AGENTS.md Is Not Context. It Is a Control Surface.

The short version

There is a tempting story about repository-level instruction files like AGENTS.md, CLAUDE.md, or .cursorrules.

The story goes like this: coding agents fail because they do not understand the repo. So we should give them more context. Add architecture notes. Add test commands. Add style rules. Add “how we do things here.” Then the agent will behave more like a senior developer who has lived in the codebase for years.

It is a nice story.

It is also incomplete.

A recent paper, Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, looks directly at this question. The authors compare coding-agent performance with no context file, an LLM-generated context file, and a developer-written context file.

The awkward finding is not that context files are ignored.

The awkward finding is that they often work.

They change agent behavior. Agents read more files, search more, run more tests, and use more repo-specific tools. Sometimes that is exactly what you want. Sometimes it turns a small patch into a ritual.

3

conditions: none, generated, developer-written

138

AGENTBENCH Python tasks

1

question: which behavior did the file induce?

The wrong question

The obvious question is:

Do AGENTS.md files help?

The better question is:

What behavior does this file induce,
and when is that behavior worth the cost?

That distinction matters.

Most teams still treat AGENTS.md like onboarding documentation. But coding agents are not new hires. A human can skim a long document, ignore irrelevant sections, remember the spirit of a rule, and apply judgment.

An agent may treat every sentence as live operational pressure.

If the root context file says:

• always inspect the architecture docs
• always run the full test suite
• always check these five directories
• always use this repo-specific tool
• always consider edge cases around every subsystem

then the agent may drag even a two-line fix through that process.

From a benchmark perspective, that looks inefficient. From a harness perspective, it is more precise: the instruction file became an unconditional control mechanism.

That is the key shift.

AGENTS.md is not just context.

It is a control surface.

AGENTS.md as control surface

not repo knowledge → better agent, but instruction → behavior

1. 01
   Instruction
2. 02
   Attention
3. 03
   Tool use
4. 04
   Verification
5. 05
   Cost
6. 06
   Outcome

More context can make work worse

Once you see AGENTS.md as a control surface, “more context” stops sounding automatically good.

More context can mean more friction.

More rules can mean more false obligations.

More repo knowledge can mean more irrelevant exploration.

More helpful guidance can mean more ways to distract the agent from the actual task.

This does not mean AGENTS.md is bad. It means blunt context injection is bad.

The paper’s result fits a pattern many agent teams already see in practice: instructions can make agents more thorough without making them more successful.

That is an expensive failure mode because it feels responsible.

The agent searched more. It ran more commands. It mentioned more repo-specific facts. It looked careful.

But careful is not the same as correct.

Thorough is not the same as done.

Generated context has the wrong incentives

LLM-generated AGENTS.md files are especially fragile because they tend to summarize what is visible.

Visible is not the same as important.

A generated context file can easily restate obvious folder structure, mention tools without knowing when they matter, or inflate weak conventions into hard rules.

Developer-written context is better because it can encode taste and scars:

Do not edit this generated file.
This test suite is flaky; use this narrower command first.
This package looks unused but is loaded dynamically.
Never change this API without checking the mobile client.
For copy-only changes, skip the full e2e suite.

That kind of instruction reduces uncertainty instead of increasing it.

The best repo context does not describe everything.

It prevents known bad behavior.

Repo manual vs. control surface

Repo manual

• Explains the whole architecture.
• Adds general advice.
• Loaded globally.
• Optimized for completeness.
• Feels helpful.

Control surface

• Routes the agent to relevant context.
• Defines concrete behavior.
• Loaded conditionally by task and path.
• Optimized for outcome and cost.
• Is measured through traces and evals.

Root AGENTS.md should be boring

A good root AGENTS.md should be short. It should contain only instructions that are almost always true.

Put the boring invariants there:

• preferred package manager
• cheap setup commands
• default test or lint commands
• generated files that must not be edited
• external actions that require approval
• rules about secrets, deploys, migrations, payments, and unrelated changes

Everything else should be conditional.

If you touch frontend code, read docs/frontend.md.
If you change database migrations, read docs/database.md.
If you edit auth, stop and check docs/security.md.
If the task is copy-only, do not run the full integration suite.
If the diff touches more than 5 files, explain why before continuing.

That is a very different philosophy from “put all the context in the prompt.”

It is closer to harness design.

The harness should decide which instructions to load based on the task, path, risk level, and current failure mode.

A small CSS fix should not receive the same operational context as a database migration. A failing unit test should not trigger the same loop as a multi-service refactor. An agent doing triage needs different context from an agent preparing a production patch.

What belongs in the root file

• Rules that apply to almost every task.
• Commands that are cheap and reliable.
• Boundaries that prevent expensive mistakes.
• Approval gates for external or destructive actions.
• Pointers to conditional files, not the full content of every file.

Context should route, not flood

The future is not better one-shot prompts.

It is better loops.

A coding loop should look more like this:

classify task
load relevant instructions
inspect smallest useful code slice
make focused change
run cheapest meaningful verification
inspect diff
retry only on actionable failure
escalate on ambiguity or risk

In that model, AGENTS.md is not the whole brain. It is one input into the loop.

The loop decides when to read it, how much to apply, and when to ignore parts of it.

That is the part many teams miss. They keep improving the static file when they should improve the context-loading policy.

The question is not:

What else can we tell the agent?

The question is:

What does the agent need right now to make the next decision?

Those are not the same question.

Measure instructions like code

Agent instructions should be evaluated like code changes.

If adding a rule makes agents slower without making them more correct, it is not a good rule.

If a context file makes agents “more thorough” but not more successful, it may just be expensive anxiety.

If a generated AGENTS.md causes extra exploration without preventing real mistakes, delete or narrow it.

If a developer-written rule repeatedly prevents bad diffs, keep it.

The traces matter:

• which files did the agent read?
• which commands did it run?
• which tools did it call?
• how many retries happened?
• where did it stop?
• did the instruction change the outcome or only the ceremony?

That is how context engineering becomes engineering instead of prompt folklore.

Writing better AGENTS.md files

Do

• ✓ Keep root instructions short and testable
• ✓ Use conditional files for task-specific guidance
• ✓ Write rules that prevent known failure modes
• ✓ Measure behavior changes through traces and evals
• ✓ Delete rules that only add ceremony

Do not

• × Turn AGENTS.md into an architecture essay
• × Load every rule for every task
• × Treat generated context as domain expertise
• × Mistake extra tool use for better work
• × Assume more context means more reliability

The practical rule

Write AGENTS.md like you are programming agent behavior, not documenting the repo.

Every instruction should earn its place.

Ask:

• does this apply to most tasks?
• is it concrete enough to execute?
• does it reduce search or increase it?
• does it prevent a real failure mode?
• should it be conditional instead of global?
• can the harness enforce this better than prose?
• would I want this instruction applied to a one-line fix?

If the answer is no, the instruction probably does not belong in the root file.

The best agent context is not maximal.

It is selective.

Short root file. Hierarchical task files. Clear triggers. Concrete commands. Explicit stop conditions. Measured outcomes.

The goal is not to tell the agent everything.

The goal is to make the agent load the right thing, at the right time, for the right reason, and stop when the job is done.