The Claude Code harness has become the central concept of agentic development in 2026: the infrastructure that surrounds the AI model inside a coding agent. Analysis of Claude Code's source code confirms it: 98.4% of the architecture is harness, and only 1.6% is AI inference. This holds for Cursor, Codex and every AI editor, and it defines a discipline of its own: harness engineering. Designing a solid agent harness (a robust harness configuration, a secure harness environment, measurable harness benefits) is the fundamental skill of agentic coding in production. Advanced harness skills, best practices in harness design and the ability to build the working environment around a natural language model are what set the reference for reliable coding agents in the enterprise, for the whole developer community.
Claude Code harness architecture and components
Why 98.4% of Claude Code is harness (and 1.6% is AI)
The harness is not an implementation detail. It is the product. Every coding agent (Claude Code, Cursor, Codex) has to pass through a reliable harness MCP layer and harness configuration before every action. Robust feedback loops and quality gates are the precondition for reliable coding agents in production. Engineering the harness for development, not a more powerful model, is what makes the difference. The harness's error handling and automated evaluation are tomorrow's debug failures, avoided today.
The immutable agent loop: send → check → tool → loop
Whatever the framework (Claude Code, Cursor, Codex or a LangGraph-based agent), every agent relies on the same four-step loop. It is the pattern the whole coding agents community has converged on, whatever its favourite coding tool:
- Send: send the message and the available tools to the LLM
- Check: check the
stop_reasonin the model's response - Tool: if
tool_use, execute the tool and add the result to the context - Loop: repeat until the model gives its final response
The harness governs every transition in this loop. Without a harness, the agent runs with no constraints and no audit trail. With a correct harness configuration, every action goes through quality gates, permission checks and observability mechanisms. The harness spec defines this scope before each task handed to the agent.
Harness vs prompt engineering: two complementary disciplines
The harness and prompt engineering operate at different levels of the stack. An AI editor such as Cursor or Claude Code needs both, each on its own plane:
| Dimension | Prompt engineering | Harness |
|---|---|---|
| Target | What the model says | What the agent does |
| Coverage | Instructions, few-shots, context | Tool dispatch, permissions, hooks, memory |
| Effect | Quality of text responses | Reliability in production |
| Enforcement | Advisory only | Real programmatic blocking |
| Scope | Single session | Persistent architecture |
LangChain measured it: by changing only its harness, without touching the natural language model, the organisation went from 52.8% to 66.5% on Terminal Bench 2.0. A 13.7-point gain from the harness configuration alone. That is the fundamental skill: prompt engineering optimises the language model's responses, while harness engineering makes coding agents ready to industrialise. It is the difference between a prototype and a production coding assistant that handles its read/write operations reliably.
The npm leak of 31 March 2026: what the 512,000 lines reveal
A single missing .npmignore line in the npm package @anthropic-ai/claude-code v2.1.88 exposed the complete source code on 31 March 2026. The technical community discovered a harness with permission rule files, architecture spec files, internal readme files and 44 hidden feature flags.
What the leak brought to light goes well beyond the security incident. It opened Claude Code's architecture to public and academic analysis. The exposed files have become a reference curriculum for any developer who wants to create and build a production-ready harness. With Claude Code at USD 2.5 billion ARR, understanding this harness has become a strategic issue: experts who know how to build the working environment around a model get better results (better reliability, better control) than those who rely on prompts alone.
Memory: CLAUDE.md, the agent's persistent memory
CLAUDE.md is the memory layer of the harness. The file loads every time a session opens and sets out the project conventions, working instructions and business constraints the agent must respect. Its limit is fundamental: CLAUDE.md is an advisory instruction layer. It steers the model's reasoning; it does not block it. For an effective harness, every critical instruction written in CLAUDE.md must be backed by a rule in permissions.deny. The Claude Code skills referenced in this file are the reference the agent has at hand every time it starts.
Tools: the 12 fundamental action primitives
The harness exposes four families of tool to the model, whether that is Claude Opus or any other LLM. This is the taxonomy Cursor, Codex and Claude Code share for building coding agents:
- File I/O: read/write access, file modification and deletion
- Shell execution: bash commands, scripts, build processes
- Network: HTTP calls, external APIs, third-party services
- Browser: navigation, UI interactions, tests
The four teams that analysed Claude Code's harness converged on roughly 12 tool primitives. This convergence confirms that the tool set is constrained by the nature of development tasks, not by implementation choices. To run an agent in production, tool dispatch is the harness's central action vector. It is also its main risk vector. At team level, each exposed tool must be documented in the shared harness configuration repository, along with all the MCP scopes integrated into a centralised governance app.
Permissions: settings.json and the 7 authorisation modes
settings.json is the harness's permission engine. It implements 7 authorisation modes, evaluated in two stages: 64 tokens for the fast pass on unambiguous actions and 4,096 tokens for the model's reasoning path (Claude Opus on the full reasoning branch). Rule files apply in this order: allow → deny → ask. This harness configuration directly sets the agent's level of autonomy. Without explicit permissions.deny rules, the harness delegates every decision to the model. The permission spec files are the harness's security reference.
Hooks: PreToolUse / PostToolUse as automated quality gates
Hooks are the harness's programmatic gates. PreToolUse runs before each tool dispatch, PostToolUse runs after it. A hook that returns exit code 2 blocks the action. That blocking capability is what separates hooks from a logging layer. Every hook built into your harness must return exit code 2 for every action it blocks. The harness's quality gates and feedback loops run through this mechanism. Automated evaluation of agent outputs and harness review audits are implemented through these hooks, built directly into the development cycle for stronger security.
MCP Servers: extending the tool surface
MCP (Model Context Protocol) is the extension standard for the Claude Code harness. Each MCP server adds a tool surface to the agent while isolating credentials per server. The harness MCP layer lets you integrate business systems (databases, internal APIs, third-party tools) without exposing every credential to the agent. The granularity of MCP scoping is a critical harness configuration lever: an MCP server with overly broad write scopes becomes a direct attack vector. Cursor, Codex and Claude Code all implement a variant of this standard in their AI tool.
Observability: context compaction and a 76% cut in API costs
The harness's observability layer does two jobs. First, session logs: traces of every action the agent takes, which feed harness review and post-execution automated evaluation. Second, context window compaction: a 5-layer pipeline preserves cached prompts. Measured result: a 76% reduction in API costs. All modern coding agents build this pattern into their architecture: the community converged on it in 2025-2026. (MBZUAI VILA-Lab, May 2026)
Critical harness engineering mistakes
Anti-pattern 1: CLAUDE.md without permissions.deny enforcement
The most common mistake: writing detailed instructions in CLAUDE.md without enforcing them through permissions.deny in settings.json. The agent can ignore those instructions, not out of malice but because the model's reasoning optimises for the context it has, not for a conventions file with no enforcement behind it. The reference for best practices: every critical prohibition must exist in permissions.deny. CLAUDE.md documents the intent. settings.json enforces it. Example: write the instruction "never modify production files" without a matching permissions.deny, and the model ignores it.
Anti-pattern 2: plaintext API keys in the agent directory
Storing API keys in .env files that the agent can reach from its working repository creates a direct exfiltration vector. The harness environment must keep credentials out of the agent's area of action. The fix: credentials in mode 600 in paths the agent cannot access, or a dedicated secret manager. Any API key in the agent's repository is an API key the agent can read and potentially exfiltrate through a network tool. The harness's security readme files document where credentials are stored: this is essential security work at every team level.
Anti-pattern 3: hooks that log but never block (missing exit code 2)
A hook that records every action in the logs but never returns exit code 2 gives an illusion of control. Debug failures pile up in the logs while unwanted actions go through. The post-incident harness review reveals perfect observability and real damage. The rule is simple: if a hook cannot block, it does not protect. Effective error handling for agent tasks depends on programmatic blocking, not just traceability. This applies equally to Cursor, Claude Code and Codex.
Anti-pattern 4: MCP write scopes combined with overly broad Bash allowlists
Combining MCP write scopes with broad Bash allowlists creates a critical attack surface. The agent gets write access to uncontrolled paths through the MCP tools AND through the coding tool's shell commands. The harness MCP layer must follow the principle of least privilege: write scopes limited to strictly necessary paths, Bash allowlists restricted to clearly identified business tasks. MCP write plus broad Bash is the most frequent filesystem corruption vector in production, whether your preferred coding agent is Claude Code, Cursor or Codex.
Anti-pattern 5: bypass mode on production repos
Bypass mode switches off the harness checks. On an isolated development folder, using it for testing can be justified for a while. On a production repository, it is an open door. The harness engineering best practices are clear: enable full protections before any deployment. Bypass is designed for development, not for live environments. This rule belongs in the project readme, visible to every contributor, in the same way as the rule files Anthropic itself documents in Claude Code's internal spec files.
Real CVEs in the harness layer: CVE-2025-59536 and CVE-2026-21852
CVE-2025-59536 and CVE-2026-21852 document what the structural analysis confirms: attacks on coding agents go through the harness layer, not through the model's reasoning (Claude Opus or any other). The harness's quality gates are the defensive reference: building a stack with no known CVEs means updating the harness regularly, whatever the output of the underlying model. The harness engineering reference: apply patches before you change models.
| Anti-pattern | Likelihood | Severity | Remediation |
|---|---|---|---|
1. CLAUDE.md without enforcement (missing permissions.deny) | Very high | High | Every critical CLAUDE.md rule must have a permissions.deny in settings.json |
2. Plaintext API keys (.env in the agent directory) | Very high | Critical | Credentials in mode 600 outside the agent directory, or a dedicated secret manager (Vault, AWS Secrets Manager) |
3. Hooks that never block (missing exit code 2) | High | High | Every protection hook must return exit code 2 to block the action, not just log it |
| 4. MCP write + broad Bash | High | Critical | Least privilege: scope MCP write to strictly necessary paths + restricted Bash allowlists |
| 5. Bypass mode in production | Moderate | Critical | Bypass only in isolated dev, never on production repos |
| 6. Documented CVEs (CVE-2025-59536, CVE-2026-21852) | High | Critical | Update the harness as soon as patches are released: both CVEs sit in the harness layer |
Source: MBZUAI VILA-Lab (May 2026), Idun Group.
Configure your Claude Code harness in 3 levels
Level A, approval-first harness: every action requires confirmation
The approval-first pattern is the recommended entry point for sensitive repositories and regulated environments. Every tool dispatch triggers a human confirmation. The approval load is at its highest and the risk at its lowest. This harness suits projects in active production and codebases shared across teams. The approval-first harness configuration puts a human on every action the agent takes, which also makes it a continuous harness review mechanism. Cursor and Claude Code both expose this pattern natively in their coding tool. A spec file documents which tasks may run autonomously and which require human validation.
Level B, curated allow-list harness: only destructive actions require confirmation
The curated allow-list pattern defines a whitelist of actions allowed to run autonomously: file reads (read access), test runs, read-only API calls. Destructive operations trigger a confirmation. This harness works well for PoCs and staging: reliable coding agents in interactive mode work better and faster. The list should live in the repository readme so that Cursor and Codex work efficiently within that scope. An assistant configured with this pattern handles routine tasks without constant supervision.
Level C, sandboxed full-auto harness: complete isolation for overnight batch tasks
The sandboxed full-auto pattern isolates the agent in a container with restricted network rights and a filesystem bind-mounted on the authorised working folder only. The approval load is close to zero. This harness is designed for long-running batch tasks: codebase migrations, test suite generation, large-scale refactoring and autonomous agentic coding, including batch tasks such as app migrations and test generation. The sandboxed harness environment guarantees that the agent cannot reach secrets or systems outside the defined perimeter. Sandbox spec files document the execution limits of each autonomous task.
The real cost of the harness: Anthropic Labs figures (March 2026)
The harness benefits have been quantified. Prithvi Rajasekaran of Anthropic Labs published the real costs of three configurations on long-running frontend development tasks (March 2026). The V2 harness configuration (context window compaction, generator/evaluator separation) cuts API costs by 76% compared with an unoptimised session.
| Level | Configuration | Duration | Cost / session | Savings |
|---|---|---|---|---|
| No harness | Solo agent, no optimisation (no compaction, no multi-agent, no evaluator) | 20 min (short task) | 9 USD (baseline) | ref. |
| Harness V1 | Full multi-agent (generator + evaluator), sprint contracts, Playwright MCP, 3+ QA rounds | 6 h (long task) | 200 USD (20× more expensive) | +1,800% |
| Harness V2 | Optimised harness with context compaction, generator/evaluator separation, -76% API costs | 3 h 50 min (-36% vs V1) | 124.70 USD (-37.7% vs V1) | -38% vs V1 |
Source: Anthropic Labs, Prithvi Rajasekaran (March 2026). Key to the V2 optimisation: context window compaction (a 5-layer pipeline that preserves cached prompts) cuts API costs by 76% on long-running sessions. Separate evaluation (no self-assessment) raises the quality of deliverables without multiplying tokens.
With Claude Code at USD 2.5 billion ARR, optimising the harness is not an engineering luxury. It is an operational necessity for any organisation deploying coding agents at scale, whether you use Claude Code, Cursor, Codex or a custom AI tool.
From the individual harness to enterprise-wide governance
The structural limits of an individual harness at team scale
A local settings.json does not sync automatically between team members. Each developer maintains their own harness configuration in their own local repository, with no guarantee of consistency. Configurations multiply with no overall view: coding agents configured differently, missing readme files, misaligned policies. An individual harness hits its scalability limits at team level as soon as several agents run in parallel and start affecting business apps. A higher level of governance is needed for the harness for development to be applied uniformly across the organisation. That is where the AI assistant becomes a collective asset.
Policy engine, kill switch and RBAC: the components of centralised governance
The move to centralised governance rests on three core components:
- Policy engine: a rule file engine applied to every agent in the company, whatever its origin (LangGraph, N8N, Cursor, Agentforce, Claude Code)
- Kill switch: emergency stop for an agent in production, triggered in seconds
- RBAC: four roles (owner, admin, contributor, reader) that govern access to the harness configurations of deployed agents
The maturity path from the individual harness to enterprise-wide governance goes through four stages:
- Individual harness: single-agent configuration. The developer configures their Claude Code, Cursor or Codex agent through a local
settings.json.CLAUDE.mddefines the project rules. Hooks and MCP servers are enabled by the developer. (settings.json,CLAUDE.md, MCP servers, hooks.) - Team harness: standardising and sharing configurations. The team shares a repository of harness configurations (spec files, rule files, README).
CLAUDE.mdfiles are versioned. Hooks are standardised in the project repository. First shared spec files. (Shared repository, spec files, rule files, versioning.) - Platform harness: centralised multi-agent runtime. A standardised runtime exposes agents as services (one FastAPI API per agent, for example). Unified observability (OpenTelemetry, Langfuse), memory persistence (PostgreSQL), centralised guardrails. (Runtime, FastAPI, guardrails, observability.)
- Enterprise-wide governance: across every platform. Every agent in the company (Copilot, Agentforce, LangGraph, N8N, ServiceNow) is governed by a unified policy engine. Kill switch, RBAC, financial attribution, AI Act reporting and OWASP Agentic AI compliance. (Policy engine, kill switch, RBAC, AI Act.)
These components are the harness at enterprise scale. What settings.json does for one developer in their favourite coding tool, centralised governance does for every agent in the organisation.
Harness, AI Act and OWASP Agentic AI compliance 2025-2026
The AI Act requires high-risk AI systems to be brought into compliance, with the Annex III deadline postponed to December 2027. OWASP Agentic AI published its reference framework in December 2025. Both require auditable traces, a documented harness review capability and human oversight mechanisms for autonomous AI systems. A compliant enterprise harness needs immutable execution logs for every agent output, verifiable quality gates and automated reporting. The harness layer is the natural place to instrument this compliance: it is where the evidence is generated. For building a compliant system, every instruction given to the agent must be traceable and auditable.
Independent convergence: 4 teams, the same harness architecture
MBZUAI VILA-Lab, Obvix Labs, the OpenAI Codex CLI team and the open-source Aider/OpenClaw projects built their coding agents independently, each in its own repository and with its own AI tool. The result: four nearly identical architectures at every implementation level, with a model call loop, ~12 tool primitives and multi-stage permission pipelines. The researchers' conclusion is blunt: "it is not a preference, it is a constraint imposed by the problem itself." (MBZUAI, May 2026) Harness design is not a differentiator. The quality of its implementation, however, is what lets you build better coding agents: more reliable, better governed and more productive in production.
Beyond the harness: what Claude Code returns
A solid harness makes the agent reliable. It does not tell you who uses the Claude Code seats, for what, or what they produce against what they cost. Idun Group measures that real usage from the logs and exports your platforms already produce, cross-checks it with interviews, and tells you what to industrialise, consolidate or cut. The detail is on our Claude for enterprise page.
