AGENTS.md Explained: The Open Standard for AI Coding Agents

Over 60,000 open-source projects now ship with an AGENTS.md file, and 28+ AI coding tools read it natively. Yet the format’s most important lesson isn’t about adoption — it’s about restraint. The data shows that writing less in your AGENTS.md makes your agent perform better, cost less, and fail less often. This is the paradox at the heart of the standard: a file designed to give agents more context works best when you give them less.

What AGENTS.md Actually Is

AGENTS.md is a Markdown file placed at a repository’s root (or in subdirectories for monorepos) that provides AI coding agents with project-specific instructions: setup commands, coding conventions, testing protocols, and hard boundaries. Think of it as onboarding documentation where the new hire is an LLM, not a person. The file emerged from OpenAI in August 2025, was donated to the Linux Foundation’s Agentic AI Foundation by December 2025, and has since become the closest thing the ecosystem has to a universal configuration format.

The standard’s power lies in its boringness. It’s just Markdown — no schema, no special syntax, no vendor lock-in. A minimal file might look like this:

# Project: My SaaS App

## Stack
- Next.js 15 (App Router), TypeScript strict, Tailwind CSS
- Database: Postgres via Prisma

## Conventions
- Use named exports, not default exports
- Never modify files in /legacy/

## Before committing
- Run `npm run lint && npm run test`

That’s it. No origin stories, no architecture diagrams, no “why we chose React in 2023” narratives. Agents don’t need your journey. They need your constraints.

The Linux Foundation’s Agentic AI Foundation now stewards AGENTS.md alongside MCP and goose, with 170+ member organizations as of April 2026. Google’s Managed Agents API supports it. OpenAI’s Agents SDK includes standardized integrations for it. Next.js 16.2 generates one by default in create-next-app. The standardization race is effectively over — which makes the performance data even more important to understand.

The Context Pollution Paradox

Here’s the pattern I’ve observed: teams assume more context means better agent performance, but the evidence points the other way. An ETH Zurich study found that AGENTS.md files’ impact on agent success rates varied by file origin: auto-generated files lowered success rates by approximately 3% compared to no context at all, while human-written files added only about 4% improvement. Worse, overly detailed files increased inference costs by more than 20% — roughly 300 extra tokens per request.

This isn’t intuitive. We’re conditioned to believe documentation helps. But LLMs aren’t reading your AGENTS.md for comprehension; they’re incorporating it into a prompt window where every token competes for attention. Redundant instructions don’t clarify — they obscure. The study noted that agents excel at discovering directory structures on their own, so static file trees (a common template inclusion) actually slow down the search for relevant source files.

The contrarian take here is that AGENTS.md’s value isn’t in making agents smarter. It’s in making them consistent across tools. The format is infrastructure, not intelligence. When you treat it as a knowledge base, you degrade performance and inflate costs. When you treat it as a compatibility layer — minimal, surgical, constraint-focused — you get the cross-tool portability without the penalty.

Tool Support and the Claude Code Exception

Most major tools now read AGENTS.md natively. GitHub Copilot auto-discovers it from workspace root and subdirectories, and also supports .agent.md files with YAML frontmatter. Google’s Managed Agents API supports AGENTS.md and SKILL.md for file-based agent definitions. OpenAI’s Agents SDK includes standardized integrations with AGENTS.md for custom instructions.

The glaring exception is Claude Code. As of April 2026, Claude Code lacked native AGENTS.md support — a gap that prompted third-party tools like cc-agents-md to inject AGENTS.md via hooks. This has been the most requested feature with 3,600+ upvotes and no official response. As of June 2026, Claude Code natively reads AGENTS.md, though CLAUDE.md remains its richer native format.

This creates a practical tension for multi-tool teams. If you’re running Cursor for frontend, Claude Code for complex refactors, and Copilot for autocomplete, you face a choice: maintain AGENTS.md as your cross-tool source of truth with tool-specific files for richer features, or standardize on one vendor’s format and accept the lock-in. The layered approach — AGENTS.md for universal basics, CLAUDE.md or .cursor/rules/ for tool-specific depth — is what most teams I talk to are landing on.

Tool	AGENTS.md Support	Native Format	Pricing (July 2026)
GitHub Copilot	Auto-discovers root + subdirectories; .agent.md YAML frontmatter	.agent.md	$39–$100/seat/month per Developers Digest
Claude Code	Native since June 2026	CLAUDE.md	—
Cursor	Native	.cursor/rules/	$120/seat/month per Developers Digest
OpenAI Codex	Native	—	—

What the Performance Data Actually Shows

Let’s look at the numbers that matter. GitHub analyzed over 2,500 repositories and found a clear progression: 40-60% task success without AGENTS.md, 60-70% with minimal AGENTS.md, and 85-90% with comprehensive AGENTS.md. At first glance, this seems to contradict the ETH Zurich findings. It doesn’t — it clarifies them.

The GitHub data measures presence versus absence of guidance. The ETH Zurich data measures quality and volume of that guidance. A minimal, well-crafted AGENTS.md lands you in that 60-70% range. Pushing to 85-90% requires comprehensive documentation — but the ETH cost data suggests that “comprehensive” in practice often means bloated, and the 85-90% figure may reflect idealized enterprise files rather than typical ones. The 4% human-written improvement in the ETH study is more realistic for most teams.

The real kicker is on the cost side. AI coding tool costs for small teams of 5-10 people range from $200 to $500 per month, with enterprise seats running $39 to $100 per seat depending on model access. Cursor Teams Premium hits $120/seat/month. GitHub Copilot Enterprise has an effective price of $60/user/month when you factor in the required GitHub Enterprise Cloud subscription. These aren’t token costs — they’re seat costs. Add 20% token overhead from bloated AGENTS.md files, and you’re paying premium prices for degraded performance.

How to Write AGENTS.md That Doesn’t Hurt You

Given the data, here’s a framework that actually works:

Include only what an agent can’t infer:

• Exact stack versions (not “React” but “React 18.3, TypeScript 5.4”)
• Non-obvious commands (custom build tools, non-default package managers)
• Hard boundaries (never touch /legacy/, always run tests before commit)
• Security-critical constraints (data access rules, auth patterns)

Omit what it can:

• Directory structures (it’ll find files faster itself)
• Library documentation (it already “knows” common APIs)
• Architecture justifications (irrelevant to task execution)
• Generated overviews (prone to hallucination and drift)

Structure for token efficiency:

• Lead with stack and constraints
• Use bullet points over paragraphs
• Version-pin everything
• Update only when behavior changes, not when you learn new things

The AGENTS.md framework raised a $12 million Series A led by Andreessen Horowitz in May 2026, bringing total capital to $15.2 million. That investment is going into enterprise security, role-based access control, and a compliance-focused SDK. The format isn’t going away. Your job is to use it without letting it become another source of technical debt.

The Evolving Standard: What’s Coming

AGENTS.md is actively developing beyond static Markdown. A GitHub proposal for lifecycle commands — bootstrap, post-chat, read, run — was completed in April 2026, enabling files that trigger actions at session start or after chat completion. Another [proposal governors for a standardized rule format](https://github.com/agentsmd/agents.mdDraft proposal for a standardized rule format for .agents/rules/ is open as of May 2026, addressing the fragmentation where every tool uses slightly different path-scoping syntax.

These extensions matter for teams at scale. The lifecycle commands let you enforce “run lint before any commit” as a machine-enforced rule, not a polite suggestion. The standardized rule format would let you write path-scoped conventions once and have them apply across Claude Code, Cursor, and Copilot without duplication.

But each extension also risks the same bloat problem. A file that runs commands, reads external documents, and scopes rules by path is powerful — and power consumes tokens. The teams that win will be the ones that adopt new capabilities selectively, measuring token costs and success rates as they expand.

The Honest ROI Picture

Vendors claim 3x productivity. The actual data: DX research across 400+ organizations found a median PR throughput gain of 7.76%, with most teams landing in the 5-15% range. That’s real value, but it’s not transformational. It’s incremental improvement at significant cost.

The honest assessment is that AGENTS.md sits in this gap. It won’t make your agent 3x more productive. For teams running multiple AI tools — which is most teams now — that’s enough to justify the file. For single-tool shops, the benefit is thinner unless you’re rotating tools frequently.

Decision Framework: Should Your Team Adopt AGENTS.md?

Adopt immediately if:

• You use 2+ AI coding tools (the cross-tool standardization value is highest)
• You have onboarding friction (new developers, rotating contractors)
• You’re in a regulated industry where consistent process matters

Adopt carefully if:

• You’re all-in on one tool (benefit is thinner, consider native format instead)
• Your codebase changes rapidly (file drifts, maintenance burden)
• You lack metrics to measure agent performance (can’t optimize what you don’t measure)

Skip or defer if:

• You’re a solo developer with one tool (overhead exceeds benefit)
• Your team can’t agree on conventions (empty or contradictory AGENTS.md is worse than none)
• You’re not tracking token costs (can’t detect bloat)

The Bottom Line

AGENTS.md has won the format war. It’s in 60,000+ repos, supported by 28+ tools, governed by the Linux Foundation, and now generated by default in major frameworks. But winning the format war doesn’t mean every implementation is good. The data is clear: minimal, human-written, constraint-focused files outperform comprehensive or auto-generated ones. The standard’s value is compatibility and consistency, not comprehensiveness.

For teams deciding how to invest, the calculation is straightforward. AGENTS.md costs almost nothing to create and maintain when done right. Done wrong, it costs you 20% more in tokens and 3% worse success rates. The difference between those outcomes isn’t the tool — it’s the discipline of the team using it.

If you’re looking to optimize further, our post on how to write an AGENTS.md file for Cursor, Copilot & Codex breaks down the layered configuration model that respects LLM instruction budgets. For teams concerned about the security implications of agent instruction files, we’ve also covered hardening AGENTS.md against poisoning attacks — a critical, widely overlooked attack surface. And if you’re comparing how AGENTS.md fits alongside tool-specific alternatives, our analysis of Claude Code Skills, Cursor Rules, and AGENTS.md explains why a layered architecture with AGENTS.md as the cross-tool source of truth minimizes duplication and cuts token costs.

The open question: as AGENTS.md gains lifecycle commands and rule standardization, will teams maintain the discipline to keep files minimal — or will feature creep recreate the bloat problem at a new level of complexity? The tools are giving us more rope. Whether we hang ourselves with it depends on whether we believe the data or our intuition about “more-fluid context.”