One CLAUDE.md to Rule Them All (and Why That's the Bug)
Every agent project starts the same way. One CLAUDE.md, or one AGENTS.md, holding everything the agent needs to know: the stack, the conventions, the deploy steps, the do-nots. On day one it's twenty lines and it's perfect. Six weeks later it's four hundred lines, three people have edited it, and the agent just ignored the one rule that would have stopped it breaking prod. The file didn't fail because it was badly written. It failed because it was one file.
The Learn Harness Engineering course — a genuinely good, theory-first walkthrough of how these systems are built — gives this its own lecture: "Why One Giant Instruction File Fails." They're right, and it's worth reading alongside this. What follows is our own read of the same real problem, grounded in what actually goes wrong on disk.
The three failures, and why they're structural
The giant instruction file doesn't fail all at once. It fails in three ways that compound.
| Failure | What you see | Why the file causes it |
|---|---|---|
| Context dilution | The agent skims past the rule that mattered because it's buried at line 400 | Everything competes for attention in one blob; nothing signals what's relevant to this task |
| Contradiction drift | Two rules quietly disagree; the agent picks whichever it read last | Nobody can hold 400 lines in their head while editing, so new rules get added, not reconciled |
| Edit churn | Every new module means editing the same file everyone else edits | One file, one lock; onboarding a new stack conflicts with unrelated work |
Notice that none of these are prompt-quality problems. You can't write your way out of them. A perfectly worded rule at line 400 still gets skimmed. A perfectly worded rule still contradicts the one added last week by someone who never read the whole thing. The failure is the container, not the copy.
Context dilution is the sharpest of the three because it's invisible. The agent loads the whole file, "reads" all of it, and the one line that governs the task you're on carries exactly as much weight as the forty lines about a subsystem you're not touching. Relevance is flat. When everything is standing context, nothing is foreground. This is the same attention-budget problem that makes runaway loops hard to rein in — the model isn't malicious, it's saturated.
The fix is scope, not length
The instinct is to manage the giant file better: sections, a table of contents, bold text on the important bits. That's rearranging the blob. The actual fix is to stop loading context the agent doesn't need for the task at hand.
Split by concern and by scope. Keep a root instruction file for standing facts — the ones true everywhere in the repo: what the project is, the deploy mechanism, the hard safety rails, the things that must never happen. Then push everything else down into the directory it applies to. A nested CLAUDE.md or AGENTS.md inside payments/, another inside frontend/, each holding only what's true when the agent is working in that area. Claude Code and similar tools already support this: directory-scoped instruction files that load when the agent is operating in that subtree, not before.
This is not novel. It's how large codebases have always managed convention — .editorconfig, per-package linters, module READMEs. The monorepo pattern of "rules live next to the code they govern" applies cleanly to agents. This very repo runs a root CLAUDE.md for standing facts and pushes loop-specific instructions into the loop definitions themselves, so the daily scrape loop never reads the deploy checklist and vice versa.
Look at what scoping does to each failure. Dilution: the agent working in payments/ loads payment rules, and they're foreground because nothing else competes. Contradiction: a rule about payments lives in the payments file, where the person editing payments will actually see it — reconciliation happens because the surface is small enough to hold in your head. Churn: a new module ships its own instruction file, touching nobody else's. Three failures, one structural change.
The harness fixes these the way a good pipeline fixes carelessness — structurally, not by asking the model to try harder. You're not prompting the agent to "pay attention to the important rules." You're building a layout where only the relevant rules are in front of it, so attention doesn't have to be rationed by hand. That's also why it scales down: two files is enough on day one. You split when a section stops being true everywhere, not before.
If you're assembling a harness from scratch, the anatomy of an agent loop covers the five parts the instruction files sit under, and loops gone wrong covers what happens when the context layer is the thing that breaks. The loop builder scaffolds the scoped-file layout by default, and the directory has vetted loops you can read the structure of directly.