01. How it happens
Every time an agent got something wrong, we added a sentence. Every time a branch changed how something works, we added "since 2026-09-…" and the new fact. Nothing was ever removed, because removing a rule feels riskier than adding one. Six weeks later:
| Measure | Value |
|---|---|
| Words loaded on every turn, all instruction files | ≈ 11,500 (≈ 15k tokens) |
| The local rules file | 5,362 words, 79 dates |
| Longest sentence | 825 words |
Paths it cited that did not exist on main | 17 of 91 |
| Facts stated in 6 – 12 places · of them disagreeing | 15 · 13 |
Claude Code's own guidance is under 200 lines per instruction file, and subagents receive the whole hierarchy too, so the cost is paid on every dispatch, not just every turn.
02. Three failures it caused
- It described the wrong codebase. The work lived on a stack of unmerged branches, and the file was kept current for the furthest one. A session that started on
mainwas briefed with five wrong version facts and seventeen paths that were not there. - Copies disagreed. The library count appeared as 35, 37, 41, 42, 43, 44 and 46. Three agent prompts gave three commit syntaxes. One prompt said nothing enforces layer direction, a week after a boundaries gate went into CI. An agent believes whichever copy it read last.
- Agents re-read what they already had. Four agent prompts began "read the rules file first", though subagents receive it automatically. About 11k tokens per run, roughly 200 runs, 2.2 million tokens for nothing.
03. What we changed
- Present tense, the checkout only. One table at the top lists unmerged branches and what each adds. When a branch merges, its row is deleted and its rules are written as plain present-tense rules.
- One home per fact. Each rule lives in one file; agent prompts name it and never restate it.
- History goes to a dated note. The changelog was real and useful. It just did not belong in context on every turn.
- Environment facts are printed, not written. Counts, aliases and project lists come from a command (
nx show projects), never from prose that goes stale. - A dead-path checker fails on any backticked path in the harness that does not exist.
- Four sentences deleted from four agent prompts.
| Before | After | |
|---|---|---|
| Rules file | 5,362 words | 2,170 words, ten rules |
| Path-scoped web rules | 2,912 words | 945 words |
| Missing paths | 17 | 0, checked |
| Memory files (33 about closed PRs) | 77 | 34 |
Instructions are a rule set, not a diary. Write the diary somewhere the agent does not have to read it every turn.