Coding Agents Evolved. Our Repositories Didn’t.

Why giant AGENTS.md files may be wasting context, hurting maintainability, and making AI-assisted development harder to scale. A few years ago, for many developers, using AI for software development meant copying a small piece of code into a chat window. We would ask for a refactoring, copy the response back into the editor, run the tests ourselves, and return to the chat when something failed. Coding agents changed that workflow. Tools such as Codex, Claude Code, and others can now explore an entire repository, modify multiple files, execute commands, run tests, and iterate on failures. Coding agents turned code assistants into tools capable of executing multi-step software development tasks. But most repositories were not designed for this new kind of contributor. The repository became part of the agent's working context A coding agent needs much more than source code. It may need to understand: the project architecture; dependency boundaries; coding conventions; test strategy; build commands; local environment requirements; validation steps; security restrictions; the definition of done. A common solution is to place these instructions inside files such as AGENTS.md , CLAUDE.md , or other agent-specific configuration files. This works. I have been doing something similar in my own projects for a while. But as the repository grows, the instruction file grows with it. Eventually, a single file may contain thousands of lines covering unrelated concerns: Architecture Testing Environment setup Coding standards Infrastructure UI conventions Validation Release workflows Definition of done At that point, the file is no longer just a set of agent instructions. It has become an informal repository operating manual. The monolithic context problem A large AGENTS.md has an obvious advantage: the agent knows where to find it. But it also creates several problems. It is difficult for humans to navigate These files are not only for agents. Developers also need to read, review, m