We gave our coding agent a map. It read it, then searched anyway.

Docs: plans before code

On one of our internal projects we worked with Superpowers, a Claude Code plugin that has the agent write a design doc and a step-by-step plan before it touches any code. We committed all of them to the repo. Every decision would be written down, and the next agent could read why things were built the way they were.

That is how the workflow is meant to be used, and the docs piled up the way they always do: one spec and one plan per feature, never deleted, because each of them was true on the day it was written. By August 2026 there were 277 plan files, around 123,000 lines.

Docs: 2 million tokens of plans

Over time we noticed the agent's context was filling up before it had done any real work. When we looked into it, the plans alone came to about 2 million tokens, twice the size of the agent's whole context window. No task read all of them, but a typical plan was about 5,000 tokens and the largest 37,000, and one search across the folder could pull several in at once. Many described code that had changed since, so the agent went on to read the files they pointed at too.

Docs: we kept only what is current

On 13 August we compacted everything into one documentation folder that holds only what is current. We went through the plans for decisions worth keeping and found twelve. Eight became ADRs (Architecture Decision Records: a short note of a decision, why it was made, and what it changes). The other four became constraints in the CLAUDE.md files that load when an agent works in that part of the repo. The plan files went, and so does any ADR we later reverse: unlike the article, we delete it instead of marking it superseded; a label is easy for an agent to miss, and git keeps the history.

A decision made the cut only if it was:

• hard to reverse,
• surprising to someone who knows the stack, and
• picked over a real alternative.

The effect was immediate. Fewer tokens burned, and the agent went straight to the problem instead of browsing specs and the files they referenced.

Atlas: could a map do even better?

We wanted to be confident about why. If removing old docs helped, would the right kind of docs help more? The obvious candidate is a map: something that tells the agent where each kind of change goes, so it can skip the search.

So we built one, called Atlas:

• One markdown card per component, saying where each kind of change goes.
• An index that leads to the cards.
• Pointers in CLAUDE.md files, so the agent meets the map as soon as it starts working in a directory.
• A nightly refresh: an agent updates the cards when files are added, deleted or renamed.

Atlas: 37 tasks, 5 codebases, with and without the map

We built a benchmark of 37 tasks on 5 codebases: our private monorepo, which has never been published, plus Metabase, FFmpeg, wezterm and Hyprland. Each task ran on two identical copies of the repo, one with Atlas and one without, with the same model and the same prompt word for word in both. The model was Claude Sonnet 5 (claude-sonnet-5) on our monorepo, FFmpeg, wezterm and Hyprland, and Sonnet 5.5 (claude-sonnet-5-5) on Metabase. The agent ran in Claude Code 2.1.263 on our monorepo and 2.1.284 on the other four. All runs took place between 25 September and 5 October 2026. Metabase tasks were real bug reports with merged fixes; on the other four we wrote our own from scratch. Each says what should work, never where. The cards were generated by an agent; on our monorepo they had already been in use since August. Each task ran several times in each copy, because the same model gives different answers from run to run. 174 runs in total.

Quality was scored against real outcomes:

Cost was measured on the hunt: the tokens the agent spent before its first edit. That is the part a map is supposed to shorten.

Atlas: same quality either way

Quality was level everywhere. On Metabase both arms solved 11 of 15 bugs, the same tasks the same number of times. Elsewhere the gaps were a couple of runs either way, and they did not all point in the same direction.

Atlas: up to 65% more to find the right place

Then we looked at tokens. Runs with Atlas cost up to 65% more to find the right place, and they almost never produced a better result. Our monorepo and FFmpeg broke even; the other three cost 26 to 65% more.

Atlas: why the map did not pay

The agent read the map and then searched anyway. It opened the index, read a card or three, and ran its usual searches after that. Searches before the first edit went from 10.5 to 17.5 on Hyprland. FFmpeg was the exception: fewer searches, but more files opened, at the same price.

Everything it read stayed in context. On Metabase the index plus one card is 18,000 to 27,000 characters, re-sent with every later request. Median context over a run: 444,000 tokens with the map, 314,000 without.

The layout was already the map. On wezterm the crate names (wezterm-font, config, pty) already say where each kind of change goes, and without Atlas the agent often found the place in a couple of tool calls.

Finding the place was never the bottleneck. On Metabase, 12 of 15 runs in both arms edited exactly the file the real fix changed; the failures were wrong fixes in the right file. On our monorepo a typical run spends 5 to 10 million tokens finding the place and 50 to 150 million doing the work. Even a perfect map can only trim that slice.

Atlas: the scope of this test

• Claude Sonnet in Claude Code, the setup we use daily. Other models may use a map differently.
• Atlas as it comes from its installer.
• 37 tasks across five codebases, 2–3 runs each. Clear on direction, less precise on exact numbers.
• Real bug reports on Metabase, tasks we wrote ourselves on the other four.

What we do now

Keeping your own documentation for the agent makes little sense beyond ADRs and things that are truly unusual. The agent already knows how a React app, a Rust workspace or a Go service is laid out, and it will run the greps anyway. Every line it reads on top of that is paid for again on every request after it.

So we write down only what differs from the standard: a short ADR, or a constraint in the CLAUDE.md next to the code it governs. Non-obvious wiring, like registration points and generated code, gets one line by hand. On FFmpeg, the map's clearest win was a card that named exactly that, a registration point. One line in the right CLAUDE.md does that job without a whole map around it.

What's next

This is only the start of our work on cutting token use, and more stories will follow. If you are measuring something similar in your own repos and want to compare notes, get in touch.