Coding-Agent Architectures

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.

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.

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.

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

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

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

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

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

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

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

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

This is the most consequential mechanism in coding agents and the least discussed. Whole-file rewrites can never fail to apply and can silently delete; anchored edits can fail to apply and never silently delete. Prefer the failure you can see.

The test loop draws one verifier; in practice it is a ladder, and the ordering is the design. Most iterations never leave the bottom three rungs, which is what makes an agent that edits fifty times an hour affordable.

Put in it what is expensive to discover and cheap to state: the build command, the generated directory, the pattern that looks fine and breaks production. Because it is in the tree, it changes through review, like the code it describes.

Worktrees make isolation cheap, which is the easy half. The merge is the hard half, and it needs a role: one integrator holding both changes, rather than a conflict bounced between authors who have each seen only their own.

Autonomous coding runs fail here more than anywhere else, and never on the interesting part. A setup script in the repo, exercised by CI, turns the most common failure into one that breaks in a pull request instead of at 3am.

The unit of work changes from a conversation to a pull request. The human stops supervising steps and starts reviewing results, and CI failures and review comments, not a watching person, are what wake the agent back up.

An instruction is a request the model weighs against everything else in its window; a hook is code that runs at the moment itself. Anything that must happen every time, such as formatting, a blocked path or tests before “done”, belongs in a hook.

Grep answers “where does this string appear”; a language server answers “what refers to this symbol”. Diagnostics pushed after every edit add a type check to each change, seconds before any test could run.

Once agents write most of the diffs, review is the bottleneck, so the design goal is a cheap review: small scoped PRs, a summary with evidence attached, and a reviewer bot for the first pass. The trajectory is the cheapest evidence there is.