AGENTS.md is a Markdown file placed at the root of a repository that provides AI coding agents with persistent, project-specific operational guidance: build commands, coding conventions, testing rules, and constraints the agent cannot infer from the codebase alone. Building an effective AGENTS.md requires writing only what agents cannot discover independently, structuring rules for machine parsing rather than human readability, and accepting a measurable inference-cost trade-off whose return in task success is still unproven.
TL;DR
An AGENTS.md costs tokens on every invocation, and the evidence it earns them is thin. ETH Zurich and LogicStar.ai measured context files across two benchmarks: neither generated nor developer-written files improved task success significantly, while inference cost rose over 20%. Developer-written files beat generated ones by 7%. This guide covers what belongs in yours.
Why AI Coding Agents Need a Context File
Every coding agent, whether Claude Code, Cursor, GitHub Copilot, or Codex, starts each session blind to your project's specific conventions. The agent knows how to write Python or TypeScript in general, but it does not know that your team uses Pixi instead of pip, that your API client never throws exceptions, or that the vendor/ directory should never be modified.
Before AGENTS.md emerged as a standard, teams maintained a patchwork of tool-specific files to communicate these constraints. Augment Code's junk drawer post of February 27, 2026, describes the result: "Open a typical project that's been through a few months of AI-assisted development. You'll find some combination of CLAUDE.md, .cursorrules, copilot-instructions.md, AGENTS.md, and maybe a gemini.md for good measure. Almost the same content in each one. Slowly drifting apart."
The spec defines AGENTS.md as "Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." OpenAI released it in August 2025, and the spec site reports the format in use across more than 60,000 open-source projects. On December 9, 2025, the Linux Foundation announced the Agentic AI Foundation (AAIF), which now stewards AGENTS.md alongside Anthropic's Model Context Protocol (MCP) and Block's goose.
| File | Primary Audience | Purpose |
|---|---|---|
| README.md | Human developers | Project overview, installation, usage |
| CONTRIBUTING.md | Human contributors | How to submit PRs, code style for humans |
| AGENTS.md | AI coding agents | Build commands, test runners, conventions, constraints for autonomous agents |
The Quality Threshold: What ETH Zurich Found About Context File Effectiveness
Evaluating AGENTS.md, a preprint from ETH Zurich and LogicStar.ai revised on June 23, 2026, set out to measure whether context files earn their cost. The authors ran four models across two benchmarks: SWE-bench Lite tasks with generated context files, and CTXbench, a purpose-built set of 138 issues from 12 repositories that already carry developer-committed files. Its headline finding is that context files did not improve task success significantly in either setting.
Generated files add cost without adding measurable success. LLM-generated context files lowered the average resolution rate by 0.5% on SWE-bench and 2% on CTXbench, differences the paper reports at p-values of 0.87 and 0.37 and calls insignificant. They reduced success in 5 of 8 tested settings and added 2.45 and 3.92 steps per task. The cost increase, 20% and 23%, is the one change that was significant.
Developer-written files beat generated ones without beating no file at all. Human-written files improved performance by 2.4% on average, which at p = 0.21 is also not significant. The gap between the two kinds of file is significant: developer-committed files outperformed generated ones by 7% on average at p = 0.038, and cost at most 19% more than running with no context file.
| Context File Type | Cost Increase | Task Success Change | Statistically Significant |
|---|---|---|---|
| LLM-generated (auto-init) | 20% (SWE-bench), 23% (CTXbench) | -0.5% (SWE-bench), -2% (CTXbench) | No, p = 0.87 and p = 0.37 |
| Developer-written (human-curated) | Up to 19% | +2.4% on average | No, p = 0.21 |
| Developer-written against LLM-generated | Lower than LLM-generated | +7% on average | Yes, p = 0.038 |
| No context file | Baseline | Baseline |
A follow-up experiment removed the rest of the repository's documentation before re-evaluating. Under those conditions generated files improved performance by 2.7% on average and outperformed developer-written ones across settings. That is the paper's own explanation for the anecdotal reports that agents do better once a context file is added. In a repository with thin documentation, the context file is the documentation.
The trace analysis shows where the cost goes. Instructions in context files are followed well, which produces more testing and exploration and therefore more steps. Repository overviews are the part that does not work.
What "Non-Inferable Details" Means in Practice
The paper's own recommendation is narrow. Human-written context files "should only include instructions required for coding agents that are not already present in the README (e.g., specific conventions or non-functional requirements), and be rigorously evaluated before adoption."
| Content Type | Include? | Reason |
|---|---|---|
| Custom build commands not documented elsewhere | Yes | Non-inferable |
| Highly specific tooling choices (e.g., pixi instead of pip) | Yes | Non-inferable |
| Codebase overviews and architecture summaries | No | Agents find these independently |
| Anything already in README or existing docs | No | Redundant; increases steps and cost |
The paper is blunt about the overview section: "repository overviews, although popular and recommended by model providers, are not helpful." Eight of the twelve developer-written files in CTXbench carried a codebase overview and four of those enumerated directories. That section returned nothing measurable, and still cost tokens on every invocation.
Core Sections Every AGENTS.md Needs
GitHub analysis of more than 2,500 files and Codex documentation converge on the same six sections. Each one targets a specific class of agent error, and each holds what an agent cannot recover from the repository on its own.
Section 1: Stack Definition With Exact Versions
Without version constraints, the agent defaults to whichever API conventions are most represented in training data. The Inngest repo illustrates the principle, specifying versions hard, signaling non-negotiable constraints explicitly:
Section 2: Executable Commands With Full Flags
Place commands early; the agent references them repeatedly throughout a task. From mcollina/skills:
The spec's FAQ states that an agent "will attempt to execute relevant programmatic checks and fix failures before finishing the task," and attaches the condition that decides it. Only the checks you list. An unlisted test command is one the agent has no reason to run.
Section 3: Coding Conventions and Patterns
One real snippet showing your style beats three paragraphs describing it. The most valuable convention to document is the counterintuitive one. The NetCore repo includes this:
Without this, an agent wraps every api call in try/catch. The file explains the mechanism that enables the agent to generalize correctly to novel situations.
Section 4: Testing Rules
From phodal/auto-dev:
For complex build systems, exact commands matter more than guidelines. The CBMC repo includes:
Section 5: "Don't Touch" Zones and Permission Boundaries
"Never commit secrets" was the most common helpful constraint across 2,500+ repositories per GitHub analysis. A three-tier system gives the agent an explicit priority hierarchy when rules interact:
Section 6: Non-Standard Tooling
AGENTS.md delivers the highest ROI for tools underrepresented in LLM training data:
For standard tools like npm, pytest, or cargo, agents already know the conventions. Focus on what the agent genuinely cannot know.
Tool-Specific Variants: CLAUDE.md, .cursorrules, and copilot-instructions.md
AGENTS.md is converging as a cross-tool standard, and three of the four major tools now read the file directly. Claude Code is the exception. Its documentation states that it reads CLAUDE.md, not AGENTS.md, and offers two bridges: an @AGENTS.md import inside CLAUDE.md, which also lets you append Claude-specific instructions below it, or ln -s AGENTS.md CLAUDE.md where no extra content is needed. The same page documents auto memory, on by default, which accumulates notes from your corrections without manual configuration, and a claudeMdExcludes setting that prevents instruction bleed in large monorepos.
Cursor reads AGENTS.md from the project root as a plain-Markdown alternative to its .cursor/rules system, which uses MDC files with frontmatter to scope rules by glob. GitHub Copilot reads .github/copilot-instructions.md for repository-wide defaults, path-specific .instructions.md files carrying an applyTo glob for targeted rules, and AGENTS.md files stored anywhere in the repository. Devin Desktop feeds AGENTS.md into the same rules engine that powers .devin/rules/, with .windsurf/rules/ named as the legacy path.
| Feature | CLAUDE.md | Cursor | Copilot | Devin Desktop |
|---|---|---|---|---|
| Instruction format | Plain Markdown | MDC, Markdown with frontmatter | Plain Markdown | Plain Markdown |
| Multiple rule files | .claude/rules/, discovered recursively | .cursor/rules per subdirectory | .github/instructions/ | .devin/rules/ |
| Path scoping | paths frontmatter | Glob pattern per rule | applyTo frontmatter | Auto-generated glob per subdirectory |
| Rule activation | Loaded every session | Always, glob, agent-requested, or manual | Repository-wide plus glob-scoped files | Root always-on, subdirectory glob-scoped |
| Reads AGENTS.md | No, reads CLAUDE.md | Yes | Yes | Yes |
For multi-tool teams, the symlink pattern keeps files from diverging. The Next.js repository's AGENTS.md opens with the note that "CLAUDE.md is a symlink to AGENTS.md. They are the same file." Which file a given tool loads, and which one wins when several disagree, is a separate question from what belongs in the file.
Modular Rules: When and How to Split Your Context File
A monolithic AGENTS.md loads every rule into the agent's context on every invocation. Start with a single file and split it into subdirectories when it outgrows one. Anthropic sets the target for the equivalent file at under 200 lines, on the stated grounds that longer files consume more context and reduce adherence. The maas repo sits at the other end at 458 lines, every one of them paid for on every invocation, which is the scale at which splitting starts saving real token budget.
Place context files at any directory level; the agent reads the file closest to the file being edited:
Codex documents the mechanism as concatenation, not replacement: it joins files from the root down, and "files closer to your current directory override earlier guidance because they appear later in the combined prompt." It also stops adding files once their combined size reaches project_doc_max_bytes, 32 KiB by default, so a deep tree can lose its leaf instructions without saying so.
| Condition | Approach |
|---|---|
| Root file under roughly 200 lines | A single root file is sufficient |
| Root file past roughly 200 lines | Split: root for org-wide standards, subdirectory files for specifics |
| A deep tree under Codex | Watch the 32 KiB combined cap; leaf files past it are silently dropped |
| Cross-cutting concerns (security, testing, CI) | Path-scoped rule files, loaded when a matching file is touched |
| Multiple AI tools in use | One canonical AGENTS.md, with an import or a symlink per tool |
The Cost Tradeoff: Roughly 20% Inference Overhead
The same preprint measured the following overhead across context file types:
| Metric | Value |
|---|---|
| Inference cost increase (LLM-generated context files) | 20 to 23% |
| Inference cost increase (developer-provided context files) | Up to 19% |
| Additional steps per task (LLM-generated files) | 2.45 on SWE-bench, 3.92 on CTXbench |
| Reasoning token increase (GPT-series, LLM-generated files) | +10% to +22% |
| Reasoning token increase (GPT-series, human-written files) | +2% to +20% |
Using Claude Sonnet 5 pricing ($2.00/MTok input, $10.00/MTok output) with a baseline agentic task of roughly 50K input tokens and 5K output tokens:
| Monthly Task Volume | Monthly Overhead Cost |
|---|---|
| 1,000 tasks | ~$30 |
| 10,000 tasks | ~$300 |
| 100,000 tasks | ~$3,000 |
Prompt caching is the primary mitigation; cache reads are 90% cheaper than standard input pricing. The overhead applies whether the file is auto-generated or human-written, and neither kind bought a significant gain in task success. What the numbers do settle is the choice between them. A file someone wrote beats a file a model generated by 7%, and costs less than the generated one. That makes the decision about which file to commit, not about whether the overhead pays for itself.
Failure Patterns That Undermine AGENTS.md
Auto-generated files buy nothing measurable. Per the ETH preprint, LLM-generated files moved task success rates by -0.5% to -2%, neither difference statistically significant, while raising inference costs by over 20%. Rules should respond to observed failure, not be generated speculatively.
Context file bloat reduces task success. More rules do not produce better performance. Every time an agent makes a mistake, the default reaction is to add another rule. Rules are rarely removed. The file accumulates contradictory patches and one-off fixes, working directly against effective context engineering. Augment Code's notes on the format make the argument from the other side: a good file behaves like a model upgrade.
A context file is context, not configuration. Anthropic's documentation is explicit. The file's content "is delivered as a user message after the system prompt, not as part of the system prompt itself," and there is "no guarantee of strict compliance, especially for vague or conflicting instructions." Keep files short, place critical rules early, and start new sessions for new tasks. Where an instruction has to run at a fixed point, not merely be weighed, the documented answer is a hook, which executes regardless of what the agent decides.
Stale structural references actively mislead. Context files documenting repository structure become liabilities when the codebase changes, and the measured result is that they do not help even while they are accurate. A directory listing goes stale faster than anything else in the file and returns the least while it lasts.
Complete AGENTS.md Template
This template synthesizes patterns from Codex guidance, GitHub analysis, and production repositories, including Vercel Next.js and Inngest repo.
Keep this file under version control and treat updates as code changes. Remove the "Project Structure" section if your directory layout follows framework conventions the agent already knows. The "Non-Obvious Patterns" section is where AGENTS.md delivers the highest signal-to-noise ratio.
What a Context File Cannot Enforce
A context file states what the team decided. It does not make the decision hold, because it is read as guidance and weighed against everything else in the context window.
A Markdown file cannot know what is in the repository. Augment Code's Context Engine indexes and maps relationships across hundreds of thousands of files, so the questions a repository overview handles badly in prose get answered from the code. Augment Code publishes the Context Engine as an MCP server, and an agent working from an AGENTS.md can query it during cross-service refactoring without inferring structure from a list.
Nor can it enforce a boundary, only ask for one. Cosmos, Augment Code's unified cloud agents platform, available on all paid plans, moves that boundary out of prose and into configuration. An Expert is a reusable template carrying its own Environment, capabilities and memory, so what an AGENTS.md asks an agent to respect, an Expert's configuration settles first. Cosmos Sessions are saved indefinitely and can be reopened, so what an agent did stays readable while its Environment is disposable. The context file still does the one job nothing else does, carrying decisions a reader cannot derive from the code.
What to Do Next
Keeping an AGENTS.md accurate is harder than writing one. Non-inferable details, counterintuitive patterns, and custom tooling constraints deliver the highest signal, but they drift fastest as codebases evolve.
Start with the template above. Focus the first version on commands, boundaries, and the one or two architectural decisions that look wrong to an outsider but are intentional. Version-control changes and review them like code. Then keep it honest. Measure whether the file changed anything before adding to it, because the one clear result is that a file someone wrote beats a file a model generated.
Frequently Asked Questions About Building AGENTS.md
Related Reading
Written by
Ani Galstian
Ani writes about enterprise-scale AI coding tool evaluation, agentic development security, and the operational patterns that make AI agents reliable in production. His guides cover topics like AGENTS.md context files, spec-as-source-of-truth workflows, and how engineering teams should assess AI coding tools across dimensions like auditability and security compliance