AGENTS.md is a Markdown file providing AI coding agents with project-specific operational guidance like build commands and conventions, established in December 2025 under the Linux Foundation's Agentic AI Foundation to standardize context for autonomous AI, according to Augment Code.
Key Points:
AGENTS.md offers persistent, project-specific context for AI coding agents to overcome their inherent lack of detailed project knowledge.
ETH Zurich research shows human-curated files modestly improve agent performance by roughly 4%, while LLM-generated ones reduce success rates and increase costs.
The file should focus on non-inferable details, such as custom build commands and unique tooling, to avoid redundancy with existing documentation.
This lack of context led to a proliferation of tool-specific files until AGENTS.md emerged, offering a single, predictable location for critical instructions, similar to a README for agents.
Why Do AI Agents Need Specific Context Files?
Agents lack project-specific details such as custom commands, coding conventions, or testing rules, requiring context files to perform accurately. While they understand general languages like Python or TypeScript, they cannot infer unique team practices or forbidden zones independently, according to Augment Code.Before AGENTS.md, development teams managed a disparate collection of files like CLAUDE.md and copilot-instructions.md. These files often contained similar content, leading to maintenance challenges and consistency drift.
OpenAI initially pioneered the AGENTS.md format for its Codex model. In December 2025, it was donated to the Linux Foundation's Agentic AI Foundation to foster standardization.
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 |
How Effective Are Different Context File Approaches?
ETH Zurich research in 2026 found that LLM-generated context files reduce AI agent task success rates by 0.5% to 2% and increase inference costs by 20% to 23%. In contrast, human-curated files yield a marginal 4 percentage point performance gain, making manual curation essential, according to Augment Code.
The study emphasized that LLM-generated files often duplicate existing documentation, adding cost without improving performance. Human-written files are effective when they focus on details agents cannot infer from the codebase.
Context File Type | Cost Increase | Task Success Change |
|---|---|---|
LLM-generated (auto-init) | +20 to 23% | −0.5% (SWE-bench Lite) to −2% (AGENTbench) |
Developer-written (human-curated) | Up to 19% (shorter files, lower cost than LLM-generated) | Marginal improvement (AGENTbench) |
No context file | Baseline | Baseline |
What Should an AGENTS.md File Include?
Effective AGENTS.md files prioritize minimal requirements, custom commands, and specific tooling choices that agents cannot infer, avoiding codebase overviews or architecture summaries. Core sections include stack definitions with exact versions, executable commands, coding conventions, testing rules, and "don't touch" zones, as recommended by OpenAI and GitHub analysis.Key content includes specifying exact stack versions (e.g., Node 22.x, pnpm), full executable commands (`npm install`, `npm run typecheck`), and concise coding conventions. Documenting counterintuitive patterns like a custom `ApiResult` instead of exceptions proves highly valuable.
Testing rules (e.g., unit tests for new functionality, mocking dependencies) and clear boundaries (e.g., "Never commit secrets") also guide agent behavior effectively. The file should focus on non-standard tooling where agents lack inherent knowledge.
What About Modularity and Multi-Tool Support?
While AGENTS.md aims for a cross-tool standard, tool-specific variants like CLAUDE.md or .cursorrules persist. For multi-tool teams, symlinking AGENTS.md to tool-specific files (e.g., CLAUDE.md is a symlink to AGENTS.md) prevents content divergence.Modular organization becomes necessary for larger projects, typically when a root AGENTS.md exceeds 150-200 lines. Files can be placed at any directory level, with more deeply nested files taking precedence in case of conflicting instructions, per the Codex spec.
Condition | Approach |
|---|---|
Single root file under 150-200 lines | Monolithic root file sufficient |
Rules exceed 150-200 lines | Split: root for org standards, subdirectory files for specifics |
Multiple AI tools in use | Canonical AGENTS.md + tool-specific symlinks |
What Is the Cost of Using AGENTS.md?
Implementing AGENTS.md files incurs an inference overhead of roughly 20% regardless of whether they are auto-generated or human-written, primarily due to increased token processing. For a task with 50K input tokens and 5K output tokens, this can translate to a monthly overhead of ~$45 for 1,000 tasks, according to Augment Code.
The overhead applies because the agent processes the context file as part of its input. Prompt caching can mitigate this, as cache reads are significantly cheaper than standard input pricing. Human-curated files are worth the cost due to performance gains.
Metric | Value |
|---|---|
Inference cost increase (LLM-generated context files) | 20 to 23% |
Inference cost increase (developer-provided context files) | Up to 19% |
Reasoning token increase (GPT-series, LLM-generated files) | +14% to +22% |
Reasoning token increase (GPT-series, human-written files) | +2% to +20% |
How Does AGENTS.md Address Agent Limitations?
AI coding agents, while proficient in general programming tasks, are inherently limited by their lack of project-specific contextual understanding, leading to errors and inefficiencies. AGENTS.md aims to bridge this gap by providing explicit instructions that define unique project rules, build systems, and architectural constraints, thereby enhancing an agent's ability to operate within a specific codebase effectively.Failure patterns include auto-generated files reducing success rates and increasing costs, and context file bloat leading to poor performance. Developers must respond to observed agent failures with new rules, rather than speculative generation, and maintain short, focused files to avoid issues like silent rule dropout in long sessions.
Manual AGENTS.md files face a maintenance challenge as codebases evolve, leading to staleness. Solutions like Augment Code's Context Engine and Intent's living specs aim to automate context management, with agents updating the spec as they work, addressing the drift problem.
Dimension | Manual AGENTS.md | Intent's Context Engine |
|---|---|---|
Maintenance | Developer writes and updates manually | Agents update the living spec as they work |
Scope | Single Markdown file at repo root | Real-time semantic index across hundreds of thousands of files |
Staleness risk | Requires manual remediation after refactors | Real-time indexing |
