The refactoring had taken twenty minutes. A senior engineer was watching the agent move through a codebase they had worked in for three years, and it had proceeded correctly through the first three files before stopping at a fourth and offering to write a small utility function. The function already existed; it had been moved to a different module in the autumn of the previous year, after a discussion that concluded that its original location was the wrong abstraction. The agent had not been present for that discussion.
The agent read the code, and it read a great deal of it: more files, in less time, than any engineer would read before making a comparable change. But it read them as text, without the surrounding context that tells a human engineer what the code is for in a particular system, why certain decisions look as they do, and which things that look wrong were made that way deliberately. The engineer knew where the function lived. The agent did not, and had no mechanism to find out other than to read further.
This is the starting point that tends to get lost in discussions of making codebases legible to coding agents. A codebase that a new hire can navigate and a codebase that an agent can navigate share so much that it is tempting to treat them as identical. Acting on that assumption leads teams toward recommendations that resolve the easier version of the question and leave the harder one unanswered.
Where the traditions meet
The argument that code should be written for its next reader rather than its first author is not new. Ward Cunningham articulated the principle in the context of the extreme programming movement in the 1990s. Kent Beck formalised it in Extreme Programming Explained, published in 1999. The literature that extended through the 2000s and into the 2010s, taking a range of forms from conference talks to Robert Martin's 2008 book Clean Code, produced a shared vocabulary: meaningful names, functions with a single responsibility, minimal surface area between modules, types that express intent rather than merely constrain values. The argument was, in short, that code should carry its own explanation.
This tradition was contested for most of its existence. The counterargument took several forms: clean code was a productivity luxury; small functions multiplied call stacks without proportionate benefit; type systems slowed development without proportionate reduction in defects. None of these objections were made only by engineers cutting corners. They had genuine proponents and the debate ran for over a decade without resolution, generating conference talks and retrospective posts on both sides and very little controlled evidence on either.
Coding agents changed the setting but not the argument. Types constrain the space of changes an agent can make without breaking tests. Narrow functions with single responsibilities reduce the surface area of misunderstanding. Consistent naming lets an agent generalise from what it has read to what it has not yet read. A research protocol published on arXiv in May 2026, BUILD-AND-FIND (2605.06136), attempts to measure this directly by separating two metrics: recovery accuracy, whether a finder agent can correctly answer questions about a codebase it did not write; and inspection effort, how much of the codebase it needed to read before doing so. A codebase where the answers are close to the surface costs the agent less context to navigate. That is the same thing the clean code tradition was arguing for, measured in a different unit.
What the research is showing
The results from 2026 are instructive in their mixed character. The METR randomised trial, which tested the effect of AI coding assistance on experienced open-source contributors, found that those contributors were 19 per cent slower on familiar codebases when using an AI coding tool than when working without one. This result was not what the field expected, and it has since been used as evidence for contradictory positions depending on the argument being made.
The more precise reading is that familiarity changes the calculus. An engineer who already knows a codebase well does not benefit from an agent that must discover it. An engineer working in an unfamiliar part of a large system, or a new hire in the first weeks of an engagement, is in the same position as the agent: neither knows where the function is, and both depend on the codebase carrying its own explanation. For those cases, the quality of the codebase's navigability matters in the same way for the human engineer as for the agent. The METR result does not argue against the legibility question; it argues that the question only bites where the human engineer does not already have the answer.
A study presented at the KDD 2026 workshop, examining 25,264 agentic pull requests across a range of repositories, found that infrastructure work, including CI/CD configuration, build tooling, and dependency updates, had merge rates above 90 per cent when generated by an agent. Feature work in application logic was substantially lower. The study does not attribute this directly to codebase legibility, but the pattern is consistent with agents performing well on tasks where the requirements are explicit and the relevant surface area is narrow, and less well on tasks that require inference about design intent. These two categories align closely with the distinction between what the readable code tradition addressed and what it left for engineers to handle through other means.
The gap that is not about quality
Where the two kinds of legibility diverge is not in code quality in the conventional sense. A codebase can be well-typed, well-tested, consistently structured, and thoroughly documented at the function level, and still be opaque to an agent at the level of design decisions. The agent reads what is there. It cannot read what was decided against.
A new hire, confronted with an architectural choice that looks unusual, asks a colleague. The colleague explains the prior approach, the incident that revealed its limits, and the specific reasoning that produced the current design. The new hire now holds that context and knows not to correct what looks like a mistake. The agent reads the same pattern, identifies the divergence from what it has seen in comparable codebases, and sometimes corrects it. The information was available in the room; it was not available in the repository.
Architectural decision records address exactly this gap. The format was described by Michael Nygard in a 2011 blog post: a short document for each significant architectural decision, recording what was decided, what alternatives were considered, and why each alternative was rejected. The format entered the standard software architecture literature and has been part of the practitioner vocabulary for over a decade. It is newly pressing because an agent reading the repository encounters an ADR in the same pass it reads the code, and the ADR provides the implicit context that the agent otherwise cannot recover through any other means. The new hire could have asked. The agent cannot.
The argument that agent legibility and new-hire legibility are the same thing is not obviously wrong. Comments explaining why a function takes the form it does help both a new hire and an agent. Type annotations on public interfaces, comprehensive integration tests that encode expected behaviour, clear module boundaries with documented contracts: these help both. The practices the clean code tradition advocated for thirty years turn out to be, in the main, the same practices that make a codebase navigable for an agent. This is not a coincidence; it is evidence that the tradition was identifying something real.
The cases that diverge are narrower, but they are the ones that cause incidents. An architectural decision encoded in tests will be protected from agent modification: the agent will break the tests and receive feedback. An architectural decision enforced only by convention, held in the shared understanding of the team, never written down because the team could always be asked: this is opaque to the agent in a way it is not fully opaque to a new hire. The things that were previously optional because engineers could always ask are less optional when agents cannot.
Whether the right investment is in documenting architectural decisions or in improving code structure, and in what proportion, is a question the evidence from 2026 does not yet settle. The METR result suggests the productivity gain from agents on familiar codebases may be smaller than the industry expected; the agentic pull request study suggests the gain on well-specified, constrained tasks is real; the BUILD-AND-FIND protocol gives researchers a framework for measuring inspection effort against codebase properties, and those results will accumulate. The practical advice, given what is known, is that the gap between a codebase legible to an agent and one legible to a new hire is narrow but real. It does not sit in code quality. It sits in the decisions that engineers have always been able to recover through conversation, and have therefore rarely troubled to write down.
“The things that were previously optional because engineers could always ask are less optional when agents cannot.”