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.
A coding agent needs much more than source code.
It may need to understand:
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.
A large AGENTS.md
has an obvious advantage: the agent knows where to find it.
But it also creates several problems.
These files are not only for agents.
Developers also need to read, review, maintain, and discuss the rules.
Someone changing a test should not need to navigate through multiplayer architecture, asset conventions, deployment rules, and UI standards.
A small bug in a domain class may not require information about:
When a large root instruction file is injected into every task, unrelated guidance may consume context that could otherwise be used for the task, the code, and the relevant documentation.
Architecture rules may remain stable for months.
Bootstrap commands may change after a toolchain update.
Validation rules may evolve every week.
Keeping all of them in one document makes ownership and maintenance harder.
A giant Markdown document is mostly passive guidance.
It may describe commands that no longer work, paths that no longer exist, or rules that contradict the current codebase.
This problem is not entirely theoretical.
OpenAI has publicly described moving away from a large AGENTS.md
file because it consumed context, became difficult to maintain, and was hard to validate mechanically.
Their solution was to use a shorter AGENTS.md
as a table of contents for a structured repository knowledge base.
That experience supports the direction of this experiment, but it leaves an important question open:
Can this approach become a vendor-neutral, reusable, and measurable repository specification?
I agree with the direction OpenAI has described: AGENTS.md
should not contain the repository's entire operating model.
It should act as an entry point, while the detailed knowledge lives in a modular and versioned repository structure.
A small boot.
The actual repository knowledge could live in a versioned and modular structure:
AGENTS.md
↓
.harness/
├── architecture
├── environment
├── validation
├── workflows
└── manifest
The .harness
directory is a proposed convention, not something coding agents currently understand automatically.
In the first version, AGENTS.md
would remain the supported entry point and instruct the agent how to discover and use the repository harness.
The exact filenames are intentionally undefined at this stage.
For example, testing could be part of validation in a small project:
validation/
└── testing rules and commands
A larger project might need a dedicated testing document containing:
The goal is not to force every repository into the same directory tree.
The goal is to define capabilities that agents can discover.
With a modular harness, an agent working on a domain bug might load:
Architecture
Testing
Validation
An agent preparing the project for the first time might load:
Bootstrap
Environment
Validation
A task involving deployment might load an entirely different set.
This creates a form of progressive context :
Provide the agent with the context required for the current task, rather than the entire repository handbook.
The approach could potentially improve:
But this is still a hypothesis.
A useful repository harness should not consist only of Markdown files.
Whenever possible, instructions should point to executable and reproducible operations.
Instead of documenting a long sequence of test commands, the repository could expose:
./scripts/test-unit
./scripts/test-integration
./scripts/validate
The Markdown explains:
The script defines how the operation is performed.
This also makes the repository easier to validate through CI and less dependent on an agent correctly reproducing a sequence of commands.
The same concept could eventually apply before coding begins.
A team using Jira, GitHub Issues, Linear, Azure DevOps, another issue tracker, or an internal product backlog might define a repository-specific Definition of Ready.
Before a task enters the implementation pipeline, an agent could verify whether:
The team could also encode its agreed Definition of Done in the repository harness before implementation begins.
During and after implementation, the agent could use that definition to determine which tests, validations, reviews, documentation updates, and manual checks are required before considering the task complete.
I am starting an open project called Repository Harness Specification.
The first goal is to compare two versions of the same repository:
AGENTS.md
All instructions are contained in one large file.
AGENTS.md
.harness/
The same information is organized into task-relevant modules that the agent can discover and load as needed.
I plan to evaluate both approaches using the same:
The experiment will measure more than token consumption.
Possible metrics include:
Reducing tokens is not useful if the agent produces worse code.
The real objective is to determine whether modular repository context can improve efficiency without reducing implementation quality.
The project will be developed publicly.
The next steps include:
The structure presented in this article is not the final specification.
It is the first experiment.
Coding agents are evolving quickly.
Now we need to understand how repositories should evolve with them.
The project is available at:
Repository Harness Specification
https://github.com/Repository-Harness-Specification
Feedback, criticism, and contributions are welcome.