Don't write your CLAUDE.md yourself · structuring-agent-docs

">

Don't write your CLAUDE.md yourself

Erik Wistrand · July 2026 ·<br>structuring-agent-docs

Don't write your CLAUDE.md yourself. I don't know why people think they<br>should, but the idea is everywhere: either you hand-write the file like it's a<br>craft, or you paste in the "ultimate template" from some insanely long blog post<br>and hope. My colleagues do both. Both miss what the file is. It's the agent's<br>working memory, and the agent should be the one writing it.

The hand-writers do have<br>a study on their side: generated<br>context files make agents worse. However, the files it measured were one-shot<br>/init dumps that restated what the agent could already find in the<br>repo, and the official fix, refining the dump by hand, only fails slower: the<br>human refines once and stops, and the file drifts as soon as the code moves.<br>What matters is who maintains the file, not who drafts it.

I got here from a repo that had no chance of fitting in one CLAUDE.md, working<br>in plan-implement-fix loops: the agent writes a plan doc, implements against it,<br>fixes what broke, and the plan gets promoted to an architecture doc once it's<br>real. I never wrote those docs. The agent wrote them for its own future sessions,<br>which start with no memory of anything. The surprise was how well that loop<br>worked. The docs stayed current because the same process that changed the code<br>changed them, and reviewing a doc diff takes less time than writing the doc.

So the useful question is not what you should write. It's what rules the agent<br>needs so the docs it keeps stay usable. That's what I put in the<br>skill:

project/<br>├── README.md # humans: what, why, quick start<br>├── CLAUDE.md # agent entry point (AGENTS.md symlinks here)<br>└── agent_docs/ # one topic per file, loaded on demand<br>├── architecture.md<br>└── gotchas.md

Every agent_docs/ file is linked from the entry point with a<br>plain markdown link, one level deep. The agent loads the skill when it sets the<br>docs up and every time it touches them afterwards.

Most of the rules are obvious once stated. One isn't, and it decides where<br>everything goes: when a fact moves out of the always-loaded entry point into a<br>linked file, context is only saved if the agent opens that file. If it doesn't,<br>the fact is gone and nothing tells you. A useless fact kept inline costs a few<br>dozen tokens. A critical fact moved out and skipped produces an edit that runs on<br>the wrong assumption and looks fine in review. So you don't split by size, you<br>split by what a miss costs: anything whose absence silently corrupts an edit<br>stays inline.

I benchmarked<br>this, because it sounded true and sounding true is worth nothing. A synthetic<br>repo, a planted fact ("scheduler delays are in centiseconds"), a task that<br>quietly depends on it, and the fact placed five ways:

placementfact honored<br>inline in the entry point100%, every model, every prompt<br>behind an @-import100%, but costs the same context as inline<br>one link away0 to 100%, depending on the harness<br>two links awaymissed too, even when the harness urged reading<br>absent0%

The link rows are the interesting part: a weak model never opened a link, and<br>the strongest model in the set skipped a well-labeled one unless the system<br>prompt pushed it to read files. The descriptive labels and per-link hints I had<br>written into the skill turned out to be nearly irrelevant; what makes an agent<br>open a doc is the harness telling it to read. Mainstream harnesses do, so a<br>capable model usually follows links there, but subagents, headless runs, and<br>cheap models get no such cover. You don't control the harness. You control what<br>stays inline.

The benchmark also caught the skill causing the exact failure it warns about:<br>an agent given the skill and asked to write the docs filed the centiseconds fact<br>in a tidy agent_docs file, keeping the entry point lean, and a<br>consumer that didn't follow links missed it every time. I wasn't surprised.<br>Agents make mistakes, the same way they skip links, and it's why blast radius is<br>now the loudest rule in the skill. The harness itself broke twice along the way;<br>twice I assumed a bug rather than bad luck, and twice that was correct. What<br>survived the fixes is in the<br>findings:<br>inline wins, and an author given the skill points at source instead of<br>hand-copying values, so its docs don't rot when a constant changes.

That last result points at the real question: do we need most of these docs<br>at all? The code must be able to carry this, right? Mostly it can. A rule that<br>can be a type or a test goes in code. Anything derivable from source gets<br>generated by a build target, since a hand-copied value is stale the day after<br>someone edits the constant. What's left is what nothing can recover later: why a<br>constraint exists, and the trap that ate an afternoon before it was understood.<br>The agent was there when that happened, which is one more reason it should be<br>the one writing it down.

So: stop hand-writing your CLAUDE.md, and stop...