A Short Map Beats a Long Manual

Part 9 ended on a rule and a tension. The rule: keep the always-loaded file small, constraint-shaped, and free of implementation description. The tension: repositories grow, and a repository at real scale has more genuine constraints, more conventions, more territory than any small file can hold. Something has to give — either the file grows until it floods the context window before the agent has done any work, or it stays small and the agent wanders a codebase it knows nothing about. Both options are bad, and the way out is neither. The way out is to stop thinking of the file as a manual and start thinking of it as a map.

The tension every root file faces

A manual tries to contain the knowledge. A map tells you where the knowledge lives. The distinction sounds like wordplay until you price it in tokens: part 6 made the case that a context window is a budget, and that quality degrades as you fill it. Every line of the root context file is spent before the agent reads the first line of the actual task. A two-thousand-line manual does not make the agent twice as informed as a hundred-line map — it makes the agent start every session with a substantial slice of its best attention already consumed by material that is mostly irrelevant to the task at hand.

The map model spends differently. It holds the constraints that apply everywhere, the commands that run everything, and pointers — this is where the API conventions live, this is where the data-access rules are documented, this is the file that defines the public contracts. The agent pays a few hundred tokens for orientation, then pays for depth only in the direction the task actually goes.

Shard the map down the tree

The mechanism for this is progressive disclosure, and it falls out of a property most agent tooling already has: context files can live at any level of the directory tree, and the agent picks up the ones on the path to wherever it is working. The root file carries what is true everywhere; each region of the repository carries what is true only there.

For Meterly — the invented billing service from part 9 — the sharded layout looks like this:

meterly/
  CLAUDE.md            # constraints true everywhere; commands; pointers
  src/
    api/
      CLAUDE.md        # versioning rules, error envelope, auth boundaries
    billing/
      CLAUDE.md        # posting-service rule in depth, money invariants
    connectors/
      CLAUDE.md        # rate limits, retry policy, sandbox credentials note

An agent fixing a connector bug loads the root map plus the connector rules — and never pays for the billing invariants it does not need. An agent working on the posting path gets the money rules in full. Each regional file obeys the same discipline as the root: constraints and conventions, not module tours. The effect is that total documented knowledge can grow with the repository while the amount any single session carries stays roughly constant. The context file stops being a document and becomes a routing structure.

The failure mode to watch is duplication. The moment the same rule appears in the root file and two regional files, you have three copies to keep synchronised and a poisoning hazard when they disagree. A rule lives at exactly one level — the highest level at which it is universally true — and everything below refers upward rather than restating.

One million lines, one hundred lines of map

The strongest published evidence that this scales further than intuition suggests comes from OpenAI. In their engineering post “Harness engineering: leveraging Codex in an agent-first world”, they describe a team of three engineers who built a production application of roughly a million lines of code over five months — around 1,500 pull requests, an average throughput of 3.5 merged PRs per engineer per day, with every line written by Codex and none by hand. (The post itself is the primary source; InfoQ's summary is a useful secondary account of the same figures.)

The detail from that write-up that belongs in this part: the root AGENTS.md steering all of that work was kept to roughly a hundred lines. A hundred lines of map for a million lines of code — a ratio of one to ten thousand — with the file pointing at deeper sources of truth in the repository rather than trying to contain them, and precise file references standing in for copied explanations. The post distils the team's experience into seven key lessons, and I would rather send you to their own wording than flatten it here; the title of this part is my one-line compression of the lesson I think matters most.

What I take from the case, as my own distillation of their post rather than their list:

1. Give the agent a map, not a manual — a short root file whose job is orientation and pointers, not coverage.
2. Make the repository the single source of truth — decisions that live in chat threads, wikis or heads are invisible to the agent; push them into the repo as markdown, schemas and plans.
3. Encode opinionated, mechanical rules — the kind a machine can follow without judgement, which keep a codebase legible to the next hundred agent runs.
4. Enforce verification, don't request it — wire checks into the workflow as gates the agent cannot finish without passing, rather than instructions it might skim.
5. Hand-write the map — the root context file is the highest-leverage artefact in the whole harness, which is precisely why generating it automatically is a false economy.

Five points, and every one of them is a harness decision rather than a model decision. Which raises the obvious question: how much can harness decisions alone actually be worth?

The run that isolated the variable

LangChain answered that question about as cleanly as it can be answered, in a February 2026 write-up of taking their coding agent up the Terminal Bench 2.0 leaderboard. Their score moved from 52.8 to 66.5 — 13.7 points, from Top 30 to Top 5 — and the sentence that makes the result matter is theirs: “We only tweaked the harness and kept the model fixed.”

Same model, same benchmark, same tasks. Everything that changed was the machinery around the model — the environment, tooling and context delivery this series has been calling the harness. Thirteen points is the sort of gap teams routinely wait for a next-generation model to close, and here it was closed by engineering work on infrastructure that already existed. The harness was the bottleneck, and the harness is the part you control. You cannot retrain the model this quarter; you can absolutely rewrite a hundred-line map, shard your context files, and turn your verification steps into gates.

Drawing your own map

The pattern travels. Whether the repository is a million lines or fifty thousand, the same moves apply, in the same order:

• Shrink the root file to a map — constraints true everywhere, the commands, and pointers to where depth lives. If a section describes rather than directs, it moves out.
• Shard by region — put local rules where the work happens, each rule at the highest level where it holds, no duplicates.
• Prefer references to copies — a path and a line number stay true longer than a pasted snippet, and they cost a fraction of the tokens.
• Let the benchmark thinking in — before wishing for a better model, ask what a fixed-model, better-harness experiment would change first in your own setup. That question is nearly always cheaper to answer than it looks.

A short map, disciplined constraints, enforced gates: at this point in the series the agent knows what to do, knows the territory, and cannot ship unverified work. What none of that machinery answers is whether the work is aimed at the right target — an agent can execute flawlessly against goals the organisation stopped holding a quarter ago. Next, the discipline that failure names, and the most instructive public example of it: intent engineering and the Klarna lesson.