One home per rule, or the copies already disagree
Public developer issues show the same project fact copied into two, three, or four files, and the copies already contradict each other. A current answer needs one home. History belongs somewhere else.
Public developer issues often come back to a quieter failure than a missing file. The current fact was written down. It was written down more than once. The copies already disagree. Or the current answer was never written as such, so the next agent reconstructs it from the code, every turn, and sometimes gets it wrong.
The copies already disagree
In a public issue on the cycling project, Patrik reported an audit of main (5e8284b0). Every document was read in full. About 420 factual claims were checked against the code. Size was not the problem. Three things were.
Agents in that repository work from AGENTS.md, docs/, and .agents/. The same rule lived in two to four places, and the copies already disagreed. Pull requests appended a paragraph of internals or history instead of rewriting the current intent, so a document that should state the present turned into a changelog. A few documents still described an older product.
The mismatches were concrete. The README said the project had nine built-in workouts; the code had 16. A brief and a labels document named labels that do not exist in the repository. One document said a turn is announced "30 s ahead (150 to 400 m)"; the code uses a fixed 300 m. In several places, two documents disagreed with each other, and only one of them matched the code.
The decision recorded in the issue is direct. Where a document and the code disagree, the code is right, unless the code looks like the bug, in which case you file it. Each rule gets one home; the others link to it. Documents state the present: no "before", no pull request numbers as explanation, no dated decisions in the paragraph the next reader will treat as current. History stays in git and in the issues.
"What is it now" should not be a search
A related failure is that the current value is on the page, but it is buried in a history of how it used to be.
In codegraph, GRAPH_FORMAT_VERSION moved from 6 to 10 in one session. The code was consistent: the constant is 10. The file a consumer reads to decide whether to wipe .graph-cache was not. The rest of that file carried several separate "X → Y" bump narratives. Each was accurate for its moment. Together they made "what is it now" a grep-and-infer exercise.
The proposed fix was a single current-state sentence, and every historical mention written in the past tense, so a later reader scanning for the current value cannot land on an old one.
If it is not written as current, the agent rebuilds it
When the current answer is missing, the cost is not only inconsistency. The agent spends the turn reconstructing it.
In two user tests on kiln, a read-only Copilot assistant lacked standing rules for facts that other issues were already adding. It rebuilt "what v0.1 can and cannot do": which families train, that a native instance stops at a plan, which verbs are planned: from plan.py, cli.py, and the family files on every turn. That work took 29 to 248 seconds per answer. In one case it also sent a V-Pred user to the eps model's page, and never said where the project records the prediction type.
The proposed change was to write a short current block once, and to fail a check when that block drifts from the family files. The issue is still open. The tests are two sessions, not a large study. They still show what a missing current answer costs: the next agent does the research again, and it can still point the reader at the wrong place.
This is an old documentation problem. Agents now read the copies.
Google's documentation best practices put it plainly: a small set of fresh and accurate docs is better than a large assembly of "documentation" in various states of disrepair. The same guide has a short rule under "Duplication is Evil": do not write your own copy of a guide that already exists. Link to it. If it is wrong, update the original.
Software Engineering at Google, in the documentation chapter by Tom Manshreck, makes the same call when documents conflict. Designate canonical documentation. Determine the primary source, and consolidate the others into it, or deprecate the duplicates.
That guidance is about engineering documentation in general. It is not a controlled study of coding agents, and it does not measure how often an agent follows a stale copy. The public issues above are the first-hand cases. What has changed is the reader. A teammate might notice that two pages disagree and go look at the code. An agent will often treat the first current-sounding sentence it finds as the rule.
Keep one current answer
A practical split looks like this.
- Give each current fact, decision, or constraint one home. Other files link to it. They do not restate it.
- Write the present-tense answer. How you got there belongs in git, in the issues, or in an append-only timeline, not in the paragraph the next session will treat as current.
- If the next agent has to reconstruct the fact from the code every turn, the current answer is missing. Write it once, in the home that the next session will actually read.
- Where a document and the code disagree, treat the code as right unless you are filing a bug. Then update the one home.
- A check that the current answer still matches its source is more reliable than hoping someone notices the drift.
MindMux itself makes a product in this space.
MindMux captures background, decisions, and constraints from the conversations you already have with agents, and writes them into a Markdown project brain. Agents read that brain over MCP before they start a task. To connect Claude Code or Codex, install @mindmux/cli and run mmx setup in the project. mmx setup --local gives a local Brain without Cloud login. The open, local counterpart, brain.md, is a brain/ folder in your repo plus a small CLI (@mindmux/brain-md). Every page keeps a compiled_truth, the current answer, and an append-only timeline of how you got there. It is git-native and agent-agnostic: Claude Code, Codex, Cursor, and anything else that can read a file.
This is cross-session, cross-tool decision memory. If the current answer has one home, and yesterday's history is not sitting in the same paragraph, the next session has a chance of reading the same truth.