AI Systems Atlas

Coding-Agent Architectures

Software is the best environment agents have: a verifier (tests) that is objective, fast and free. Every serious coding agent is built around that gift — the architectures differ mainly in how they explore, how they parallelize, and how they survive long tasks.

Index G-01 The Test / Diagnose LoopG-02 Single Agent vs Multi-AgentG-03 CI Feedback LoopG-04 Plan-first CodingG-05 Test-driven AgentG-06 Reviewer AgentG-07 Worktree ParallelismG-08 Researcher + ImplementerG-09 CheckpointingG-10 Repo Indexing & Code SearchG-11 Computer-use Coding

G-01The Test / Diagnose Loop

/coding-agents/test-loop

Understand, explore, plan, edit — then let the test suite verify, and diagnose real failures instead of guessing.

Key insight

The traceback is the highest-signal context a coding agent ever receives. Architectures that route it back into the edit step outperform ones that just retry.

Failure mode

Skipping exploration: an agent that edits before reading the codebase produces plausible patches against an imagined repo.

RelatedActor–VerifierCI feedback loopReAct loop

G-02Single Agent vs Multi-Agent

/coding-agents/single-vs-multi

One agent with full context and no coordination — or several specialists working in parallel, plus the overhead of keeping them coherent.

Key insight

Multi-agent buys wall-clock speed on cleanly-splittable work and nothing else. Coordination cost grows with coupling, and most features are more coupled than they look.

Failure mode

Splitting a coupled task: four agents each holding a quarter of the picture will confidently build four incompatible quarters.

RelatedHierarchicalParallel swarmWorktrees

G-03CI Feedback Loop

/coding-agents/ci-loop

Push, let CI verify remotely, and let failure events — with logs — wake the agent to fix and push again.

Key insight

CI extends the verifier beyond the agent’s machine: same loop as test/diagnose, but event-driven and running against the team’s real gates.

Failure mode

Poll-and-pray: agents that sleep-loop on CI status burn tokens and miss context that the failure event would have carried for free.

RelatedEvent-driven agentTest loop

G-04Plan-first Coding

/coding-agents/plan-first

Produce a reviewable plan before any edit; humans veto cheaply at the plan stage.

Key insight

The plan is the highest-leverage review surface in the loop: minutes to redirect there, hours to unwind a wrong diff.

Failure mode

Plans that are vibes: if the plan doesn’t name files and steps, approval is meaningless and drift is guaranteed.

RelatedPlan → ExecuteHuman-in-the-loop

G-05Test-driven Agent

/coding-agents/test-driven

Write the failing test first; the test then defines “done” unambiguously.

Key insight

TDD fixes the coding agent’s worst habit — declaring victory early. The agent cannot argue with a red test.

Failure mode

The agent writes a test that asserts its implementation rather than the spec: green, and wrong.

RelatedTest loopActor–Verifier

G-06Reviewer Agent

/coding-agents/reviewer-agent

A separate agent reviews the diff with fresh context, catching what the author’s context normalized.

Key insight

Author blindness is a context problem, so the fix is a context boundary — the reviewer’s power is precisely what it hasn’t seen.

Failure mode

Sharing the author’s conversation with the reviewer “for context”: you’ve rebuilt the same blind spots and doubled the cost.

RelatedGenerator–CriticTest loop

G-07Worktree Parallelism

/coding-agents/worktrees

Each agent works in its own git worktree; merge conflicts are surfaced by git, not by luck.

Key insight

Filesystem isolation makes parallel agents boring in the best way — and routes their disagreements through tooling built to resolve them.

Failure mode

Parallel agents in one working directory: silent overwrites, corrupted builds, and no record of who changed what.

RelatedSingle vs Multi-AgentParallel swarm

G-08Researcher + Implementer

/coding-agents/researcher-implementer

One agent reads the codebase and produces a digest; a second implements against it with a clean context.

Key insight

Splitting read-heavy from write-heavy work means the implementer never pays the exploration tax — its whole window is for the change.

Failure mode

A digest that omits one convention or trap: the implementer can’t know what the researcher didn’t write down.

RelatedHierarchicalRepo indexing

G-09Checkpointing

/coding-agents/checkpointing

Commit at every good state; a bad direction becomes a reset, not a restart.

Key insight

Cheap recovery changes what the agent can afford to attempt — risky refactors are rational when undo is free.

Failure mode

One giant commit at the end: when step 14 of 15 goes wrong, all fifteen are tangled together.

RelatedLong-running agentRetry loop

G-10Repo Indexing & Code Search

/coding-agents/repo-indexing

Symbol maps and semantic search turn ten rounds of grep into one hop.

Key insight

Navigation is most of a coding agent’s token bill; an index converts that recurring cost into a one-time build.

Failure mode

A stale index: confidently wrong answers about code that moved is worse than grep’s slow honesty.

RelatedResearcher + ImplementerRetrieval & RAG

G-11Computer-use Coding

/coding-agents/computer-use

The agent drives a real browser to verify UI changes — closing the loop unit tests can’t see.

Key insight

A screenshot in the loop makes “looks right” a checkable claim: vision extends the verifier to layout, styling, and flow.

Failure mode

Verifying single frames only: the bug that needs a hover, a scroll, or a second click stays invisible.

RelatedTest loopCI feedback loop

Elsewhere in the atlas

Harnesses →Security →Evals →Context →