You read the previous post and you agree: write the why down, or the agent will undo it. So you open the CLAUDE.md file and paste it in: “Do not replace the queue between orders and fulfillment with synchronous calls. The partner API has multi-hour outages. See incident 2024-03, or ask Marko why.”
That’s the previous post’s sentence, near enough, and I said the agent needs it verbatim, in context. Half of it does. The model obeys what it can see, and this is the file it always sees - “loaded into the context window at the start of every session”.
It works. Now count what you just did. That paragraph rides along on every request, and the subagent loads CLAUDE.md too. Every session, every task, every subagent you define.
A line in CLAUDE.md is a tax on every task. The reason behind a decision is needed only when someone is about to change it.
What a Line in CLAUDE.md Actually Costs
Claude Code “re-sends the full context” on every request and caches it. At $2 per million tokens base and $0.20 cached on Sonnet 5, the token cost of that paragraph - thirty-odd tokens - is under a hundredth of a cent per request. A file of them, cents a session. Illustrative, like every token count here.
It’s not the invoice.
Caching cuts the bill. It doesn’t cut the window. Cached prefixes “still occupy the context window”, because “prompt caching changes what you pay for those tokens, not whether they count.” And as the count grows, “accuracy and recall degrade”, which the same page names context rot.
Then attention. Put the relevant line mid-context and performance “significantly degrades”. Pile up instructions and “even the best frontier models only achieve 68% accuracy at the max density of 500 instructions”, with a bias toward the earlier ones. Anthropic’s guidance, as of 2026-09-09, targets “under 200 lines per CLAUDE.md file” and warns that “Bloated CLAUDE.md files cause Claude to ignore your actual instructions”. Guidance, not measurement.
The measurement exists. Context files on real tasks, measured this February, “do not generally improve task success rates, while increasing inference cost by over 20% on average”. The instructions in them are “well followed.” The repository overviews “are not helpful.”
The root CLAUDE.md file of one of my own repos - a monorepo an agent works on unattended - is 822 lines and 9,450 words. Four times the target. Of its 81 paragraphs, 23 are the reasons behind decisions, several with the date and the issue number. They hold 5,274 words. More than half the file.
At Anthropic’s 0.75 words per token that’s about 12,600 tokens, 7,000 of them rationale, before the newer tokenizer’s roughly 30% more.
A rationale paragraph is two hundred and thirty words the agent reads past to find the one line that constrains it - the sign buried in the story.
I wrote every one of those paragraphs because something had gone wrong, or was about to. Each one is true. Each one is in the wrong file.
The question isn’t how short. It’s which lines.
Present Tense in CLAUDE.md, Past Tense in the ADR
Anthropic’s best-practices table puts “Architectural decisions specific to your project” under Include, and “Long explanations or tutorials” and “Detailed API documentation (link to docs instead)” under Exclude. No sentence says where the explanation goes.
CLAUDE.md is the present tense. An ADR is the past tense. The file says what is true now and what must not be done. The record says why it became true, what was rejected, and what it would take to change it.
Michael Nygard wrote in 2011 that “the motivation behind certain decisions” is one of the hardest things to track, and that without it a newcomer can only “blindly accept” or “blindly change.” The agent is that newcomer, every session. The sign prevents the blind change. The ADR makes the informed one possible.
Here’s where I part from the docs. When /doctor trims a CLAUDE.md it “keeps pitfalls, rationale, and conventions that differ from tool defaults”. Keep the pitfalls. Keep the conventions. On rationale I disagree, past a clause. A clause of why is a sign: “the partner API has multi-hour outages” is six words the agent can act on. The incident, the options rejected, the date and Marko’s name are the story - needed on one task and paid for on every one.
So the queue line becomes: “Do not replace the queue between orders and fulfillment with synchronous calls - the partner API has multi-hour outages. See ADR-012.” And one line, once, in the root file: decisions live in docs/decisions/. The line is the sign. The file is the story.
The Test That Sends Each Line to the Right File
The objection is my own maxim: the model obeys what it can see, and a why that isn’t loaded can’t be seen. Fair. At the moment of temptation - this queue looks unnecessary - the sign has to be visible. The reasoning doesn’t.
The sign is a line. The reason is a file, one Read away.
Here’s the test. Three of its four rows are Anthropic’s own:
Must be seen whatever the task. The root CLAUDE.md: loaded at launch, in every request, “re-injected from disk” after /compact. The queue line with its ADR number goes here - a queue has two ends and a config file, and no paths: glob covers every way to remove it.
Only needed near one part of the code. A nested CLAUDE.md there, or a .claude/rules/ file with paths: frontmatter. From the repo root, both load on demand as the agent reads code there.
The reason something is true. An ADR in docs/decisions/, MADR’s directory. Never loaded by default: zero token cost until it’s needed. Named beside the code it protects, so the Read is one line away.
Must hold every time, no exceptions. A hook, not prose. Constraint and pointer are both requests - “a request, not a guarantee” - and for what must never happen “an instruction is the wrong tool”. A PreToolUse hook exits with code 2 and blocks the edit.
The constraint in the root CLAUDE.md, the ADR in docs/decisions/, the pointer beside the code - a nested file or a rule scoped to services/orders/**/*:
Before changing the queue in
services/orders/, readdocs/decisions/012-queue-between-orders-and-fulfillment.md.
That’s Sebastian Tekieli’s shape - “the rule matters as much as the pointer” - with Claude Code’s loading rules deciding which line goes where.
Compaction is why they’re different artifacts. Read the orders code early, /compact, and the scoped rule is summarized away with it. The docs say so: “If a rule must persist across compaction, drop the paths: frontmatter or move it to the project-root CLAUDE.md.” The sign persists. The pointer comes back with the code.
One character turns that pointer into a paste. Backticks keep a path literal. Bare, with an @ in front, it’s an import, “loaded into context at launch”, and splitting into imports “doesn’t reduce context”. The path names the file. The @ pastes it.
Why the Reasons Don’t Live in AGENTS.md Either
Whatever the tool calls the file. AGENTS.md is “a README for agents”, “used by over 60k open-source projects”, stewarded by the Agentic AI Foundation under the Linux Foundation since December 9, 2025, when OpenAI contributed it. Claude Code still “reads CLAUDE.md, not AGENTS.md” and bridges with an @AGENTS.md import - the one @ that’s right, because that file is meant to load every session.
Cursor has .cursor/rules/*.mdc with globs, Copilot .github/copilot-instructions.md, and .github/instructions/*.instructions.md with applyTo. Switch tools and the syntax changes. The reasons don’t. And Codex reads AGENTS.md “before doing any work”, at most 32 KiB of it by default. Mine is 60 KB. In AGENTS.md the tax stops being dilution and becomes a cutoff.
The instruction file is a delivery format. The decision log is the record. That’s John Kennedy’s split: “keep the records as the system of record, and treat the agent context files as a delivery format”. Elliot Nelson made the token case in January, for topic files he calls ADRs. Neither says the why must stay out of CLAUDE.md, and neither puts a number on the paragraph.
The reverse direction has a rule already. The agent that decides mid-task drafts the ADR - the one rule from the workflow post - and now adds the line.
A reversal gets a new ADR that supersedes the old one - Nygard’s instruction is to “keep the old one around, but mark it as superseded” - and the line in CLAUDE.md changes. Not appends. Changes. The same PR does both, reviewed like code, so a line still citing a superseded number is a diff a reviewer can see.
The previous post called the log “the one memory that persists across sessions, across models, across tools.” “Across tools” turns out to mean outside every tool’s file.
None of this is a rewrite. It’s a move - twenty-three files, drafted by the agent from paragraphs already written. Keep each paragraph’s first sentence, give the rest a number and a file, put a backticked path beside the code it protects. The scar tissue was ADRs all along, waiting for a filename.
It’s the same thesis as the context post: better density, not more context. A file that carries only what every session needs is the densest file in the repo.
The card points at the book. Don’t write the book on the card.