Most agent tools now ship a command that reads your repository and writes an instruction file for you. It is a reasonable-sounding idea with an uncomfortable evidence base, and the honest summary is that the evidence is mixed rather than damning.
The ETH Zurich study
The most direct measurement is Evaluating AGENTS.md, from ETH Zurich, published at ICSE 2026. It ran 138 real-world tasks across four coding agents, comparing runs with and without repository context files, and separating machine-generated files from human-written ones.
For LLM-generated context files the results were negative on every axis measured:
- Task success fell by 2 to 3%.
- Inference cost rose by 20 to 23%.
- Agents took 2.45 to 3.92 additional steps to complete work.
- Success was reduced in 5 of the 8 settings tested.
So: worse outcomes, more expensive, and slower. The negative effect on success is small; the cost and step-count effects are not. Paying a fifth again in inference for a slight reduction in success is a poor trade in any direction you read it.
Human-written files went the other way
The same study found human-written context files improved task success by about 4 percentage points. Same agents, same tasks, same file format, same location in the repository — opposite sign.
Whatever is going on, it is not that instruction files are inherently harmful. The difference is in the content, which points at a specific mechanism: a model generating an instruction file can only write what it can infer from the repository, and anything it can infer, the agent reading the file could also have inferred. The generated file therefore consists largely of restated observations, which cost tokens without adding information.
A human writes the other kind of thing. That the staging database is a shared instance and migrations must be reversible. That a directory looks dead but is imported by a scheduled job. That a plausible refactor was tried and reverted. None of it is derivable from the source at any context budget, because it is not in the source.
Repository overviews provided no benefit
One specific finding deserves separate attention, because it contradicts the most common advice in circulation. Repository overview sections — the project description, the tech stack, the directory tree, the "this is a React app with a Postgres backend" paragraph — provided no measurable benefit.
In hindsight this is close to obvious. An agent with filesystem access establishes the stack from package.json in one read, and the directory layout in one glob. Telling it what it is about to see is redundant, and redundancy is not free: it occupies the beginning of the file, which is the most valuable position available, and it pushes the constraints that actually matter further down.
Almost every generated instruction file leads with exactly this section. Almost every template recommends it.
The countervailing evidence
It would be dishonest to stop there. A separate study by Lulla and colleagues, presented at the ICSE 2026 JAWs workshop, examined 124 pull requests and found that the presence of an AGENTS.md file reduced agent runtime by 28.64% and output tokens by 16.58%.
That is a substantial efficiency gain, and it points in the opposite direction to the ETH Zurich cost figures. The two are not necessarily in conflict — different task sets, different agents, different measurement targets, and efficiency and success rate are different things — but the responsible reading is that the field has not converged. Repository context files are not settled science, and anyone telling you the question is closed is selling something.
The other thing worth stating plainly: neither study evaluated Codee3, or any governed knowledge layer. They tested single-file instruction documents. Nothing here constitutes evidence for or against a structured, authority-graded corpus, and it would be a misuse of both papers to claim otherwise.
The step count is the number to watch
Task success moved by 2 to 3 percentage points, which is small enough that a sceptic could reasonably discount it. The step count did not: agents took between 2.45 and 3.92 additional steps to complete the same work when given a generated context file.
That is a large effect and a diagnostic one. Extra steps mean the agent explored more, backtracked more, or attempted more approaches before converging. A context file that was purely redundant would leave step counts flat while raising token cost. A file that increases exploration is doing something more active — introducing material the agent felt obliged to reconcile, or asserting things at a level of generality that had to be checked against the code.
This also compounds with the length effects covered in context rot. More steps means more tool output accumulating in the window, which means longer contexts, which means measurably lower reliability on later turns. A file that adds three steps to every task is not paying a one-off cost; it is shifting the whole session further along a degradation curve.
For anyone evaluating their own instruction file, step count is also the easiest thing to observe without instrumentation. If adding context made your agent take longer to converge, the context is not helping regardless of what it says.
The rule that survives both results
Across the conflicting findings, one principle is consistent with all of them: include what the agent cannot discover by reading the repository, and exclude what it can.
This explains the whole pattern. Generated files perform badly because generation can only produce discoverable content. Human files perform well because humans know things the repository does not record. Repository overviews provide no benefit because they are the purest form of discoverable content. And the efficiency gain in the second study is consistent with a file that saves the agent exploration it would otherwise have had to perform.
It is also a usable editing test. For every line, ask whether an agent with a shell and ten minutes could have worked it out. If yes, delete it. What remains will be short, which is the right shape for a file loaded on every request. The specifics — including discovery rules and size limits — are in what belongs in an instruction file.
How to read evidence like this without over-reading it
Two studies pointing different ways is the normal condition of a young field, and there are a few things worth holding on to when interpreting them.
Success rate and efficiency are different outcomes. A file can make an agent faster and cheaper while making it slightly less likely to finish the task correctly, and both findings can be true of the same artefact. Anyone quoting one number without the other is picking a side rather than reporting.
Task selection dominates results in this area. A benchmark of small, well-scoped changes in familiar open-source repositories measures something quite different from work in a large private codebase with undocumented history — and it is precisely the undocumented history that a good context file is supposed to supply. The tasks where non-inferable knowledge matters most are the tasks that are hardest to include in a public benchmark.
And the generalisation people reach for — "context files help" or "context files hurt" — is the wrong shape. The measured variable that separated the two outcomes in the ETH Zurich work was not presence but provenance: who wrote the file, and therefore what kind of content was in it. That is an argument about content, not about the format.
The defensible conclusion is narrow. Adding an unreviewed generated file to your repository is not a free improvement, and there is measured reason to think it costs you something. Writing a short one yourself, containing things the repository does not record, is the version with evidence behind it.
Where this leaves generated files
Generation is not useless; it is misapplied. A generated draft is a reasonable starting point for a human who is going to delete 80% of it and add the five things only they know. It is a poor finished artefact, and the measured penalty for treating it as finished is real.
The deeper issue is that a single instruction file is being asked to do a job it is the wrong shape for. Constraints, decisions, current state, and domain knowledge have different lifetimes, different owners, and different authority. Flattening them into one document loaded on every request means the whole thing is either always loaded or never maintained.
Codee3's position on this is narrow: it installs a governed .ai/ layer where those different kinds of knowledge live in separate, classified documents, points the instruction files your tools already read at that layer, and fails CI when the layer's structure breaks. It does not write your knowledge for you — which, on the evidence above, is the part you would not want automated anyway.