TL;DR: ETH Zurich’s SRI Lab evaluated whether repository-level context files like AGENTS.md actually help coding agents, and the answer is nuanced: structure and specificity matter more than raw length. Treating the file as a trainable artifact, refined iteratively like gradient descent, measurably improves LLM output quality.
When OpenAI’s Codex, Cursor, and OpenCode all converged on the same convention — a plain Markdown file named AGENTS.md sitting at the repository root — a de facto standard was born. Yet almost nobody could say whether these files genuinely improve agent-generated code. That changed when ETH Zurich’s SRI Lab put the question to a systematic evaluation, and the results complicate the hype.
So does the file live up to its reputation? Sometimes. The SRI Lab study found that context files can improve agent performance on repository-specific tasks, but the effect depends heavily on how the file is written. Vague, generic guidance adds noise. Precise, project-specific instructions add signal.
What Is an AGENTS.md File and Why Did It Emerge?
An AGENTS.md file is a plain Markdown document placed in a repository that provides standing instructions to AI coding agents: build commands, test procedures, code style rules, architectural conventions, and areas of the codebase to avoid touching. Think of it as a README written for machines instead of humans.
According to OpenCode’s documentation, you provide custom instructions by creating an AGENTS.md file, and the approach is explicitly compared to Cursor’s rules — a similar mechanism that injects persistent guidance into every agent session. The file’s contents get included in the context the model sees, so every edit, commit, or refactor happens against the same baseline of project knowledge.
Why did it emerge at all? Because agents kept failing in predictable ways. They guessed at build systems, invented test commands, and violated project conventions that any human contributor would have learned in week one. A repository-level instruction file is the cheapest possible fix: no fine-tuning, no tooling changes, just text. The format spread organically because it required nothing more than a file.
The key insight is placement. Because AGENTS.md lives inside the repo, it is versioned, reviewed, and updated alongside the code it describes. Instructions evolve with the project. That is what separates it from chat-level prompts, which vanish between sessions.
Does Research Confirm That AGENTS.md Improves Agent Coding Performance?
Partially — and the nuance matters more than the headline. ETH Zurich’s SRI Lab, in its evaluation “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?”, found that repository-level context files can improve coding agent performance, but the benefit is conditional on the file’s content rather than guaranteed by its existence.
The study’s central finding is that specificity beats volume. Context files containing precise, actionable instructions — exact commands, exact paths, exact constraints — improved agent outcomes on repository-specific tasks. Files stuffed with generic advice, boilerplate style rules, or long philosophical statements about code quality did not. In some configurations, bloated context files actively hurt performance by crowding out more useful context within the model’s attention window.
This reframes the question developers should ask. Instead of “should I add an AGENTS.md?” the better question is “what belongs in mine?” A short file with five commands the agent will actually run outperforms a long file describing how the team feels about clean code. Every token competes for attention.
The practical takeaway from the research is measurable: instruction quality is a variable you control, and it directly moves agent output quality. Treat the file as engineering artifact, not documentation decoration. Iterate on it like code.
How Should You Structure an AGENTS.md File for Better Code Quality?
Start with commands, then constraints, then conventions — in that order of priority. The SRI Lab findings imply a structure where the most actionable, verifiable information sits at the top, because that is the information agents can act on immediately and unambiguously.
A structure that follows from the research and tooling docs looks like this:
- Build and test commands — exact invocations, e.g.
pnpm test --filter core - Verification steps — how to confirm a change works before committing
- Directory map — where source, tests, and configs live
- Hard constraints — files or patterns the agent must never modify
- Code style rules — only project-specific deviations, not general taste
- Dependency policy — when adding packages is allowed
- Commit conventions — message format, branch naming
- Known pitfalls — commands that fail, flaky tests to ignore
Notice what is absent: essays. Generic advice like “write clean, maintainable code” consumes context without changing behavior, and the SRI Lab evaluation indicates this kind of filler dilutes the useful signal. Each line should either command an action or forbid one.
Consistency across tools is the second structural concern. As the guide from aq.dev explains, teams running multiple agent CLIs should make AGENTS.md the single source of truth for Codex, Cursor, and OpenCode, then bridge Claude Code with an import or symlink. This prevents instruction drift, where different agents follow different rules because someone updated one file and forgot the other three. One file, many consumers.
Why Do Developers Call AGENTS.md a ‘Neural Net’ You Train Over Time?
Because the feedback loop looks like training. Kun Chen’s essay “Your AGENTS.md is a Neural Net” argues the file should be maintained the way you train a model: observe where the agent’s output deviates from what you want, encode the correction as an instruction, and repeat. Each failed generation is a training signal.
The analogy maps surprisingly well onto gradient descent. In machine learning, you compute the error between prediction and target, then adjust weights to reduce it. With AGENTS.md, you observe the gap between generated code and acceptable code, then adjust instructions to close it. Over weeks, the file accumulates the project’s hard-won lessons — the quirk in the test runner, the module with hidden coupling, the lint rule that must run before every commit.
The SRI Lab’s findings validate this iterative approach indirectly. If specificity drives performance, then iteration drives specificity: you cannot know on day one which instructions matter. You discover them through failure. A file refined over fifty pull requests contains far denser signal than one written in a single sitting.
The practical discipline is simple. When an agent produces wrong code twice for the same reason, that is a gradient. Add a line. When an instruction never changes behavior, delete it. Dead instructions are noise, and noise costs attention. The file converges toward the minimum set of rules that reliably steers the model — which is, in the end, exactly what training is.
How Do Different Agent CLIs Handle Rules and Instruction Files?
AGENTS.md has quietly become the closest thing to a standard for repository-level agent instructions, but each CLI loads it differently. OpenCode’s documentation states plainly that you can provide custom instructions by creating an AGENTS.md file, and describes it as “similar to Cursor’s rules” — instructions that will be included in the agent’s context on every session. That phrasing matters, because it confirms the file is injected automatically, not discovered on demand.
The broader ecosystem tells a similar story. Codex reads AGENTS.md natively, Cursor supports it alongside its own .cursor/rules format, and OpenCode treats it as the primary mechanism for custom instructions. Claude Code, however, still looks for CLAUDE.md by default. So one repository can end up with two competing instruction files that slowly drift apart. This fragmentation is exactly why multi-tool setups need a deliberate sync strategy rather than hoping for the best.
The practical consequence is simple. Teams that standardize on AGENTS.md as the canonical file, then bridge other formats to it, maintain a single source of truth. Teams that don’t end up with contradictory instructions across tools — and contradictory instructions produce contradictory code.
How Do You Keep AGENTS.md and CLAUDE.md in Sync Across Tools?
The recommended pattern is to make AGENTS.md the single source of truth for Codex, Cursor, and OpenCode, then bridge Claude Code to it through an import or a symlink. This approach, documented as a practical guide to stopping “instruction drift,” acknowledges a real failure mode: when two files carry overlapping rules, one gets updated and the other rots.
How does this work mechanically? Claude Code supports an import syntax that lets CLAUDE.md pull in the contents of another file. A one-line CLAUDE.md containing an import reference to AGENTS.md means every Claude Code session reads the same rules as every other CLI. Alternatively, a symlink replaces CLAUDE.md entirely with a pointer to AGENTS.md. Either way, there is one file to edit.
The alternative — maintaining parallel files by hand — fails predictably. A rule added to CLAUDE.md after a debugging session never reaches Codex. A deprecated convention gets removed from AGENTS.md but lingers in the Cursor rules. The agent then receives conflicting guidance, and conflicting guidance is worse than no guidance at all. One file, many consumers. That’s the whole trick.
What Common Mistakes Make AGENTS.md Files Ineffective?
The most common mistake is treating AGENTS.md as a dumping ground for everything anyone might ever want the agent to know. Kun Chen’s essay “Your AGENTS.md is a Neural Net” frames the file as something you train iteratively — you don’t write it once, you adjust it based on the errors the agent actually makes, like gradient descent applied to instructions. Files written speculatively, before any agent session, tend to be full of rules that never matter.
Other recurring failure patterns include:
- Vague platitudes (“write clean code”) instead of verifiable conventions (“always use
uv run pytest“) - Rules that contradict the actual codebase, which the model resolves unpredictably
- Duplicating information already discoverable from the code itself
- Instructions about topics the agent cannot act on, like company org charts
- Stale rules for tools or commands that were replaced months ago
- One enormous file where critical rules drown in noise
- Never updating the file after observing repeated agent mistakes
- Copying another repository’s AGENTS.md wholesale without adapting it
The fix is disciplined editing. When the agent makes the same mistake twice, add a rule. When a rule never changes behavior, delete it. Chen’s framing makes this concrete: each edit is a training step, and the loss function is the frequency of agent errors you have to correct manually.
When Should Instructions Live in AGENTS.md Instead of System Prompts?
Instructions belong in AGENTS.md when they are facts about the repository rather than facts about the assistant. Build commands, test invocation, architectural conventions, commit message format, and “never touch this generated directory” warnings are all repository properties. They should travel with the code, be version-controlled alongside it, and apply to every agent a contributor might use.
System prompts, by contrast, suit persona and behavior shaping that is tool-specific or personal. The OpenCode documentation positions AGENTS.md as the mechanism for custom instructions within that tool — meaning the file is the sanctioned, portable channel for project-level rules, not the prompt you type at session start. Retyping