What 1,925 repositories actually tell their AI coding agents, why writing more of it down turns out to be the wrong fix, and the system I built instead — whether you're working alone or on a team.
Someone counted. A study of 2,303 agent context files — the AGENTS.md and CLAUDE.md files that tell an agent how a project works — across 1,925 repositories, sorted into sixteen categories.
Testing appears in 75.9%. Implementation details, 70.8%. Architecture, 68.1%. Then it falls away. Security: 14.8%. Performance: 14.5%. UI/UX, last of the sixteen, at 8.7%.
That last number needs some honesty first: the sample is repositories where agents already contribute, and plenty have no interface at all. But the low number isn't only sampling. An agent can see a button has 8px of padding and a specific blue. It can't see why: which spacing is a token and which is a one-off, which color is brand-locked and which nobody's fixed. Code shows what. UI/UX lives almost entirely in why — exactly the category that goes undocumented most.
My first instinct was to fill the gap. A second study talked me out of it. ETH Zurich benchmarked 138 real tasks against frontier models three ways: no context file, an LLM-generated one, and one written by the project's own developers. No improvement in success rate. Over 20% more spent per run — agents explored more, ran redundant tests. An architecture overview worked as a distraction rather than a map.
This doesn't prove my approach works — the study never tested decision records. It just rules out the easy fix: restating what the code already shows. Recording what the code can't show at all is still the harder half, and it's still untested.
The null result makes sense once you separate the two categories. An architecture overview — folder structure, patterns, naming — is already derivable from the source. Writing it down again hands the model a second copy of something it had.
What isn't in the code is the decision. Why this pattern and not the three I tried first. Which brand rule is deliberate and which is an accident nobody has fixed. What “done” means here. Which approach was already ruled out, and why. None of that is recoverable by reading the repository. It lived in a conversation, and the conversation closed.
A decision recorded without its reasoning can only be re-argued: you find the choice, not why, and can't tell whether the reason still holds. A decision recorded with its reasoning can be amended — you can see what it was answering, and change it deliberately when it's no longer true.
Same problem whether you're solo six months into a project or one of eight on a team. Nobody has a standup with their own memory from three weeks ago, and no team's memory outlasts everyone who was in the room. Either way, the choice gets re-argued by whoever finds it next.
Concretely, a decision record is short:
## ADR-014: Brand blue stays under AA contrast on white
Status: Accepted
Context: Brand blue tests 3.9:1 on white CTAs — AA needs 4.5:1.
Decision: Keep the blue. Require bold text at 16px+, or a darker
fallback shade for anything smaller.
Rejected: A WCAG-safe blue site-wide — it flattened the brand
color everywhere it appeared.Five lines. Quick enough to skim in a few seconds — but this tells you what got ruled out, and why.
Three layers. Memory — what stays stable: product north star, brand, design, content, architecture, quality. Methods — eight repeatable skills for how work gets done: kickoff, product spec, information architecture, frontend design, accessibility review, design system, quality gate, Linear setup. Logs— specs for what's being built now, decision records for why past calls went the way they did.
Agents enter through AGENTS.md and read the same files a person would, so nothing is written twice and nothing drifts.
Multi-session work over weeks, where a person is making real calls about product, brand, design, architecture and the quality bar — solo or on a team, whenever nobody three weeks from now was in this room.
Vibe coding is still the better call for a weekend prototype — the overhead here outweighs the benefit there. This pays off later, when the thing has to outlive its first version. It also adds little to a mature codebase that's already well documented, which is where the ETH result bites hardest.
Here's a check worth running: think of the last real decision on your project — not the last commit, the last choice that could have gone another way. Did the reasoning survive anywhere findable? If it only exists in someone's head, or in a chat window that closed, the next person there will re-argue it rather than improve it. That's true whether the next person is a colleague, an agent, or you in November.
Open source
A GitHub template — read it first, then start your own project from it.
View the kit on GitHubChatlatanagulchai et al., Agent READMEs: An Empirical Study of Context Files for Agentic Coding — 2,303 context files across 1,925 repositories.
Gloaguen et al. (ETH Zurich, LogicStar.ai), Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? — 138 tasks, four frontier models, three conditions.