# AGENTS.md Is Not Context. It Is a Control Surface. Canonical URL: https://huecki.com/en/blog/agents-md-control-surface-en/ Markdown URL: https://huecki.com/en/blog/agents-md-control-surface-en.md Language: English Published: 2026-06-08 Updated: 2026-06-08 Author: Dominic Hückmann Topic: AI-first Engineering - Agent topics: Agent Harnesses, Context Engineering, Agent Evals, LLM-native Engineering - Tags: AI Engineering, Coding Agents, AGENTS.md, Context Engineering, Developer Workflow Content status: field-note ## Summary The surprising lesson from AGENTS.md benchmarks is not that context files are useless. It is that they change agent behavior, sometimes into more expensive and less useful work. Treat them as a control surface, not a repo manual. ## Description A new AGENTS.md benchmark shows the awkward part: repo context files often work. They change agent behavior. The question is whether that behavior is worth the cost. ## Body ## 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?*](https://arxiv.org/abs/2602.11988), 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. ## The wrong question The obvious question is: ```txt Do AGENTS.md files help? ``` The better question is: ```txt 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. ## 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: ```txt 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. ## 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. ```txt 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. ## 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: ```txt 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: ```txt What else can we tell the agent? ``` The question is: ```txt 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. ## 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. ## FAQ ### Are AGENTS.md files useless? No. The better reading is that AGENTS.md files change agent behavior, and that behavior needs to be designed and measured instead of assumed helpful. ### Why can repo context files make agents less efficient? They can induce extra reading, searching, testing, and tool use. That may be good for risky tasks, but wasteful for small changes. ### What should go into a root AGENTS.md? Only rules that are almost always true: setup, cheap checks, hard boundaries, approval gates, and pointers to conditional task-specific files.