Essay

The nervous system of your codebase is a markdown file

The plain markdown file now has a number behind it: 2,853 repositories.

A team of researchers set out to catalogue every way a repository can configure an agentic coding tool: Claude Code, GitHub Copilot, Cursor, Gemini, and Codex among them. They identified eight distinct configuration mechanisms, running from static text a human writes once to scripts the agent can execute to live connections out to other systems. Then they counted, across 2,853 real GitHub repositories, which of the eight actually get used.

The count is lopsided. Context files, the plain-language documents like AGENTS.md, dominate the landscape. In the repositories that configure an agent at all, the context file is often the only mechanism present. The elaborate machinery sits idle: Skills and Subagents barely register, and the Skills that do exist are overwhelmingly static text, with fewer than 6 percent bundling an executable script. AGENTS.md itself is spreading faster than the tools that read it: 493 of these repositories carry an AGENTS.md and no tool-specific file at all, while Claude Code, the most popular tool in the study, still does not read it natively. Developers symlink it to CLAUDE.md and move on, what the paper calls “a clear gap between developer practice and tool capability.” Practice running ahead of product is what a standard looks like while it is being born.

The file is the nervous system. Code is the musculature of a codebase: it does the lifting. What coordinates the lifting never lived in the code. It lived in people: the senior engineer who knows why the retry logic is sacred, the review thread where the deploy rules got settled, the hallway answer that saves a new hire a week in the commit log. Agents broke that arrangement, because the new hands are not in the hallway. So the signal is moving out of heads and into the repository, and the census just showed the wire it chose: a markdown file, sitting in a directory every agent already knows to check.

I have been saying a version of this for a year without a dataset to point at. Software engineering is mid a generational shift, and it rhymes with the last one. When Java abstracted memory management away, the job moved up a level: engineers who used to manage memory started managing logic instead. The same rotation is happening again, one level up: managing syntax gives way to managing context. The context file is the first place the new job condenses into an artifact you can version, diff, and hold each other to.

The objection with a clock in it. Skills and Subagents barely register, so maybe the ecosystem just has not caught up: give it a year, every serious repo accretes an orchestration of subagents and executable scripts the way codebases eventually accreted CI, and AGENTS.md turns out to be the training wheels. Concede the clock. This census is a February snapshot of public repositories whose conventions are still forming. The authors call their results early signals rather than settled findings, and Skills had been public for roughly four months when the counting ran. No snapshot refutes a trajectory. The paper’s third finding even leans the objection’s way: Claude Code users, holding the fullest toolbox in the study, employ the broadest range of mechanisms of any tool’s users. But look at the shape of the growth. The machinery accretes around the file, not in place of it: context files sit in 94 percent of the study’s Claude Code repositories, and outside Cursor’s rules files, no other mechanism clears 20 percent adoption for any tool. Muscle getting stronger does not retire a nervous system. If the accretion story comes true, it gets wired into this file, and the file is how anyone finds out what got wired.

Does the file even work? A second study measured that directly, benchmarking agents on real tasks with and without context files, and came back cold: providing the file did not generally improve task success, while adding more than 20 percent to inference cost. The result held for machine-generated files and developer-committed ones alike. If adoption were proof of function, the essay would end here.

It ends somewhere better, because the same study found the split that matters. Agents follow the instructions in a context file well. What fails to earn its cost is the repository overview, the guided tour of the code that model providers themselves recommend, and that the tools will scaffold for you in one command. A nervous system would predict that split. It carries no anatomy lessons. The body already has its anatomy. It carries commands and inhibitions: fire this, never that. An agent can read your code, so the tour is noise it paid to re-read. What it cannot read is the constraint that lives outside the code: the invariant nobody wrote down, the migration you must never run at noon, the reason the retry logic is sacred. The study’s own conclusion lands there: context files earn their keep specifying the non-standard, the things the code cannot say about itself.

Software engineering spent seventy years teaching itself new dialects, FORTRAN to C to Java to Python, each one a fresh syntax to master before you were allowed to be useful. The discipline ahead runs through what you tell the machine before it touches your code. The census says the wire is already chosen: a markdown file with a name, adopted faster than the tools can read it. What travels on that wire, no census can hand you. A nervous system is only ever worth its signal.

Sources: