Why I separate agent instructions from project knowledge
Keeping agent instructions separate from project knowledge avoids paying the same cost in every session.
Every instruction file for an AI agent (a program that carries out tasks) starts small. It has a few style rules, the command to prepare the program to run, and the place where tests live. A few months later, it no longer fits on one screen. Nobody remembers why half the rules exist. And you pay for all those tokens (units of text read by the model) in every session. Even when you only want to ask what time it is.
The size is not what bothers me. The problem is putting two very different kinds of information in the same place.
Two different things
One part configures the agent: use a worktree (a separate copy of the project files) before changing code. Do not install anything without asking. Run the linter (an automatic code check) before opening a PR (a request to review and include changes). These are practical, short rules. They need to stay in memory because they guide every action.
The other part records project decisions. Why does the payment service notify the orders service through an event? It is a message that something happened. This replaces a direct call. Why can that field be empty? The code marks it as nullable. Which option was rejected in 2025, and why? This knowledge is detailed and keeps growing. You may need it in one session out of ten.
Putting both kinds in the same file makes you pay the cost of the second as often as the first.
The split
Today I keep two places with different jobs:
- The configuration file (
CLAUDE.md) became a router: a guide that shows the agent where to look. It holds always-on rules, a file map, and pointers. It does not explain the subject. It shows where to find the explanation. - The vault (a collection of project documents) became the official source. It holds ADRs (records of architecture decisions), along with specifications, decisions, and lessons. The agent checks these documents when work reaches that part of the project.
The rule that makes this work is simple: local instructions can add details, but they
never contradict the vault. If a project's CLAUDE.md and the vault disagree, the vault
wins. Without this rule, you have two sources claiming to be official. In practice, you
have none.
What changed in practice
The cost of starting a session became steady instead of growing with the project. When the agent needs details, it fetches the right version. There is one place for each subject.
The less obvious benefit came later. Once decisions had a fixed address, they started getting recorded. Before that, a decision about the system's structure became a code comment or disappeared into chat history.
Where it fails
The split adds one step. Sometimes the agent does not realize it needs to check the vault. It answers from what it already knows, confidently, without noticing a recorded decision that says something else. To prevent this, the router needs to say clearly where to look before answering.
A stale vault is worse than no vault. The agent may read the wrong file in the official place and treat it as true. If you do not update the records when the work ends, the split gets in the way.