The AGENTS.md Field Guide, 2026 edition

If you are deciding whether AGENTS.md should become the shared instruction layer for your team, the answer in May 2026 is mostly yes. The harder questions are how much to put in it, how to bridge the remaining tool gaps, and how to stop the file from turning into a slow, noisy instruction dump.

Not every source in this piece carries the same weight, and it is worth keeping that in mind as you read. The most solid claims come from first-party documentation and repository files you can inspect yourself. Some of the headline numbers come from vendor research or widely cited independent posts instead. Those sources are still useful, but it is better to treat them as signals than as settled fact unless someone else has replicated them.

These two references anchor most of the analysis below:

agents.md

AGENTS.md

AGENTS.md is a simple, open format for guiding coding agents. Think of it as a README for agents.

agents.md/

code.claude.com

How Claude remembers your project - Claude Code Docs

Give Claude persistent instructions with CLAUDE.md files, and let Claude accumulate learnings automatically with auto memory.

code.claude.com/docs/en/memory

TL;DR#

Adopt AGENTS.md as your single source of truth, and keep a thin CLAUDE.md that does @AGENTS.md — as of May 2026, AGENTS.md is the de facto open standard. It has been stewarded by the Agentic AI Foundation under the Linux Foundation since December 9, 2025, and tools such as Codex, Cursor, GitHub Copilot's coding agent, Windsurf, Amp, Aider, Gemini CLI, Zed, Jules, Devin, and Junie all read it natively. Claude Code is the main holdout. It still reads CLAUDE.md only, but Anthropic's docs recommend importing @AGENTS.md or using ln -s AGENTS.md CLAUDE.md as the bridge.
Keep it short, command-first, and hierarchical — aim for roughly 150 to 200 lines at the root, use nested AGENTS.md files in monorepo packages, and put exact shell commands ahead of prose. The nearest file to the edited path wins on conflict. Long-form guidance should live behind links so it loads only when relevant.
Treat it like code, not a wiki — commit it, review it in PRs, and prune it on a schedule. A stale or bloated AGENTS.md can actively hurt agent performance. Augment Code's internal evals reported that one bad file could drop task completeness by 30%, while Vercel's 2026 evals reported an always-on AGENTS.md docs index hitting a 100% pass rate versus 53% with no docs and 79% with skill-only approaches. Those numbers are useful, but they come from vendor-run evaluations rather than a public benchmark.

Details#

1. What AGENTS.md is and where it came from#

AGENTS.md is a plain Markdown file at the root of a repository that gives AI coding agents project-specific instructions: build commands, test commands, conventions, gotchas, and PR rules. The format is intentionally schema-free. As the agents.md FAQ puts it: "No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide."

It consolidates a previously fragmented landscape:

CLAUDE.md (Anthropic, 2024) — Claude Code's project memory file
.cursorrules → .cursor/rules/*.mdc (Cursor)
.github/copilot-instructions.md and .github/instructions/**.instructions.md (GitHub Copilot)
.windsurfrules (Windsurf)
AGENT.md (singular) — Sourcegraph Amp's original format
GEMINI.md (Google Gemini CLI)
.aider.conf.yml / CONVENTIONS.md (Aider)

OpenAI shipped AGENTS.md (plural) alongside Codex in August 2025 as a deliberate consolidation effort with Amp, Jules (Google), Cursor, and Factory. Sourcegraph's Amp switched from singular AGENT.md to plural AGENTS.md in the same month. Amp's blog explained the decision this way: "OpenAI picked AGENTS.md (plural) for their agent and, instead of insisting on what we came up with, we decided that we'd prefer one standard. Our condition: if OpenAI can get the agents.md domain, we'll switch."

On December 9, 2025, AGENTS.md, MCP, and goose were jointly donated to the Agentic AI Foundation (AAIF), a new directed fund under the Linux Foundation co-founded by Anthropic, Block, and OpenAI, with Platinum members AWS, Bloomberg, Cloudflare, Google, Microsoft, and OpenAI. The Linux Foundation announcement is the cleanest primary reference. As of that date, AGENTS.md's governance moved out of OpenAI and into a neutral foundation — the same governance pattern as Kubernetes or Node.js.

2. Adoption status as of May 2026#

One useful first-party reference here is GitHub's August 2025 changelog entry on AGENTS.md support:

The GitHub Blog

Copilot coding agent now supports AGENTS.md custom instructions - GitHub Changelog

With custom instructions, you can guide Copilot on how to understand your project as well as how to build, test, and validate its changes. Copilot coding agent, our autonomous background…

github.blog/changelog/2025-08-28-copilot-coding-agent-now...

At a high level, the ecosystem breaks down into a few simple buckets:

Native support in major coding agents: OpenAI Codex, Cursor, GitHub Copilot Coding Agent, Sourcegraph Amp, and Windsurf all read AGENTS.md directly.
Configurable rather than native-by-default: Aider can be pointed at AGENTS.md through .aider.conf.yml, and Gemini CLI can be configured to use AGENTS.md instead of GEMINI.md.
Also listed as supported on agents.md: Zed, Warp, Devin, Jules, Junie, goose, Kilo Code, RooCode, Augment Code, Ona, Phoenix, Semgrep, and Factory.
Main exception: Claude Code still reads CLAUDE.md rather than AGENTS.md directly.

The implementation details that matter most are these:

OpenAI Codex: hierarchical support from ~/.codex/AGENTS.md down to nested project files, plus AGENTS.override.md and configurable fallback filenames in ~/.codex/config.toml.
Cursor: per Cursor's official docs, AGENTS.md is a project-level alternative to .cursor/rules, supports root and nested files, and more specific files take precedence.
GitHub Copilot Coding Agent: GitHub's changelog says the agent supports both root and nested AGENTS.md files alongside .github/copilot-instructions.md, .github/instructions/**.instructions.md, CLAUDE.md, and GEMINI.md.
Sourcegraph Amp: switched from AGENT.md to AGENTS.md in August 2025 and walks parent directories up to $HOME, lazy-loading subtree files.
Windsurf: treats the root file as always-on and turns subdirectory AGENTS.md files into scoped rules using the matching directory pattern.
Claude Code: still requires the CLAUDE.md bridge, either through @AGENTS.md or a symlink.

Anthropic's May 2026 Claude Code docs are equally explicit: "Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them. You can also add Claude-specific instructions below the import. … Running /init in a repo that already has an AGENTS.md reads it and incorporates the relevant parts into the generated CLAUDE.md. It also reads other tool configs like .cursorrules and .windsurfrules."

3. Structural best practices#

Where it lives. Put one AGENTS.md at the repository root, then add one in each meaningful subdirectory of a monorepo, such as apps/web/AGENTS.md, packages/ui/AGENTS.md, or services/payments/AGENTS.md. The filename should be uppercase. Across every supported tool, the nearest AGENTS.md to the file being edited wins on conflict, and explicit user prompts override everything. The agents.md FAQ states it directly: "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything."

How long. Anthropic's official guidance for CLAUDE.md is "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." That is a reasonable target for the root AGENTS.md as well. Real-world reference points:

Next.js (vercel/next.js, canary): 446 lines / ~21KB — large but for an enormous codebase.
OpenAI Codex (openai/codex): 219 lines / 17.3KB at root, plus 87 more nested files.
Temporal Java SDK (temporalio/sdk-java): 59 lines / 2.22KB — the minimal viable end of the spectrum.

Sub-package AGENTS.md files tend to be smaller and more concrete than the root.

Sections that earn their tokens (in roughly decreasing utility):

Project snapshot — one to three sentences: what this is, which package manager, primary stack. Acts as a role-based prompt.
Setup / dev environment commands — exact strings. pnpm install, pnpm dev, port assignments, prerequisite services.
Build, test, lint, type-check commands — the highest-leverage section. The agent will run these without prompting if they're listed. Make them copy-pasteable.
Code style / conventions — only the rules that aren't already enforced by ESLint/Prettier/tsc. If the linter catches it, don't restate it.
Project layout / where things live — directory-purpose lines, not full file trees. File paths drift; capabilities are stable.
PR and commit conventions — title format, conventional-commits enforcement, what not to include (e.g., AI co-author footers).
Safety / boundaries — explicit "never do" rules: never --force-push, never --no-verify, never delete migrations, never touch secrets.
When stuck / escalation rules — what to do after N test failures, when to stop and report rather than improvise.
Domain vocabulary — terms unique to your business ("workspace" vs "org" vs "tenant") that the agent would otherwise guess at.

Sections to omit or move out: lengthy architecture essays, full ADRs, anything that duplicates the linter, anything that duplicates package.json scripts the agent can already see, and anything that only "might be useful someday." If you cannot justify a section by pointing to a mistake the agent made twice, cut it.

4. Content best practices#

These are the patterns that most consistently change agent behavior, based on Matt Nigh's analysis of 2,500+ agents.md files on the GitHub Blog and Blake Crosley's controlled A/B tests:

Imperative, not descriptive. "Run pnpm test before committing." Not "We value testing."
Command-first. Exact shell strings the agent can execute. pnpm turbo run test --filter <project> beats "use the monorepo's test runner."
Closure criteria. "Done means: typecheck passes, pnpm test is green, no new any types." Not "ensure quality."
Banned phrases: "be careful," "where appropriate," "if needed," "generally," "try to." They map to no decision.
Three-tier boundaries: always-do / ask-first / never-do. Especially the never-do list — agents default to creative workarounds when blocked (deleting lockfiles, bypassing checks, force-pushing). Banning destructive recovery patterns prevents the worst failure modes.
When-then escalation rules.:

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check requirements.txt first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests.

Progressive disclosure for long-form material. Don't paste your TypeScript style guide; link to docs/TYPESCRIPT.md. The agent will read it on demand when it's relevant, and the tokens don't load on every request.
Concrete examples > abstract rules. "Use interface for object shapes; reserve type for unions and primitives. Example: interface User { id: string } vs type Status = 'active' | 'inactive'."
Domain stability over path stability. File paths churn; domain concepts don't. Encode "the billing service handles invoice generation" over "billing logic lives in src/billing/handlers.ts."

Photograph of a craftsperson carefully pruning a bonsai tree in a quiet courtyard Figure 1: AGENTS.md works best when teams keep shaping and pruning it instead of letting it grow into an instruction dump.

5. Common pitfalls and anti-patterns#

Augment Code's evals identified four high-frequency failure modes:

Too much architecture overview. The agent gets pulled into reading dozens of doc files trying to "better understand the architecture," loads hundreds of thousands of tokens, and the output gets worse. "An AGENTS.md included a full service topology covering the event bus, message queues, API gateway routing, and shared middleware layers, with reasoning for every architectural decision. The task: a two-line config change." — Augment Code blog
Context rot via linked docs. If your AGENTS.md is good but your module has 500K of specs around it, the specs are what the agent reads. Fix the documentation environment, not just the entry point.
The accumulating "ball of mud." The feedback loop is obvious: the agent does something you do not like, you add a rule, and after enough repetitions the file becomes an unmaintainable mess that hurts performance. The mitigation is a review-and-prune cadence. Delete entries you cannot tie to a recent failure.
Auto-generated AGENTS.md. Init scripts tend to stuff the file with generic "useful for most scenarios" advice. AI Hero's guide is blunt: "Never use initialization scripts to auto-generate your AGENTS.md. They flood the file with things that are 'useful for most scenarios' but would be better progressively disclosed." The result is usually broad and noisy instead of selective. Treat /init as a starter draft, then cut it back hard.

Other recurring failures:

Restating the linter. If eslint enforces it, don't put it in AGENTS.md.
Documenting absolute file paths that get renamed and silently mislead the agent.
Treating it as enforcement. AGENTS.md shapes behavior but does not guarantee it. The rule of thumb from Bijit Ghosh's widely-cited Medium post: "If a violation of the rule would block a merge in CI, the rule belongs in CI. If a violation would make a code reviewer raise an eyebrow, the rule belongs in CLAUDE.md."

6. TypeScript / full-stack specific guidance#

The canonical example on the agents.md homepage is itself a pnpm/Turborepo/Vite/TypeScript file. It reflects the stack most often discussed in 2026 agent-instruction guidance. Specific recommendations:

Package manager. Pin it explicitly. Agents will hallucinate npm if you don't say pnpm (or bun). Add packageManager to package.json (corepack will warn on mismatch), and call it out in AGENTS.md: "Use pnpm, not npm. Run pnpm install --frozen-lockfile in CI."

Monorepo commands. Turborepo's --filter syntax should be in the file: pnpm turbo run test --filter <project>, pnpm turbo run build --filter <project>, pnpm turbo run lint --filter <project>. Nx equivalent: nx run <project>:test.

Nested AGENTS.md layout for a typical TS monorepo:

/AGENTS.md                       # universal: package manager, monorepo conventions, PR rules
/apps/web/AGENTS.md              # Next.js app: routing rules, server-action conventions
/apps/api/AGENTS.md              # Node backend: validation, error format, auth boundaries
/packages/ui/AGENTS.md           # Component patterns, Storybook expectations
/packages/db/AGENTS.md           # Migration rules, never edit historical migrations

Next.js specifically. Vercel's January 27, 2026 blog post "AGENTS.md outperforms Skills in our agent evals" reported that four frontier models on Next.js 16 API tasks hit a 100% pass rate when given an always-on AGENTS.md docs index, compared with 53% no-docs baseline and 79% with skill-only approaches. Vercel later reported compressing the initial ~40KB documentation index to ~8KB while maintaining the 100% pass rate. That is strong evidence for Next.js itself, but it is still a vendor-run Next.js-specific eval rather than a general benchmark for every stack. As of Next.js 16.2, create-next-app ships an AGENTS.md by default with a single directive: "Before any Next.js work, find and read the relevant doc in node_modules/next/dist/docs/. Your training data is outdated — the docs are the source of truth." Vercel publishes the codemod as npx @next/codemod@canary agents-md for retrofitting existing projects.

For readers who want to inspect that Next.js-specific claim directly, this is the post the article is referring to:

Vercel

AGENTS.md outperforms skills in our agent evals

A compressed 8KB docs index in AGENTS.md achieved 100% on Next.js 16 API evals. Skills maxed at 79%. Here's what we learned and how to set it up.

vercel.com/blog/agents-md-outperforms-skills-in-our-agent...

Testing frameworks. Be explicit: pnpm vitest run -t "<test name>", pnpm playwright test --project=chromium. If you run tests in CI mode differently from local (IS_WEBPACK_TEST=1 style env vars), document it. Agents will reproduce the wrong configuration otherwise.

Build tools.

Turborepo: Mention turbo.json task descriptions (Turborepo 2.8 added a description field on tasks specifically for agents), mention worktree-aware caching (also new in 2.8), and pin task names.
Vite: Tell the agent which vite.config.ts is canonical in a monorepo.
tsconfig: If you use TypeScript project references or path aliases, name them. Strict mode policies belong here.

Type rules that matter. "TypeScript strict mode, no any (use unknown + narrowing), prefer interface for object shapes, named exports only." Two lines of this beats two pages of style guide.

Backend gotchas. Database migration policy ("never edit historical migrations"), env-var location, secret-handling rule ("never commit .env; secrets live in .env.local which is gitignored").

7. Claude Code specifics (May 2026)#

Claude Code remains the clearest exception to the AGENTS.md standard. The current state, drawn from Anthropic's official memory docs:

Read order. Claude Code walks up the directory tree concatenating every CLAUDE.md and CLAUDE.local.md it finds, from filesystem root down to working directory. Files closer to the working directory load last (highest priority).
Scopes. Managed policy → user (~/.claude/CLAUDE.md) → project (./CLAUDE.md or ./.claude/CLAUDE.md) → local (./CLAUDE.local.md, gitignored). Subdirectory CLAUDE.md files lazy-load when Claude reads files in them.
Imports. @path/to/file.md syntax. Recursive imports allowed up to 5 hops. Both relative and absolute paths supported. This is the official bridge to AGENTS.md: write @AGENTS.md at the top of CLAUDE.md.
Path-scoped rules. .claude/rules/*.md with YAML frontmatter paths: ["src/api/**/*.ts"] — loads only when working in matching paths. No AGENTS.md equivalent in other tools (Cursor's .cursor/rules/*.mdc is closest).
Auto memory. Since Claude Code v2.1.59, Claude maintains its own MEMORY.md per project at ~/.claude/projects/<project>/memory/. First 200 lines or 25KB loaded each session. Machine-local, not committed, not in your repo. Toggle via /memory or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
Skills, slash commands, MCP, subagents — orthogonal to AGENTS.md/CLAUDE.md. Skills live in .claude/skills/<name>/SKILL.md and only load when invoked or judged relevant; they're the right home for occasional workflows ("upgrade Next.js version," "audit accessibility") rather than always-on rules. MCP server config lives in .mcp.json. Subagents have their own auto-memory.
Compaction behavior. Project-root CLAUDE.md survives /compact (re-injected from disk). Nested subdirectory CLAUDE.md files do not — they reload the next time Claude reads a file in that directory.

Recommended Claude Code setup for a multi-tool team (2026 Q2):

# CLAUDE.md (project root)
@AGENTS.md

## Claude Code specifics
- Use plan mode for changes under `src/billing/`.
- Prefer the `db-migrator` subagent for schema changes.

# Alternative if you don't need Claude-specific additions
ln -s AGENTS.md CLAUDE.md
# Windows: requires Admin / Developer Mode — use @AGENTS.md import instead

/init respects an existing AGENTS.md, so running it in an AGENTS.md-first repo is safe and produces a thin CLAUDE.md that defers to it.

8. Multi-tool environments#

If your team uses Claude Code + Cursor + Copilot, which was the most common mix in 2026, the recommended setup is:

Source of truth: AGENTS.md at the repo root (and in subpackages for monorepos), committed to version control.
Claude Code bridge: CLAUDE.md with @AGENTS.md as the first line. Add Claude-specific overrides below.
Copilot bridge: Copilot's coding agent reads AGENTS.md natively. For VS Code in-editor, also keep .github/copilot-instructions.md if you want path-scoped .instructions.md files — or just let it read AGENTS.md.
Cursor: No bridge needed. AGENTS.md works directly.

9. Version control and team workflow#

Commit it. AGENTS.md belongs in the repo, just like README.md and CONTRIBUTING.md. The whole point is shared context across the team. Personal or machine-local variants such as CLAUDE.local.md should be gitignored.

Review it in PRs. Factory's docs put this well: "Treat AGENTS.md like code — PR reviewers should nudge updates when build steps change." Common triggers for an AGENTS.md update in a PR:

New script in package.json
New service / package in the monorepo
New environment variable or config requirement
A "the agent did the wrong thing twice" pattern that needs documenting
An old convention being deprecated (remove the rule before it confuses future agents)

Cadence. Most teams writing about this recommend a quarterly prune to delete stale rules and consolidate duplicates, plus an on-trigger update whenever an agent makes a mistake worth codifying. Anthropic's Claude Code docs explicitly include a maintenance check in the troubleshooting flow: "File has been reviewed and pruned within the last 90 days — run /memory and remove duplicates."

PR templates. Adding a checkbox like - [ ] Updated AGENTS.md if build/test/deployment commands changed to your PR template costs nothing and catches drift early.

Generation. Avoid letting any tool auto-write your entire AGENTS.md. Use /init in Claude Code or Codex as a skeleton generator only, then aggressively delete. Auto-generated AGENTS.md files are the single most cited anti-pattern.

Caveats#

Claude Code support could land any time. Anthropic has acknowledged the issue exists but has made no commitment. If you adopt the @AGENTS.md import pattern today, you'll have zero migration work when (if) native support lands.
The "60,000+ projects" and "88 AGENTS.md files in OpenAI's repo" figures are self-reported on agents.md and treated as "at time of writing". They are directionally useful, but if the exact number matters, verify them independently.
Vercel's 100% pass rate is on Next.js-specific evals, not a general-purpose benchmark. The pattern (always-on docs index in AGENTS.md > on-demand skills) is intuitive and likely generalizes, but treat the specific number as Next.js-flavored.
Several of the post's strongest quantitative claims come from vendor blogs with skin in the game. That does not make them wrong, but it does mean they should carry less weight than first-party docs or directly inspectable repository evidence.
AGENTS.md is not enforcement. Multiple tools (Claude Code, Cursor, Copilot) document explicitly that the file shapes behavior but does not guarantee compliance. Treat critical rules (security scans, mandatory test coverage, blocked file paths) as CI gates or pre-commit hooks, not as AGENTS.md prose.
The 150–200 instruction budget heuristic comes from one widely-cited blog post, not a study. Treat it as a useful heuristic, not a hard limit.
Cursor's docs do not explicitly slot AGENTS.md into the Team→Project→User precedence ladder — they describe it as "a simple alternative to .cursor/rules", which positions it at the Project tier by inference rather than by direct documentation.