Coding Agents Evolved. Our Repositories Didn’t.

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, maintain, and discuss the rules. Someone changing a test should not need to navigate through multiplayer architecture, asset conventions, deployment rules, and UI standards.

Unrelated context may be loaded

A small bug in a domain class may not require information about:

• production deployment
• UI assets
• database migrations
• release procedures
• external integrations

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.

Different knowledge changes at different speeds

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.

The file becomes difficult to validate

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?

A Repository Harness

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 bootloader.

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:

• when to use unit tests
• when to use integration tests
• how to run each suite
• mocking and fake conventions
• test naming standards
• patterns for writing new tests

The goal is not to force every repository into the same directory tree. The goal is to define capabilities that agents can discover.

Progressive Disclosure of Repository Context

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 loading: provide the agent with the context required for the current task, rather than the entire repository handbook.

The approach could potentially improve:

• context efficiency
• token usage
• instruction discoverability
• human readability
• documentation ownership
• consistency between different coding agents

But this is still a hypothesis.

Documentation Is Not Enough

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:

• when the command must be used
• what it validates
• what failure means
• which exceptions are allowed

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.

Beyond Implementation Tasks

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:

• acceptance criteria are clear
• required architectural context exists
• dependencies are identified
• the task conflicts with existing documentation
• expected validation is defined
• important information is missing

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.

The Experiment

I am starting an open project called Repository Harness Specification. The first goal is to compare two versions of the same repository:

• Monolithic AGENTS.md: All instructions are contained in one large file.
• Modular 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:

• coding agent
• model
• repository
• starting commit
• implementation task
• validation criteria

The experiment will measure more than token consumption. Possible metrics include:

• input tokens, when exposed by the selected agent or runtime
• cached and uncached input tokens, when available
• task success rate
• tests passed
• validation failures
• files changed outside the expected scope
• number of correction cycles
• execution time

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.

Building It in Public

The project will be developed publicly. The next steps include:

• defining the minimum repository harness
• migrating a real project manually
• creating reproducible benchmark tasks
• comparing monolithic and modular context
• publishing the results
• building a CLI to initialize and validate repository harnesses
• exploring integrations with different coding agents

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

Feedback, criticism, and contributions are welcome.