Distributed context: why agents should not read the whole project

I started the way most people start: one specification per undertaking, and one large file with the project context beside it. That carries you a few weeks. Then both grow, and at some point it tips over. Not because the information is wrong, but because too much of it sits in one place. The agent reads everything, weights the wrong parts, and answers a question I did not ask.

The fix was not to write less. It was to separate what I had written by the question it answers.

The starting position that forces this

A context document begins as a help and becomes a burden once it reaches the size at which nobody knows what is in it any more. With people, the file simply stops being read. With an agent the opposite happens: it reads the file in full, every time, and treats every sentence as equally important.

That difference is what forces the split. A human skims and picks out what they need. A model has no feel for which paragraph matters unless something in the structure tells it. Twenty pages of mixed knowledge are inconvenient for people and a source of errors for agents.

A second problem stays invisible inside a single document: knowledge has different shelf lives. A command for running the tests changes with the tooling. An architectural rule holds until it is revoked. The reasoning behind that rule holds forever, because it describes a historical event. Put all of it side by side and the document ages at the speed of its most perishable part.

Splitting by the question, not by the topic

I now divide project knowledge into three sources, and the criterion is not the topic but the question a file answers.

The first answers: how do I work with this repository? Commands, gates, what has to be green before anything lands. It is the shortest of the three and the only one an agent needs every time.

The second answers: how is it built, and by what rules? This is the normative part: layers, permitted dependency directions, how components are allowed to communicate. It states what holds, not why it holds, and not whether it has been implemented yet.

The third answers: why was it decided this way? These are the specifications: alternatives, trade-offs, rejected paths. They are an archive, not a working document. An agent implementing a ticket does not need to read them; a person questioning a rule does.

The rule that holds the arrangement together: never blur the three. A rule in the normative part does not explain its reasoning, it links to it. As soon as a file starts answering two of these questions at once, it is on its way back to being the big document.

The normative part is split again along the same logic: general rules kept apart from the descriptions of individual building blocks. Architectural guardrails, the checklist walked before every pull request, are their own document rather than a section inside a component description. They apply everywhere, so they must not be filed anywhere specific.

On disk it looks roughly like this:

AGENTS.md                  → How do I work with the repo? (commands, gates)
context/
  README.md                → Index: one line per file
  core/
    architecture.md        → What holds: layers, dependency directions
    guardrails.md          → Checklist before every pull request
  modules/
    <module>.md            → What this building block is, its pitfalls
docs/specs/
  YYYY-MM-DD-<topic>.md    → Why it was decided this way, alternatives

The folder names are arbitrary. What matters is the right-hand column: every file has exactly one question it answers, and no second one.

The index is the actual mechanism

Splitting alone achieves nothing. Twenty files instead of one are worse than one if the agent does not know which to open. It will either read all of them or guess.

What makes the split work is an index file: one row per document, saying in a single sentence what it contains. No more than that, and above all not a summary of the contents, because then the agent ends up reading everything at once again.

The agent reads the index, picks two or three files and ignores the rest. That is the whole trick. What decides the quality of the work is not how much context there was, but how precisely it was chosen.

To keep the index from rotting, a rule hangs off it: whoever adds a file adds its index row in the same step. A file that is not indexed effectively does not exist for the agent.

A second rule keeps it honest: context is written in the same ticket as the code it describes. No documentation for functionality that does not exist yet. That sounds like discipline, but it is mostly relief. There is no backlog to catch up on, and no file describing intentions instead of states.

Along with it comes the rule I took longest to arrive at: no status markers in the normative part. No "not implemented yet", no ticket numbers. Status belongs in the issue tracker. Once it migrates into the rules, the document ages with every sprint, and an agent can no longer tell whether a line is a norm or a note.

Who checks that the rules were followed

Writing rules down does not mean they are followed. What catches this is the final phase of every task: a review pass that checks the change against exactly those architectural guardrails, point by point, against a document that exists. Not against code quality in general.

That is why the separation pays off at all. A checklist buried between commands and reasoning cannot be walked. One that stands on its own can.

Then the quiet deviations surface: the ones a green test suite misses, because they break nothing and merely move a boundary.

This is also the answer to the question of who owns the architecture when agents write the code. It belongs to whoever decides what has to fail loudly. A green gate is necessary and never sufficient; every guarantee the architecture makes needs an anchor that breaks when the guarantee is violated. Choosing those anchors is the work that does not get delegated. The implementation beneath them does.

The uncomfortable part of the bill

Maintenance costs little, because it is part of the task rather than something that comes after. The price sits elsewhere, and it is less comfortable.

The context becomes binding. An outdated comment in code is harmless, because a developer reads past it. An outdated rule in a normative document gets followed: reliably, literally, and without asking. That shifts the failure from "the agent did not know" to "the agent did what it said". The second failure is harder to find, because the result looks perfectly consistent.

The second price: the construction does not stop growing. It now grows distributed rather than in one place, which delays the effect without removing it. Eventually the index is long too, and then the same question comes up again, one level higher.

Where I would not do this

For a small project with a clear, bounded scope the effort is not justified. When the codebase fits into one session and the rules into one paragraph, splitting is ceremony: you build an index for a document you could have read in one go.

The threshold is where an agent starts reading things on every task that have nothing to do with it. Before that, the structure solves a problem you do not have yet.

Leaving out, not knowing everything

The question is not how to give an agent as much context as possible. It is how to let it leave the right things out. That is a question of structure, not of volume, and larger context windows do not make it smaller. A model that can read everything is still a long way from weighting it correctly.

What surprised me most: the arrangement turned out to be just as useful for people. Separating by the question answered is not a concession to the machine, it is the order one should have had anyway.