AGENTS.md Examples for Real Projects: What Actually Works

Cloudflare deployed AGENTS.md across roughly 3,900 internal repositories and now has 3,683 engineers using AI coding tools in a 30-day window. That’s not a pilot program—it’s autonomous worker agents that make any pipeline step a markdown-defined AI agent, a production reality that started with a single Markdown file at the repository root. If you’re still treating AGENTS.md as a nice-to-have, you’re already behind the teams that have made it their cheapest reliability upgrade.

What AGENTS.md Actually Is (And What It Costs You)

AGENTS.md is a plain Markdown file placed at the repository root that provides AI coding agents with project-specific operational guidance—build commands, testing instructions, coding conventions, and constraints that agents cannot infer from the codebase alone. It was introduced by OpenAI in August 2025 and donated to the Linux Foundation’s Agentic AI Foundation in December 2025, where it is now stewarded as an open standard.

The published AGENTS.md specification includes seven explicit design decisions: plain markdown only with no YAML or schema, a single root-level file, no required fields or sections, the literal filename AGENTS.md, nested subdirectory files override by concatenation, a 32 KiB default cap on file body, and no @-import or include syntax. These choices matter because they define what you’re signing up for. The plain markdown decision means zero migration friction but no machine-readable validation. The concatenation override rule means prompt size grows linearly with directory depth—an automatic tax on deep monorepos that most teams don’t model until they see the token bill.

Here’s the cost reality that research has surfaced. ETH Zurich 2026 research on AGENTS.md file performance found that human-curated AGENTS.md files deliver a marginal 4% improvement in task success rate on average, while LLM-generated context files reduce task success rates by an average of 3% and increase inference costs by over 20%. Projects with detailed AGENTS.md files average 35-55% fewer agent-generated bugs, while LLM-generated files reduce task success in 5 out of 8 tested settings and add 2.45-3.92 extra steps per task.

The pattern I’ve observed—what I call the Context Dominance Model—is that the dominant cost and reliability bottleneck for production AI agents in 2026 isn’t model inference. It’s engineering overhead for integration, evaluation, and context management. AGENTS.md is both the primary mitigation for this overhead and, if done wrong, a new source of quantifiable hidden cost.

What to Put in Your AGENTS.md (And What to Leave Out)

The standard recommends focusing content on non-inferable project specifics—custom commands, exact stack versions, unique architectural patterns—and avoiding redundant codebase overviews to minimize token overhead. This sounds obvious until you watch a team paste their entire architecture diagram into a file that the agent loads on every turn.

For large projects, AGENTS.md files should be modularized when exceeding 150-200 lines to optimize token budgets. The concatenation override rule means that a 180-line root file plus a 120-line subdirectory file plus a 90-line package-level file becomes a 390-line prompt payload. At that point, you’re paying a premium for context the agent doesn’t need.

The highest-value lines in any AGENTS.md are what an agent can’t infer: exact commands, multi-tenant data-access rules, and a clear list of what to never touch. If your agent can discover it by reading three files, don’t put it in AGENTS.md. If your agent will guess wrong and cost you a debugging session, that’s your signal.

Real-World Adoption Patterns

AGENTS.md has been adopted by more than 60,000 open-source repositories and is supported by major AI coding tools including Cursor, GitHub Copilot, Claude Code, Codex, Devin, Windsurf, and Gemini CLI. The cross-tool portability is the point—one file that any compliant tool can read, replacing the patchwork of .cursorrules, CLAUDE.md, and copilot-instructions.md that fragment across teams using multiple agents.

Cloudflare’s deployment at 3,900 repositories with 60% company-wide adoption shows what’s possible at scale. Next.js 16.2 generates an AGENTS.md file in create-next-app by default as of March 2026, which means the convention is now framework-default for one of the most widely used web stacks.

The tooling ecosystem is converging around this standard. Harness uses the AGENTS.md agent-file format as the standard for defining Autonomous Worker Agents in software delivery pipelines, executing them in sandboxed containers with scoped credentials and audit trails. Google’s Managed Agents API, launched at I/O 2026, supports AGENTS.md and SKILL.md extensibility for defining custom agent behavior in isolated Linux sandboxes.

A GitHub Proposal and the Future of the Format

A GitHub proposal to add YAML front matter with lifecycle commands (bootstrap, post-chat) and builtin commands (read, read-as-system, run) to AGENTS.md was completed and closed in April 2026. This matters because it shows where the standard is heading: more structured, more powerful, and potentially more complex to maintain.

The lifecycle commands address a real limitation. The bootstrap command runs once when the session starts, before the first API call, enabling pre-loading of shared context. The post-chat command fires after the client completes a full task cycle, enabling automated cleanup like linting or formatting. The read and read-as-system commands allow modular composition—reusable rulesets that can be shared across projects without copy-paste.

But here’s the tradeoff: every structured extension adds surface area for inconsistency. A team that adopts YAML front matter for one project and plain markdown for another has created a maintenance burden. The spec’s original plain-markdown-only decision was deliberate precisely to avoid this fragmentation.

Cost Analysis: When AGENTS.md Pays Off (And When It Doesn’t)

The research on AGENTS.md performance is more nuanced than the headline numbers suggest. Human-curated files deliver a 4% success rate improvement but still raise costs by up to 19% due to additional steps. LLM-generated files are worse than no file at all in most settings. The real win comes from the 35-55% reduction in agent-generated bugs—which translates directly to engineering time saved on debugging and rework.

For a deeper look at how context file choices compound across your AI coding stack, see our analysis of Claude Code Skills, Cursor Rules, and AGENTS.md as a layered configuration model. The short version: AGENTS.md as your cross-tool source of truth, with tool-specific adapters for behavior that varies by agent, minimizes duplication and keeps token costs bounded.

The cost math changes based on your agent’s task volume. If your team runs 500 agent sessions per week and each AGENTS.md load adds tokens at standard inference rates, you’re looking at a modest weekly increment. Against a 35-55% bug reduction, the payback is immediate. But if your AGENTS.md is bloated with inferable content, you’re paying that tax for no benefit—and an LLM-generated file makes it worse.

Comparison: AGENTS.md Across the Ecosystem

Tool/Platform	AGENTS.md Support	Key Differentiator	Best For
Cursor	Full native support	.cursorrules fallback, .mdc per-feature granularity	Teams wanting fine-grained rule scoping
GitHub Copilot	Full native support	Deep IDE integration, enterprise policy controls	Organizations with existing Microsoft stack
Claude Code	Full native support	Subagent definitions in AGENTS.md, SKILL.md extensibility	Complex multi-agent workflows
Codex	Originated the standard	Concatenation override, 32 KiB cap enforcement	Teams prioritizing spec compliance
Harness	Agent-file format standard	Sandboxed container execution, audit trails	CI/CD pipeline automation
Google Managed Agents	AGENTS.md + SKILL.md extensibility	Isolated Linux sandbox per agent invocation	Cloud-native enterprise deployments

Writing Your First AGENTS.md: A Minimal Template

Start with what breaks. Not what might break—what actually broke last week because an agent guessed wrong.

# Build & Test

- Use `pnpm install` and `pnpm build` (not npm)
- Run `pnpm test:unit` for unit tests, `pnpm test:e2e` for integration
- E2E tests require `docker compose up db` first

# Conventions

- API routes live in `packages/api/src/routes/`
- Database models live in `packages/api/src/models/`
- Tests adjacent to source as `*.test.ts`
- No `any` types except in test files

# Boundaries

- Never modify files in `vendor/` or `generated/`
- Never commit migration files without running `pnpm migrate:verify`
- All database changes require review from @data-platform team

That’s it. No architecture overview. No “our company values.” No copy-paste from the README. Every line answers a question the agent has gotten wrong before.

For teams ready to go deeper, our guide on how to write an AGENTS.md file for Cursor, Copilot, and Codex walks through the layered configuration model that respects LLM instruction budgets and tool-specific adapter patterns.

The Verdict: Start Minimal, Stay Curated

AGENTS.md is a net positive when it’s human-curated, constraint-focused, and ruthlessly pruned of inferable content. It’s a net negative when it’s auto-generated, bloated, or treated as documentation rather than a runtime instruction set.

AGENTS.md done right attacks that overhead directly. Done wrong, it adds to it.

For most teams in 2026, the specific recommendation is this: write your AGENTS.md by hand, keep it under 150 lines, review it monthly for stale constraints, and measure agent-generated bug rates before and after. If your bug rate isn’t dropping, your file is probably too long, too generic, or both. What’s your current ratio of agent-generated bugs to total bugs—and how much of that is traceable to context the agent loaded at session start?