Claude Code Harness Engineering and Configuration

This guide shows you how to turn Claude Code from a capable coding assistant into a repo-specific engineering harness with instructions, permissions, hooks, skills, subagents, MCP, and verification.

Who this is for

Use this if you already run Claude Code and want repeatable results across a real repository. The goal is not more prompting. The goal is a small operating layer around Claude Code that gives it the right context, blocks the wrong actions, routes repeated work into reusable tools, and proves the result before you trust it.

You need:

• Claude Code installed and authenticated.
• Permission to add or edit CLAUDE.md, .claude/settings.json, .claude/skills/, and .claude/agents/.
• At least one validation command, such as lint, tests, typecheck, build, or a browser smoke test.
• A git branch or worktree for changes.

Expected result: a starter Claude Code harness that a teammate can clone, inspect, and improve without relying on a transcript from your machine.

Define harness engineering in Claude Code

Harness engineering is the work of designing the environment around the agent loop. Claude Code already knows how to read files, edit code, run tools, ask for permission, and continue after tool results. Your harness decides what the agent sees first, what it can do without asking, which workflows load on demand, which external systems are available, and which checks must pass before a task is called done.

A useful Claude Code harness has six layers:

1. Stable repo context in CLAUDE.md.
2. Permission and sandbox policy in settings.
3. Deterministic hooks for checks and blocks.
4. Skills or custom commands for repeated procedures.
5. Subagents for fresh-context work.
6. MCP or plugins for shared external capabilities.

Do not start at layer six. A repo with no test command in CLAUDE.md usually does not need three MCP servers yet.

Start with a minimal setup

The minimal setup is small enough to review in one sitting. It gives Claude Code the repo map, exact checks, safe default permissions, and one place to put repeated workflows.

.
|-- CLAUDE.md
|-- .claude/
|   |-- settings.json
|   |-- hooks/
|   |   `-- validate-edits.sh
|   |-- skills/
|   |   `-- release-check/
|   |       `-- SKILL.md
|   `-- agents/
|       `-- code-reviewer.md
|-- docs/
|   `-- agent-runs/
`-- package.json

# CLAUDE.md
 
## Project map
- Next.js app router site.
- Routes live in app/.
- Shared logic lives in lib/.
- Reusable UI lives in components/.
- Generated output lives in out/ and must not be edited.
 
## Setup
- Install: npm install
- Dev server: npm run dev
 
## Checks
- Lint: npm run lint
- Test: npm test
- Build: npm run build
 
## Working rules
- Read the nearest domain docs before editing that area.
- Keep edits scoped to the requested outcome.
- Do not change auth, payments, secrets, migrations, deploy scripts, or generated files without explicit approval.
- Before completion, report changed files, checks run, and remaining risk.
 
## Routing
- Use .claude/skills/release-check/SKILL.md for release readiness work.
- Use .claude/agents/code-reviewer.md for fresh review of non-trivial diffs.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint *)",
      "Bash(npm test *)",
      "Bash(npm run build *)",
      "Bash(git status *)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(npm install *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-edits.sh"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
set -euo pipefail
 
payload="$(cat)"
file_path="$(printf '%s' "$payload" | jq -r '.tool_input.file_path // empty')"
 
case "$file_path" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$file_path"
    npm run lint -- --file "$file_path" >/tmp/claude-lint.log 2>&1 || {
      tail -n 40 /tmp/claude-lint.log >&2
      exit 2
    }
    ;;
esac

Move repeated work into a skill

A skill is better than a long CLAUDE.md section when the instruction is procedural. The description is the trigger surface. Keep it specific so Claude loads the skill only when it fits the task.

---
name: release-check
description: Use before merging or publishing a web app change that needs lint, tests, build, preview review, and a short risk note.
allowed-tools: Bash(npm run lint *) Bash(npm test *) Bash(npm run build *) Bash(git diff *) Bash(git status *)
---
 
# Release check
 
Run this procedure before saying a change is ready.
 
1. Inspect the current diff.
2. Run lint, tests, and build.
3. If the app has a UI change, start the preview and inspect the route.
4. Summarize changed files, validation commands, failed checks, and remaining risk.
5. Do not commit unless the user asks.

Add subagents with narrow roles

Use a subagent when the side task would flood the main context or when the implementation needs a fresh reviewer. Avoid vague roles such as "senior engineer" because they do not tell Claude when to delegate or what evidence to return.

---
name: code-reviewer
description: Use after a non-trivial implementation to review the current diff for correctness, regressions, missing tests, and unsafe changes.
tools: Read, Grep, Glob, Bash
---
 
Review only the current diff and directly related files.
 
Report findings as:
- severity: P0, P1, P2, or P3
- file and line when available
- evidence from the code
- suggested fix
 
Do not rewrite the code. Do not comment on style unless it hides a bug.

Expand to a production setup

The production setup is not bigger for its own sake. It adds ownership and proof:

• CLAUDE.md stays short and imports deeper docs only when useful.
• .claude/settings.json denies secrets, destructive commands, and production paths by default.
• Hooks enforce deterministic checks and never hide their failures.
• Skills hold release, incident, migration, and review procedures.
• Subagents separate research, implementation review, test repair, and security checks.
• MCP servers are pinned, documented, and limited to workflows with repeated external state.
• Worktrees isolate long-running or parallel work.
• Verification evidence is written to docs/agent-runs/<task>.md for long tasks.