AI Coding Agents Architecture: Why the Harness Matters More Than the Model
Most teams comparing AI coding tools ask one question: which model is smartest? That question matters less than it did a year ago. Every major lab now ships a model and an agent harness, and the harness decides whether an agent is safe, affordable, and actually finishes work. This guide explains AI coding agents architecture in plain terms and gives you a way to audit your own setup.
What an AI coding agent actually is
An AI coding agent is a model plus a harness. The model reads code and proposes the next step. The harness is everything else: the loop that keeps the agent running, the tools it can call, the context it sees, the permissions that limit it, and the place it runs.
Research on production systems now uses this split as the core abstraction. A source-code study of eleven coding harnesses, including Claude Code, Codex CLI, Gemini CLI and Aider, maps the same seven subsystems across them. The study describes and compares how these harnesses are built; it does not rank them. A better harness is not automatically a better product for your team.
The model supplies judgment
The model decides what to change and whether a test failure matters. Upgrading it improves reasoning, but not the guardrails around it.
The harness supplies everything else
The harness controls tool access, context budget, permissions and orchestration. When an agent deletes the wrong directory or runs out of context halfway through a refactor, the cause is usually the harness, not the model.
The seven subsystems of a coding-agent harness
Harnesses differ in detail, but the same parts recur: the agent loop, tool definitions, context management, safety controls, orchestration of parallel workers, extension surfaces, and persistence. If you evaluate a tool, check each subsystem rather than comparing benchmark scores, because no shared leaderboard for agent harnesses exists yet.
Loop, tools and context management
The loop decides when the agent stops. Tools define what it can touch. Context management decides what the model sees on each turn. Of these, context is the one teams most often misconfigure.
Safety controls and orchestration
Safety covers permissions, hooks that run around actions, and sandboxing. Orchestration covers how multiple workers run in parallel and how their results merge. For the control-plane view, see AI coding agent orchestration control plane.
Context economy: the new bottleneck
Recent releases make the point clearly. Claude Code's October 2026 updates let it read an entire oversized file in one call instead of chunking reads, and let subagents auto-compact earlier than the main conversation through an autoCompactWindow setting. These are context-budget fixes, not intelligence upgrades. If cost per solved task is your metric, the cheap subagent architecture shows how the same economics apply.
Reading large files in one call
Chunked reads fragment reasoning and burn tokens on overlap. A single full read keeps the file coherent, at the cost of a larger single context load. Choose based on file size and how tightly the agent must reason across it.
Subagents that compact on their own schedule
A subagent doing a narrow task does not need the parent's full history. Letting it compact early keeps the parent thread clean and the subagent cheap. For long sessions, set compaction per subagent rather than globally.
Isolation and safety: fail-closed hooks and worktrees
When agents run unattended, the question shifts from "can it code?" to "what can it break?" Three recent changes address this directly.
Managed git worktrees for parallel agents
Codex shipped managed git worktrees, so parallel agents work in isolated copies instead of colliding in one checkout. This is the cleanest way to run two refactors at once without merge conflicts.
Blocking hooks and pre-delete guardrails
Claude Code's hooks can now fail closed: a hook that cannot start, times out, or exits unexpectedly blocks the action instead of silently passing. Cursor's CLI halts before a recursive delete. Both encode the same rule: a silent failure in a safety check is worse than a blocked action you can retry. The attack surface this closes is covered in the permissions attack surface and the hooks fail-closed write-up.
Configuration is the real control surface
A study of 2,853 GitHub repositories found eight configuration mechanisms across Claude Code, Copilot, Cursor, Gemini and Codex. Most repositories use only the simplest one: static context files. AGENTS.md has emerged as an interoperable format across tools.
Context files and AGENTS.md
Start here. A short AGENTS.md describing build commands, test commands, and forbidden paths does more than most elaborate setups.
Why teams under-use skills and subagents
Advanced mechanisms such as skills and subagents remain rare in practice. The likely reason is setup cost, not lack of value. Add them once your context file is stable and you find yourself repeating the same multi-step procedures.
How to audit your own agent setup
Use this four-point check on any coding agent you deploy:
- Context: Is there a committed context file that states build, test and forbidden areas?
- Budget: Do long sessions compact, and do subagents have their own compaction limits?
- Isolation: Do parallel agents work in separate worktrees or branches?
- Failure mode: When a hook or safety check fails, does the action block?
If any answer is no, fix that before adding capability. Tests that pass are not the same as correct code, so pair this audit with AI code review beyond passing tests.
Where the evidence is still thin
Most published numbers come from vendors or single case studies. A reported 25–40× productivity gain on one document-conversion library, built by one engineer, is an estimate, not a controlled result. Treat vendor speed and cost claims as starting points and measure on your own repositories.
Frequently asked questions
What is an AI coding agent? An AI coding agent is a language model combined with a harness: a loop, tools, context management, permissions and orchestration that let the model take actions in a codebase.
Why does the harness matter more than the model? The model reasons; the harness determines what it can access, how much context it sees, and whether unsafe actions are blocked. Most production failures trace to the harness.
What is AGENTS.md? AGENTS.md is a plain-text context file that tells coding agents how to build, test and work within a repository. It is becoming a shared format across tools.
Should I use git worktrees for AI agents? Yes, when running parallel agents. Worktrees give each agent an isolated copy, preventing collisions in one checkout.
How do I compare Claude Code and Codex architecture? Compare the seven harness subsystems: loop, tools, context management, safety, orchestration, extensions and persistence. Test each on your own repository, since no standard benchmark for harnesses exists yet.
Related reading
Coding Agent Harness Explained: The 7 Parts That Decide Safety
A coding agent is a model wrapped in a harness. The harness sets what the agent can read, run and change. Here are the seven parts that decide safety and cost, and how to check each one.
AI Coding Agent Security: Risks Your Approvals Miss
Approval answers whether a vendor is trustworthy, not what the agent can do with your credentials. Here is the real attack surface and a control ladder to act on this week.
AI Coding Agent Orchestration: The 2026 Control Plane
October 2026's biggest agent releases were not model upgrades. Cursor moved tool execution onto customer machines, Anthropic split cloud sessions from Remote Control, Devin shipped eight parallel sessions, and Codex turned its CLI into a task board. Here is the architecture behind the shift — and the five questions that decide whether a fleet is useful or just busy.