On this page
AGENTS.md Best Practices
Most root-level AGENTS.md files deliver negligible or negative returns for AI coding tools, per 2026 ETH Zurich research. Curated minimal files with only non-inferable rules cut task time by 28% and reduce agent-generated bugs by 35-55%. Avoid bloat, redundant overviews, and stale content to boost performance and lower inference costs.
AGENTS.md Best Practices: Why Most Files Hurt Performance
GitHub code searching shows approximately 96,600 root-level AGENTS.md files as of June 2026, yet the majority deliver negligible or negative returns. The format has achieved remarkable adoption—read natively by 28–30+ AI coding tools and used by over 60,000 open-source projects—but a 2026 ETH Zurich study of 138 repositories found that README-style or LLM-generated AGENTS.md files reduced task success rates by 0.5–2% and increased inference costs by 20–23% in five of eight tested configurations. The problem isn’t the standard; it’s how most teams write it.
The Core Tension: Universal Simplicity vs. Effective Constraints
AGENTS.md’s greatest strength is also its biggest trap. The spec consists of plain Markdown with no required fields, no YAML frontmatter, and no special syntax—intentionally so. This zero-friction design, stewarded by the Agentic AI Foundation under the Linux Foundation, enabled explosive adoption across Claude Code, OpenAI Codex, GitHub Copilot, Cursor, and dozens more. But that same flexibility means there’s no guardrail against bloat.
The spec encodes seven explicit design decisions: plain markdown only, a single root-level file, no required fields, the literal filename AGENTS.md, nested subdirectory files that override by concatenation, a 32 KiB default cap, and no @-import syntax. Each choice trades capability for portability. The concatenation rule, for instance, means nested files grow prompt size linearly with directory depth—simple to understand, costly to ignore.
What I call the Context-Value Decoupling pattern is at work here. Teams assume more context equals better agent performance, but the ETH Zurich research shows the opposite: when researchers removed all documentation from repos, LLM-generated context files suddenly helped (+2.7%). The files were duplicating information agents already extracted from READMEs and code on their own. Curated minimal files with only three content categories—coding conventions, architecture, and project description—reduced median wall-clock time by 28% and output tokens by 16%.
What Actually Goes In: The Non-Inferable Rule
Effective AGENTS.md files prioritize copy-pasteable commands, real code snippets, and explicit boundaries over vague prose or redundant project overviews that agents can infer from the codebase. This isn’t my opinion—it’s what the data shows about which files actually move performance metrics.
The perception-practice gap is stark: developers rank Architecture & Design rules as most important, but actual AGENTS.md files are dominated by Code Style & Formatting rules. Meanwhile, the most prevalent form of agent misalignment is Developer Constraint Violation at 38.33% of all misalignment episodes—precisely the architectural boundaries that files underweight.
Here’s what belongs in your file:
- Exact build/test commands with flags:
pnpm test -- --runnot “run the test suite” - Forbidden directories and files: NEVER modify
/legacy/,rant` without approval - Critical architectural boundaries: which service owns which data, API versioning rules
- Tool-specific gotchas: the linter config that differs from defaults, the mock setup pattern
Here’s what doesn’t: project overviews, generic coding principles, restatements of README content, or anything an agent could deduce from package.json or existing code. Projects with detailed AGENTS.md files average 35–55% fewer agent-generated bugs—but “detailed” here means precise, not lengthy. Developer-written files achieve roughly a 4% improvement in task success rate, while LLM-generated files perform worse than no file in most tested settings.
The Cross-Tool Compatibility Trap
AGENTS.md is positioned as a universal replacement for fragmented tool-specific instruction files, but advanced use cases still require parallel maintenance of proprietary configs. This isn’t a failing—it’s a tradeoff to understand.
| Aspect | AGENTS.md | Tool-Specific Files (CLAUDE.md, .cursorrules) |
|---|---|---|
| Portability | One file works across 28–30+ tools | Locked to single vendor |
| Native features | Basic instruction parsing only | Subagent definition, skill integration, glob scoping |
| Maintenance burden | Single source of truth | Multiple files to sync |
| Optimization depth | Generic, lowest-common-denominator | Tool-native performance tuning |
CLAUDE.md remains a richer native format for Claude Code than AGENTS.md, supporting features like subagent definition and skill integration. Many power users maintain both files—AGENTS.md for cross-tool baseline behavior, CLAUDE.md for Claude-specific capabilities. The practical setup: put shared instructions in AGENTS.md for cross-tool compatibility, and use tool-specific files for advanced use cases.
For teams evaluating this split, our guide to writing AGENTS.md for Cursor, Copilot & Codex breaks down the layered configuration model that respects LLM instruction budgets while maintaining consistent behavior.
The Stale File Problem
The MSR ‘26 survey of 10,000 repositories found that half of all AGENTS.md files have zero commits after creation. This matters because the most common misalignment type—Developer Constraint Violation at 38.33% of episodes—grows over time as stale files fail to reflect new architectural boundaries.
AGENTS.md is designed as a stable, low-maintenance persistent contract, but its effectiveness degrades without active curation. The spec itself changes slowly by design—the last major update was March 2026—but your codebase doesn’t. A file that correctly prohibited modifying /legacy/ six months ago may now need to add the new /experimental/ directory, or update the build command after your migration from Jest to Vitest.
The maintenance pattern that works: treat AGENTS.md like your CI configuration. Review it in code review when architectural boundaries change. Add a checklist item to your sprint retrospective. The best AGENTS.md templates include versioning hooks—comments indicating when a rule was added and why, making stale entries easier to identify.
Emerging Standards: What v1.1 and Lifecycle Commands Mean for You
Two proposals are moving through the spec process that could change how teams structure their files.
A proposal for AGENTS.md v1.1 was open as of June 2026, aiming to codify hierarchical scope, precedence, and progressive disclosure, and to position AGENTS.md as complementary to SKILL.md. This would make implicit behaviors explicit—how nested files interact, which rules take precedence when conflicts arise—reducing the guesswork that currently leads to over-specification.
A proposal for Lifecycle Commands (Issue #167) was completed on April 28, 2026, introducing YAML front matter with bootstrap and post-chat lifecycle commands and builtin commands (read, read-as-system, run). This is a significant departure from the spec’s plain-markdown-only principle, enabling pre-session setup like loading shared skill files or running lint fixes after each chat cycle.
Both proposals reflect growing enterprise demand for more structured agent governance. The Agentic AI Foundation had 190 member organizations as of May 2026, including Stripe, GoDaddy, Atlassian, U.S. national labs, and the U.S. Army. That institutional weight means the spec will evolve, but the core tension remains: every added capability risks the bloat that harms performance.
A Practical Decision Framework
For most teams, the optimal AGENTS.md is a 1–2KB file containing only non-inferable rules rather than a full project overview. Any content agents can extract from the codebase, README, or existing docs actively harms performance and increases costs.
Ask these questions before adding any line:
- Can the agent discover this from existing files? If yes, delete it.
- Is this a command the agent can copy-paste? If no, make it one or remove it.
- Does this boundary change how the agent would otherwise act? If no, it’s prose, not a rule.
- When did I last verify this still applies? If you can’t remember, audit it now.
The teams getting the 35–55% bug reduction aren’t writing more—they’re writing less, more precisely. Our guide to building and testing AGENTS.md in production covers real-world adoption patterns, cost tradeoffs, and a minimal template to get started without the bloat traps.
The open question for 2026: as the spec gains YAML front matter and lifecycle commands, will the simplicity that drove adoption survive? Or will AGENTS.md fragment into the same tool-specific complexity it was designed to replace?