Architecture Design

Conclusion first: the value of multi-agent doesn’t come from more models; it comes from the right structure. Multi-agent without structure is just more expensive concurrency — burn 2 to 3 times the tokens to watch a group of models nod at each other. Multi-agent with structure is an execution system that can delegate, parallelize, and verify. Why a Single Agent Fails at Long Tasks # Diagnosis first. A single agent executing complex tasks has five structural defects — blame the execution structure, not the model’s intelligence:

The claude-code-from-scratch project implements a “mini Claude Code” in roughly 3,000 lines of TypeScript. It has the Think-Act-Observe loop, a tool system, a system prompt, permission control, memory, Skills, multi-agent, MCP — every core concept we tore down over the previous ten posts. And the official Claude Code source? Roughly 500K lines of TypeScript/TSX. That’s a 100x+ gap between 3,000 lines and 500K. What’s in it? The gap isn’t “number of features”. from-scratch already covers every core concept. The gap is the road each concept travels from “it runs” to “it’s usable” — that road is called productionization.

Autoregressive large language models operating in unconstrained environments suffer from an inherent tendency toward myopic mutation and runaway divergence. Claude Code’s Plan Mode attaches an external discrete Finite State Machine (FSM) that projects the action space onto a strictly side-effect-free subset, using an interactive human barrier to prune catastrophic physical backtracking branches from the decision tree. In disciplined software engineering, experienced developers instinctively value structural planning: mapping dependency graphs, deriving type signatures, and scoping blast radiuses before modifying a single line of code. Large language models possess no such innate restraint. Shaped by reinforcement learning to generate immediate answers, an agent granted unrestrained write permissions will instinctively mutate files without global context, precipitating an architectural cascade across complex repositories.

There’s a counterintuitive phenomenon: take the same model, split it into multiple independent instances, and have them collaborate — the result is often better than a single instance. Not more compute (three instances burn more total tokens than one), not more capability (every instance is the same model). The gain comes from role separation — when each agent attends to only one facet of the problem, it works with more focus and more depth than a “do-everything agent”.

Last time we talked about the Think-Act-Observe loop — the skeleton of an AI coding assistant. A skeleton can’t work on its own; it needs muscle. In Claude Code, that muscle is tools. Without tools, the loop loses the Act between Think and Observe and degenerates into plain Q&A. With tools, the model can touch the real world: read your code, change your configs, run your tests.

If you dig through the Claude Code source, you will discover a counterintuitive fact: The core of the entire program is a while loop. Not a complex state machine, not an elaborate pipeline, not distributed coordination — just a plain while loop that does three things over and over: let the model think, let the model act, feed the results back. 1 2 3 4 5 6 7 8 9 while (user hasn't quit) { thinking = callLLM(conversation history + tool definitions) if (thinking.wants to call a tool) { result = executeTool(thinking.toolCall) conversationHistory.push(result) } else { output(thinking.reply) } } That’s it? The entire secret of an AI coding assistant lives in this loop?