The problem
Writing the intent down is not enough.
Three defects. None of them visible while reading the file. Each one costs you twice.
it contradicts itself
The same fact lives in two places
An agent updates one copy. Nothing tells it about the other.
what it costs you- A conflict. Two agents build two different things, each correct about what it read.
- Context paid twice. The agent reads the same fact in two files and pays tokens for both.
it goes stale
The text no longer matches the code
A rule describes behaviour that was changed months ago.
what it costs you- The document decides the bug. Agents trust the written rule over the code.
- Nothing flags it. The file still reads perfectly well.
it only grows
Nothing ever removes text
Every correction is satisfied by adding words.
what it costs you- Old and new rules sit side by side. The agent picks one.
- More tokens, worse answers. Every frontier model degrades as context grows — keep agent-facing files to 200–500 lines.