Build a Claude Code Enterprise Harness

An agent that writes code is a demo. An agent fleet you can trust on a million-line codebase is a harness — and a harness isn’t a feature you turn on. It’s a composition of primitives, every one of them a plain file that lives in your repo and rides through code review like any other source.

This is the hands-on build. We’ll assemble a Claude Code enterprise harness from its seven building blocks, wire them into an orchestrator → researcher → implementor → reviewer loop, and — most importantly — internalize the one distinction that separates a governed setup from a toy: context versus configuration. This is part of our series on running agentic loops around serious codebases.

🏛️ The Seven Primitives

Everything below is a file on disk, checked into version control, improved by the whole team through pull requests:

1. CLAUDE.md + .claude/rules/ — always-loaded rules and project memory (the constitution).
2. Subagents (.claude/agents/*.md) — isolated, tool-restricted workers with their own context window (the workforce).
3. Skills (.claude/skills/<name>/SKILL.md) — reusable procedures that double as slash commands (the playbooks).
4. Hooks (settings.json lifecycle handlers) — deterministic code that fires on events (the enforcement layer).
5. Scripts — the ordinary bash/PowerShell/Python that hooks and skills call (the muscle).
6. MCP servers (.mcp.json) — connections to Jira, GitHub, databases, monitoring (the senses and hands).
7. Settings & permissions (settings.json) — least-privilege allow/deny/ask rules (the guardrails).

🧭 The One Idea That Governs Everything: Context vs. Configuration

Before a single file, absorb this, because it decides where every rule you write belongs:

CLAUDE.md and skills are context — probabilistic guidance the model may or may not follow. Hooks and permissions are configuration — deterministic rules the client enforces regardless of what the model decides.

A serious harness uses context to steer and configuration to guarantee. If a rule is a preference (“prefer functional components”), it’s context — put it in CLAUDE.md. If a rule must always hold (“never touch main“, “always lint on save”, “never read .env“), it is not a suggestion — it belongs in a hook or a permission rule. The official docs say it plainly: to block an action regardless of what Claude decides, use a PreToolUse hook, not a line of prose.

Building the harness is the discipline of sorting every requirement into one bucket or the other. Get this wrong and you’ll write beautiful CLAUDE.md rules that the model politely ignores at the worst moment.

📜 The Constitution: CLAUDE.md and Rules

CLAUDE.md is markdown loaded in full at the start of every session. It has scopes that stack from broad to specific — an org-managed policy file, your personal ~/.claude/CLAUDE.md, the project’s committed ./CLAUDE.md, and a gitignored ./CLAUDE.local.md for personal tweaks.

For a large monorepo, three tools keep it sane:

• .claude/rules/*.md — modular, one-topic-per-file rules (testing conventions in one file, API rules in another), loaded at the same priority as the project CLAUDE.md.
• Path-scoped rules — a paths: frontmatter glob so a rule for src/api/**/*.ts loads only when Claude touches those files, keeping context lean.
• A hard length budget — keep each CLAUDE.md under ~200 lines. Longer files measurably reduce adherence and burn context every session. Move procedures into skills; move file-specific rules into path-scoped rules.

The golden rule of the constitution: put facts every session needs here; put everything else where it loads on demand.

🤖 The Workforce: Subagents

A subagent is a named Claude instance with its own context window, its own system prompt, a specific tool allowlist, and independent permissions — defined as a markdown file with YAML frontmatter, where the body is the system prompt.

Three properties make subagents the backbone of the loop:

• Context isolation. A subagent starts fresh — it doesn’t inherit the parent’s conversation or the files it already read. When the orchestrator sends a researcher to “find every call site of chargeInvoice,” the researcher burns its own window thrashing through the code and returns a compact summary. The verbose search output never pollutes the main thread. (This is also why a symbol-retrieval tool like Serena pays off inside each agent.)
• Constraint enforcement. A tools allowlist and disallowedTools denylist narrow capability. A reviewer defined with tools: Read, Grep, Glob, Bash literally cannot write files — the safety is structural, not behavioral.
• Cost control. Route cheap tasks to a cheap model (model: haiku); let heavy reasoning inherit the main model.

A minimal reviewer agent (.claude/agents/reviewer.md):

---name: reviewerdescription: Expert code review specialist. Use immediately after writing or modifying code.tools: Read, Grep, Glob, Bashmodel: inheritmemory: project--- You are a senior code reviewer. When invoked, run `git diff`, focus on themodified files, and report Critical / Warning / Suggestion findings with concretefix examples. Consult your agent memory for patterns you've seen before.

Give an implementor its own isolated checkout with isolation: worktree so parallel workers never collide, and restrict which agents an orchestrator may spawn with a scoped Agent(...) allowlist.

🧩 The Playbooks: Skills

A skill is a directory with a SKILL.md entry point. Its frontmatter description tells Claude when to auto-load it; its directory name becomes a /slash-command. The economics are the point: a skill’s description is always in context so Claude knows it exists, but its body loads only when invoked. Long reference material costs almost nothing until used — the opposite of CLAUDE.md.

That’s progressive disclosure: facts every session needs go in CLAUDE.md; procedures go in skills. A run-tests skill can even fork itself into a subagent so verbose test output stays out of your main window:

---name: run-testsdescription: Run the suite and report only failing tests. Use after code changes.context: forkallowed-tools: Bash(npm test *)--- ## Results!`npm test` ## TaskSummarize only the failing tests and their errors. If all pass, say so.

For anything with side effects — /deploy, /commit — set disable-model-invocation: true so the model can’t fire it just because the code “looks ready.”

🪝 The Enforcement Layer: Hooks

Hooks are handlers that fire at fixed lifecycle points, and they are everything CLAUDE.md cannot be: deterministic. The ones a harness leans on:

• PreToolUse — fires before a tool runs and can block it (exit code 2), approve it, or even rewrite its input. This is your strongest guarantee.
• PostToolUse — fires after an edit succeeds; the home of lint-on-edit and format-on-edit. It can’t undo the action, but its output feeds back to Claude to fix.
• Stop — can prevent the agent from finishing (exit 2), which is how you enforce “tests must be green before you’re done.”

The canonical guard — a PreToolUse script that blocks destructive SQL — reads the tool input on stdin and exits 2 to deny:

#!/bin/bashINPUT=$(cat)COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|ALTER)\b' >/dev/null; then  echo "Blocked: read-only queries only" >&2; exit 2fiexit 0

Wire it in settings.json alongside a PostToolUse linter and a Stop-on-red-tests gate. (On Windows, write the script in PowerShell and set shell: powershell.) Beyond command scripts, hooks can also call an HTTP endpoint, an MCP tool, or even a subagent to verify an action — but a shell script covers most enterprise guardrails.

🔌 The Senses and Hands: MCP

MCP servers connect the loop to the systems where work actually lives — Jira for the ticket, GitHub for the PR, Postgres for the query, Sentry for the error. Commit a project-scoped .mcp.json so the whole team shares the same connections:

{  "mcpServers": {    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },    "jira":   { "type": "http", "url": "https://mcp.atlassian.com/mcp" }  }}

At enterprise scale the load-bearing feature is tool search: only tool names load at startup, and full schemas are fetched on demand when a task needs them. That means you can wire in a large fleet of MCP servers with minimal hit to your context window — and you can scope a noisy server to a single subagent so its tool descriptions never touch the main conversation.

🔐 The Guardrails: Permissions

settings.json permissions are allow, deny, and ask arrays using a ToolName(pattern) syntax. This is where least privilege becomes real:

{  "permissions": {    "allow": ["Bash(npm run test:*)", "Read(./src/**)", "Edit(./src/**)"],    "deny":  ["Read(./.env)", "Read(./secrets/**)", "Bash(curl:*)"],    "ask":   ["Write(./infra/**)"]  }}

Rules merge across scopes, so an org can ship a baseline deny list that no project can weaken. Treat bypassPermissions mode as a loaded gun — it skips prompts and permits writes to sensitive paths, and a parent session’s bypass overrides its children.

🔁 How It All Composes Into a Loop

Snap the primitives together and the loop from the cornerstone becomes real:

• CLAUDE.md + rules give every agent the same constitution.
• The orchestrator delegates research to a read-only researcher (cheap model), hands a plan to an implementor working in an isolated worktree, then a read-only reviewer critiques the diff.
• Skills are the reusable verbs each agent calls (/run-tests, /commit).
• Hooks enforce the invariants nobody may violate — lint on edit, no secrets, no finishing on red tests.
• MCP pulls the ticket and opens the PR.
• Permissions keep every agent least-privilege.
• The human governs at the PR boundary — review, not typing, is where architecture is steered.

⚠️ Pitfalls That Bite Real Teams

• Trusting CLAUDE.md as enforcement. It’s guidance, not a guarantee. Anything that must hold belongs in a hook or permission rule.
• A bloated CLAUDE.md. Over ~200 lines and adherence drops while every session pays the context tax. Split into path-scoped rules and skills.
• Fat subagent returns. A subagent’s summary re-enters the main window — instruct workers to return only what’s needed, or you forfeit the isolation you paid tokens for.
• bypassPermissions as a convenience. It’s how you accidentally let an agent write to .git. Reserve it for sandboxes.
• Autonomous side effects. Any deploy/send/publish skill needs disable-model-invocation: true.

❓ Frequently Asked Questions

What is a Claude Code enterprise harness? A version-controlled composition of Claude Code primitives — CLAUDE.md rules, subagents, skills, hooks, scripts, MCP servers, and permissions — that turns a single coding assistant into a governed, least-privilege agent fleet your team improves through PRs.

Where’s the line between CLAUDE.md and hooks? CLAUDE.md is guidance the model may follow; hooks are code the client enforces. Preferences go in CLAUDE.md; invariants that must always hold go in hooks or permissions.

Do subagents share the main context window? No — each has its own window and starts fresh. That isolation is the point: exploration stays quarantined and the main thread stays lean.

How do I stop an agent from finishing with failing tests? A Stop hook that exits 2 while tests are red — the agent can’t declare done until the gate passes.

Does adding lots of MCP servers blow up my context? Not with tool search on: only names load upfront and schemas are fetched on demand, so large MCP fleets stay affordable.

📚 Further Reading

• The Agentic Development Loop, Explained for Senior Engineers — the loop this harness is built to run.
• Serena MCP: Give AI Coding Agents a Real Memory — keep each agent’s context cheap and precise.
• Claude Code documentation — the authoritative reference for subagents, skills, hooks, MCP, and permissions.

Part of the “Agentic Loops for Enterprise Codebases” series. Next: how to keep quality and readable patterns from decaying once agents are writing most of the code.

---

📦 Recommended Reading

Wiring up the primitives is the easy part; the judgment to govern them is the career skill. These pair well with building a harness you’ll trust:

📘 Books for Building With AI Agents

1. AI-Assisted Programming — Tom Taulli (O’Reilly) – A practical guide to shipping software with AI tools and agents — the working context for everything in this article.

1. The Pragmatic Programmer — David Thomas & Andrew Hunt (20th Anniversary Edition) – The design judgment you spend your attention on once the harness handles the typing.

1. Refactoring — Martin Fowler (2nd Edition) – When agents generate the diffs, reading and reshaping code becomes the core skill. This is the canonical text.

---

✅ Pro tip: Check your .claude/ harness into version control and review it in PRs like any other code — that’s how a team’s agents actually get better over time.