Why my agents read a vault instead of one giant CLAUDE.md
Every CLAUDE.md grows until it becomes a fixed cost you pay every session. The fix was separating what configures the agent from what decides for the project.
Every agent instruction file starts small and honest. A few style rules, the build command, where the tests live. A few months later it no longer fits on one screen, nobody remembers why half the rules exist, and you pay for that whole file in tokens every time you open a session — including when you only want to ask what time it is.
The problem is not the size. It is that two very different kinds of information ended up in the same place.
Two things that are not the same thing
Part of what sits there configures the agent: use a worktree before touching code, never install anything without asking, run the linter before opening a PR. It is operational, it is short, and it has to stay in memory permanently because it governs every action.
The other part decides for the project: why the payments service talks to orders through an event instead of a direct call, why that column is nullable, which alternative was discarded back in 2025 and why. It is dense knowledge, it grows without end, and you need it in maybe one session out of ten.
Cramming both into one file makes you pay the price of the second at the frequency of the first.
The split
What I run today is two places with different authority:
- The configuration file (
CLAUDE.md) became a router. Always-on rules, a map of where things live, and pointers. It explains nothing — it says where the explanation lives. - The vault became the canonical authority. ADRs, specs, decisions, lessons. The agent reads on demand, when the work actually touches that area.
The rule that makes this work is boring and essential: local refines, never contradicts.
When a project's CLAUDE.md and the vault disagree, the vault wins. Without that rule you do
not have two layers, you have two sources of truth — which is the same as having none.
What changed in practice
Session startup cost became constant instead of growing with the project. When the agent needs deep context it goes and fetches it — and fetches the right version, because there is exactly one place that thing lives.
The less obvious win came later: once writing a decision down had a fixed address, decisions actually got written down. Before that, an architecture call either became a code comment or evaporated into chat history.
Where it breaks
It is not free. The indirection means the agent sometimes does not know it needs to look — it answers from what it already has, confidently, never noticing there was an ADR contradicting it. The mitigation is an explicit resolution order in the router, stating where to look before answering.
And a stale vault is worse than no vault: a wrong file in the canonical location gets read as truth. Without the discipline of updating it when the task ends, the split works against you.