AGENTS.md in 2026: Tool Support and CLAUDE.md Precedence

Coding agents are now the default interface for a large share of professional software work, and individually they are terrible at remembering project conventions across sessions. AGENTS.md is the convention the industry settled on to fix that: one Markdown file in the repository that any agent can read on task start, carrying the build commands, test commands, code-style rules and "do not touch" boundaries you would otherwise re-type into every prompt.

The single biggest change since this guide was last updated is that Claude Code now reads AGENTS.md directly. For a year that was the one conspicuous hole in the format's coverage, and the workaround — a CLAUDE.md that @-imports AGENTS.md — was the standard advice, including here. It is no longer necessary in most repositories. This guide has been corrected throughout, and the support matrix below is dated and versioned so you can tell how stale it is when you read it.

Last updated: 5 October 2026. Every version number and behaviour below was checked against vendor documentation on that date.

What is AGENTS.md?

AGENTS.md is a conventionally-named Markdown file placed in a code repository. It holds operational context for AI coding agents: the build pipeline, the test command, the directory layout, the code-style conventions, the rules that would get a new hire pulled into a code review. Agents that support the format read it on task start and treat the contents as high-priority guidance.

The official spec page describes it as "a simple, open format for guiding coding agents," and the usual analogy holds: AGENTS.md is to agents what README.md is to humans. A README answers "what is this project and how do I clone it." An AGENTS.md answers "you are about to modify code in this repo — here is what the README would never bother to spell out."

The format is deliberately minimal. It is plain Markdown with no required headings, no mandatory frontmatter, no custom syntax, no build step and no vendor SDK. As agents.md puts it today: "AGENTS.md is just standard Markdown. Use any headings you like." That minimalism is the whole reason it works as a cross-vendor standard — no vendor has an incentive to fork it.

Governance sits with the Agentic AI Foundation under the Linux Foundation, after an origin as a collaboration between OpenAI, Amp (Sourcegraph), Google's Jules team, Cursor and Factory. agents.md reports adoption at more than 60,000 open-source projects as of October 2026.

Which tools read AGENTS.md, and as of what version?

This is the part of any AGENTS.md article that rots fastest, so treat the date as part of the data. Everything below was verified against vendor documentation on 5 October 2026.

The practical takeaway has not changed, only strengthened: if you commit one agent context file, commit AGENTS.md. It now has the broadest reach of any instruction-file convention, with no significant holdout left among mainstream coding agents.

Still choosing an agent? Our AI coding agents complete guide compares Cursor, Claude Code, Codex, Aider and the rest on pricing, autonomy and terminal-vs-IDE fit.

Does Claude Code read AGENTS.md?

Yes, since v2.1.277, published 18 September 2026. The changelog entry is one line: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config."

It was a long time coming. The feature request, anthropics/claude-code#6235, was opened on 21 August 2025 and accumulated 5,186 👍 reactions (6,685 total) and 409 comments before being closed on 17 August 2026 — one of the most-upvoted issues in the repository's history. The Hacker News thread on the day it shipped reached 741 points and 285 comments.

Here is the default behaviour, straight from Claude Code's memory documentation:

Three files "count" as a CLAUDE.md for that check and therefore suppress AGENTS.md: ./CLAUDE.md, ./.claude/CLAUDE.md and ./CLAUDE.local.md, in the working directory or any directory above it. Three things explicitly do not count and keep loading alongside AGENTS.md: your personal ~/.claude/CLAUDE.md, your organisation's managed CLAUDE.md, and .claude/rules/ files.

That CLAUDE.local.md rule bites people. If you keep a gitignored CLAUDE.local.md for your own scratch notes in a repo that otherwise relies on AGENTS.md, you have silently turned AGENTS.md off for yourself and nobody else. The fix is the setting in the next section, not deleting your notes.

Two more details worth knowing. When it works, an interactive session prints a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md, so you can confirm it rather than guess. And Claude Code deliberately ignores AGENTS.local.md, AGENTS.override.md and anything under a .agents/ directory — the Codex override convention does not carry over.

The telemetry-gating episode

The rollout had a genuinely instructive bug. In the first release, AGENTS.md support did not work in every session — among others, sessions on Amazon Bedrock and sessions with telemetry disabled still read CLAUDE.md only. Because the feature ships as a built-in plugin that depends on Claude Code's analytics pipeline, turning telemetry off also turned the feature off.

Developers noticed, and a post titled "Claude Code reads AGENTS.md only when telemetry is on" hit 486 points and 284 comments on Hacker News on 23 September 2026. That was the same day the fix shipped: v2.1.281, with the changelog entry "Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled."

Five days, start to finish, which is fast. The practical lesson for anyone standardising a team: pin a minimum version. On anything before v2.1.277 there is no AGENTS.md support at all, and between v2.1.277 and v2.1.281 it is conditional on your provider and telemetry settings. The documentation also notes that the first session immediately after upgrading from v2.1.276 or earlier can still miss it; it works from the next session on. If you are on an older build or you have disabled the built-in agents-md plugin, the old @AGENTS.md import workaround is still the reliable path.

What takes precedence if both AGENTS.md and CLAUDE.md exist?

In Claude Code, CLAUDE.md wins by default and AGENTS.md is ignored entirely. That is a choice, not a law, and it is the single setting most teams will want to change.

Run /config and set Project instructions to one of four values:

You can set it in a settings file instead of the UI. Note the key: it lives under the built-in plugin's ID, because AGENTS.md support is implemented as a plugin.

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

One constraint that catches teams out: Claude Code ignores this key in project and local settings files. It is honoured in ~/.claude/settings.json, a --settings file, or managed settings only. You cannot commit claude-md-and-agents-md to a repo and have it apply to everyone who clones it — it has to come from each developer's user settings or from your MDM-deployed managed settings.

Three behaviours also differ for an AGENTS.md loaded through the setting rather than through an import: InstructionsLoaded hooks do not fire for it; AGENTS.md in directories added with --add-dir does not load even when the matching CLAUDE.md would; and an @path import pointing outside the working directory loads without a prompt if you have already approved external imports for that project. If you depend on InstructionsLoaded hooks, keep the @AGENTS.md import — hooks fire normally for an imported file.

Elsewhere in the field, precedence is simpler. Codex concatenates root-down so the deepest file effectively wins, with AGENTS.override.md as a hard replace at any level. Cursor combines nested files with parents and lets the more specific one win, inside an overall Team → Project → User order. Copilot takes the nearest AGENTS.md in the tree but ranks all of them below .github/copilot-instructions.md and path-specific .instructions.md files.

We go through the per-tool decision in more depth in AGENTS.md vs CLAUDE.md vs Cursor rules.

Do I need both AGENTS.md and CLAUDE.md?

Usually no, and the answer got simpler in September 2026. Pick by situation:

• Multi-tool team, no Claude-specific workflow. Ship AGENTS.md alone. Every mainstream agent now reads it, Claude Code included. Do not create a CLAUDE.md just to have one — an empty-ish CLAUDE.md actively suppresses your AGENTS.md.
• You have real Claude-Code-only content (subagent routing, slash commands, hook configuration). Keep a CLAUDE.md whose first line is @AGENTS.md, then put the Claude-specific material below it. Claude Code reads the imported file first, then the rest.
• Mixed fleet on older builds, or Bedrock/Vertex/gateway sessions on pre-v2.1.281. Keep the import. It is the only form that works everywhere.
• You want both files read, as written, with no import. Set Project instructions to claude-md-and-agents-md in user or managed settings.

If you set up a workaround before September 2026, here is what to do with it. A CLAUDE.md containing @AGENTS.md can stay — the import never causes a double read under any setting value. A CLAUDE.md symlinked to AGENTS.md is also fine, with one caveat: Claude Code's Edit and Write tools refuse to write through a symlink and will redirect to the target. The two you should actively remove are a CLAUDE.md that merely tells Claude in prose to go read AGENTS.md (it only happens if Claude decides to open the file — replace the sentence with a real @AGENTS.md import), and any SessionStart hook that prints AGENTS.md into context, which now adds a redundant second copy.

How do you keep them from diverging?

The failure mode with two instruction files is not conflict, it is quiet drift: CLAUDE.md says pnpm test, AGENTS.md still says npm test, and whichever agent a developer happens to use behaves differently. Three mechanical defences:

• One file is canonical, the others point at it. Either a symlink or a one-line @AGENTS.md import. Never two hand-maintained copies of the same rule.
• Tool-specific files contain only tool-specific content. If a line would be true for any agent, it belongs in AGENTS.md. The test: would you tell this to every new engineer regardless of their editor?
• Audit on a schedule. Claude Code v2.1.283+ ships /doctor prompt-audit, which checks your CLAUDE.md, CLAUDE.local.md and AGENTS.md files plus everything under .claude/ for contradictions, dead file references and instructions written for older models. It proposes edits and changes nothing until you ask.

Do AGENTS.md files actually improve results?

This is the uncomfortable question, and the honest answer is: less than the vendors recommending them imply.

The most rigorous study so far is "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" (Gloaguen, Mündler-Sasahara, Müller, Raychev and Vechev, submitted 12 February 2026). It evaluated established benchmarks and real developer-committed context files across multiple LLMs and coding agents, and the headline finding is blunt: providing context files "does not generally improve task success rates, while increasing inference cost by over 20% on average."

The useful detail is in the breakdown. The authors found that "instructions in the context files are well followed by coding agents," but that "repository overviews, although popular and recommended by model providers, are not helpful."

That maps cleanly onto how to write the file. The agent will obey "run pytest -x --tb=short tests/unit" and "never edit gen/". It gains nothing from three paragraphs describing your service topology, which it can derive from the code and which costs you tokens on every single task. Claude Code's own documentation makes the same point from the other direction: it tells you to skip anything Claude can derive from the codebase, and to target under 200 lines because "longer files consume more context and reduce adherence."

So the defensible position in late 2026 is: write a short, imperative, command-and-boundary-heavy AGENTS.md, and skip the architecture essay. The parts of the convention with measured benefit are exactly the parts that are cheap to write. The parts that bloat the file are the parts the research says do not pay.

Where do I put AGENTS.md, and how do nested files resolve?

The repository root is the answer for a single-package project, and every tool in the matrix above looks there. In a monorepo, nest them: one at the root, one per package.

repo/
├── AGENTS.md               # stack, root commands, branch naming, security boundaries
├── packages/
│   ├── api/
│   │   └── AGENTS.md       # Express + Postgres conventions, package test command
│   ├── web/
│   │   └── AGENTS.md       # React, Tailwind, Vite, component conventions
│   └── shared/
│       └── AGENTS.md       # zod schemas, no DB imports allowed
└── tools/
    └── etl/
        └── AGENTS.md       # Python, pandas, different lint rules

Nesting is supported by Codex, Cursor, Copilot, Claude Code, Factory and Kilo Code, with the same general shape everywhere: the agent walks the directory tree and the nearest file wins on conflict. In Claude Code specifically, root-and-above files load at session start and a subdirectory's AGENTS.md loads when Claude opens a file there with the Read tool — and only if that subdirectory has none of the three CLAUDE.md filenames of its own.

Four practical rules:

• Defaults at the root, overrides at the leaf. Stack, branch naming and security boundaries at the root; per-package test commands and conventions at the leaf.
• Do not restate inheritance. If the root says "pnpm 9," the leaf should not repeat it. You are paying tokens for the duplication on every task.
• Keep leaves short. 30–80 lines each; the root can run to ~200.
• Mind the caps. Codex truncates at project_doc_max_bytes, 32 KiB by default. Claude Code loads a CLAUDE.md up to 4 MiB in full and skips anything larger, but adherence degrades long before that — its own guidance is under 200 lines.

What goes in a good AGENTS.md?

There is no required heading set. The sections that recur across the corpus — and that GitHub identified in its analysis of 2,500+ repositories — are:

• Setup and build commands — every command from git clone to a running build, with flags.
• Test commands — the full suite, a single suite, and a single test.
• Code style — formatter, linter, naming, file layout. Cite the config file.
• Project structure — the top two or three directory levels, one line each.
• Git and PR conventions — branch naming, commit format, PR template.
• Security — what must never be committed, which paths are protected, where env vars come from.
• Boundaries — three tiers: always do, ask first, never do. This is the section that prevents agent runaway.

A minimal, complete starter, close to the canonical example on agents.md:

# MyApp

## Setup
- Node 22.x, pnpm 9.
- `pnpm install`
- `pnpm dev` → http://localhost:3000

## Testing
- `pnpm test` runs vitest; `pnpm test --filter <package>` for one package.
- `pnpm lint:check` and `pnpm type:check` must pass before committing.
- Always add or update tests for the code you change.

## Boundaries
- Never edit `prisma/migrations/`; generate via `pnpm db:migrate`.
- Never edit generated code in `gen/` or `__generated__/`.
- Never commit `.env*`.
- Ask before adding a new top-level dependency.

## PRs
- Title format: `[<package>] <Title>`
- Conventional commits, squash on merge.

The phrasings that measurably move adherence, consistent with the research above:

• Imperative, not descriptive. "Run pnpm test before every commit" beats "this project uses pnpm test for testing."
• Concrete commands with flags. "pytest -x --tb=short tests/unit" beats "run the unit tests."
• Versions, not vibes. "Node 22.x, pnpm 9, Vite 5" beats "modern JS stack."
• Scope sentences per directory. "Backend code only in packages/api/src/" removes a whole class of cross-package edits.
• Generated-file guards. Name every directory a build step regenerates and forbid edits to it.
• Three-tier boundaries. Grouping into always / ask first / never gives the agent a classification problem instead of an open judgement call.

What should I never put in AGENTS.md?

1. A persona. "You are a helpful AI assistant who loves clean code" costs tokens and changes nothing.
2. A repository overview essay. The arXiv study found these specifically unhelpful. One sentence on architectural shape is plenty.
3. Your README, pasted. Double maintenance, zero new signal.
4. Marketing copy. The agent does not need to know you are the leading developer-first anything.
5. Reference documentation. If a section runs past ~30 lines it belongs in docs/ with a link.
6. Language defaults. "Use Python 3" is implicit from pyproject.toml. "Use Python 3.12 with uv, not pip" is real information.
7. Secrets. It is in version control; assume it leaks. Document env var names and where values come from.
8. Vague quality adjectives. "Write clean, idiomatic code" is signal-free. "Use Result<T, E> for fallible operations" is signal.
9. Contradictions with your other rules files. Claude Code's docs are explicit that when two instructions conflict, "Claude may pick one arbitrarily."
10. Stale content. A wrong AGENTS.md is worse than none, because the agent will follow it confidently. Update it in the same PR as the change it documents.

Cursor-heavy team? Our Cursor IDE complete guide covers when a path-scoped .mdc rule beats a global AGENTS.md, and which Project Rules to set for a small team.

How does AGENTS.md relate to .claude/rules, .cursor/rules and SKILL.md?

These are layers, not competitors. The useful mental model is: AGENTS.md is what is true all the time, scoped rules are what is true for certain files, and skills are packaged capabilities.

SKILL.md is worth understanding because it solves the problem AGENTS.md cannot: context cost. A skill directory holds a SKILL.md plus optional scripts/ and references/, and loads in three stages — metadata always, the body when triggered, bundled files on demand. Its frontmatter requires name (lowercase, hyphens, ≤64 chars) and description (≤1024 chars), where the description is the triggering signal and should be explicit about when to fire.

my-skill/
├── SKILL.md              # frontmatter + instructions
├── scripts/              # executable code the agent runs
└── references/           # docs loaded only when referenced

So: AGENTS.md for "how does this repo work," always loaded. SKILL.md for "how does this reusable capability work," loaded on demand. A serious setup uses both.

One more layer that is easy to miss: Claude Code's auto memory, which also loads every session. Claude writes its own notes into ~/.claude/projects/<project>/memory/, and the first 200 lines (or 25 KB) of the MEMORY.md index are loaded at the start of every conversation; topic files are read on demand. These files participate in context loading alongside your instruction files, which is why Anthropic hardened them: v2.1.284 (28 September 2026) neutralises "invisible characters and tags that imitate Claude Code's own markup" in MEMORY.md and recalled notes before they reach the model. Memory files are machine-local and not shared through git, so they are not a substitute for AGENTS.md — but if an agent is following a rule you never wrote, check there.

Do Claude Code Mods change how context files load?

Yes, and more directly than you would expect: AGENTS.md support is a mod.

Mods shipped in v2.1.287 on 1 October 2026 — "plugins may now modify deeper behavior." A mod is a plugin whose JavaScript or TypeScript handlers run inside Claude Code on events such as a tool call, a submitted prompt or an interface redraw, and each handler can observe the event, rewrite it, or answer it so the normal behaviour never runs.

Anthropic's mods documentation lists cc-plugin-agents-md among the built-in mods, described as "Loads AGENTS.md as project instructions," with its source public at mods/agents-md. That explains the parts of the feature that otherwise look arbitrary: you disable it in /plugin, you configure it under pluginConfigs, and in the first release it inherited a dependency on the telemetry pipeline.

Two consequences worth holding onto. First, a mod can rewrite or pre-approve tool calls — including approving a call an ask rule would have prompted for, or one your own PreToolUse hook blocked — and mods are not sandboxed. A third-party mod is code running with your permissions, so your AGENTS.md boundaries are guidance while a mod is enforcement. Second, instruction files were never a security boundary anyway. Claude Code's documentation says it plainly: CLAUDE.md and memory are "context, not enforced configuration," and to block an action regardless of what the model decides you need a PreToolUse hook or a permissions rule. Write AGENTS.md to make the agent better, not to make it safe.

How does AGENTS.md fit with MCP?

They sit at different layers and neither replaces the other. AGENTS.md is project-level instructions: what to do, what not to do, how to test, how to commit. MCP servers are project-level tools: an endpoint the agent can call to read a database, query monitoring, or fetch a ticket.

A well-configured repo has both, and they reference each other. .mcp.json (Claude Code, Codex) or .cursor/mcp.json (Cursor) tells the agent how to reach your servers; AGENTS.md tells it which to prefer — "use the db-readonly MCP server for schema questions, never query the prod database directly." If you are choosing servers, see our guide to the best MCP servers for Claude Code and Cursor.

How do you roll this out on a team?

1. Audit existing rules files. .cursorrules, .github/copilot-instructions.md, CLAUDE.md, GEMINI.md. Sort each line into universal vs tool-specific.
2. Write one AGENTS.md at the root. 100–200 lines, commands and boundaries first, no architecture essay.
3. Decide the Claude Code story. If you have no Claude-specific content, delete CLAUDE.md entirely so AGENTS.md loads directly. If you do, reduce it to @AGENTS.md plus the Claude-only material.
4. Pin a minimum version. Claude Code v2.1.281 or later for unconditional AGENTS.md support across providers and telemetry settings.
5. Tell people about CLAUDE.local.md. Anyone keeping one is silently opting out. Either they drop it or they set Project instructions to claude-md-and-agents-md in their user settings.
6. Move path-scoped rules to the right home. .cursor/rules/*.mdc for Cursor, .claude/rules/ with a paths field for Claude Code. Keep AGENTS.md for what is always true.
7. Nest for the top three packages in a monorepo, 30–80 lines each, no restated inheritance.
8. Wire it into the PR template. Any new test command, lint rule or boundary requires an AGENTS.md edit in the same PR.
9. Audit monthly. /doctor prompt-audit on Claude Code v2.1.283+, plus a read-through for anything the research says is dead weight.

FAQ

Does Claude Code read AGENTS.md?

Yes, since v2.1.277, published 18 September 2026. By default it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. Your personal ~/.claude/CLAUDE.md, your organisation's managed CLAUDE.md and .claude/rules/ files do not suppress it. Use v2.1.281 or later, where support also works on Bedrock, Vertex AI, Foundry, LLM gateways and sessions with telemetry disabled.

Do I need both AGENTS.md and CLAUDE.md?

No, in most repos. If you have no Claude-Code-specific content, ship AGENTS.md alone and do not create a CLAUDE.md — its presence suppresses AGENTS.md under the default setting. If you do have Claude-specific material (subagents, slash commands, hooks), keep a CLAUDE.md whose first line is @AGENTS.md and put the rest below. Or set Project instructions to claude-md-and-agents-md to have both read as written.

Which tools support AGENTS.md?

As of October 2026: OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Google Antigravity CLI, Gemini CLI, Jules, Factory, Amp, Aider, Zed, Warp, goose, opencode, Devin, Windsurf, Augment, RooCode, Kilo Code, JetBrains Junie, Ona, Phoenix, Semgrep, UiPath and VS Code. There is no significant mainstream holdout left. agents.md reports more than 60,000 open-source projects using the format.

What takes precedence if both exist?

It depends on the tool. Claude Code reads CLAUDE.md and ignores AGENTS.md by default; change it with Project instructions in /config (values claude-md-or-agents-md, claude-md-and-agents-md, claude-md, managed-only). Codex concatenates root-down so deeper files win, with AGENTS.override.md as a hard replace. Cursor combines nested files with parents, more specific winning, inside Team → Project → User order. Copilot takes the nearest AGENTS.md but ranks it below .github/copilot-instructions.md.

Do AGENTS.md files actually improve results?

Partly, and less than vendors imply. A February 2026 arXiv study, "Evaluating AGENTS.md," found that context files "do not generally improve task success rates, while increasing inference cost by over 20% on average." The breakdown is the useful part: instructions in context files are well followed, but repository overviews — "popular and recommended by model providers" — are not helpful. Write commands and boundaries; skip the architecture essay.

Where do I put AGENTS.md?

The repository root, which every supporting tool checks. In a monorepo, add nested files per package: Codex, Cursor, Copilot, Claude Code, Factory and Kilo all walk the tree and let the nearest file win. Put stack, branch naming and security boundaries at the root; per-package commands at the leaves.

Is AGENTS.md an official standard?

It is stewarded by the Agentic AI Foundation under the Linux Foundation, which gives it vendor-neutral governance, after originating as a collaboration between OpenAI, Amp, Google's Jules team, Cursor and Factory. It is a convention with cross-vendor buy-in rather than a formal RFC-style specification.

Does AGENTS.md support YAML frontmatter?

No. The spec is plain Markdown with no frontmatter. A v1.1 proposal (issue #135) that would have added optional description and tags fields for progressive disclosure in large monorepos was opened in January 2026 and closed on 24 August 2026 without being adopted. Do not depend on frontmatter in AGENTS.md. Note that scoped-rule formats are different: .claude/rules/ reads a paths field, and Cursor's .mdc rules read description, globs and alwaysApply.

AGENT.md or AGENTS.md?

Plural and uppercase: AGENTS.md. Singular AGENT.md is a fallback some tools accept (Kilo Code, for one). Never lowercase — case-sensitive filesystems treat agents.md as a different file.

How long should AGENTS.md be?

Short. Claude Code's own guidance is under 200 lines, because "longer files consume more context and reduce adherence." Codex truncates at project_doc_max_bytes, 32 KiB by default. Split by package rather than letting the root file grow past a few hundred lines.

Can I put secrets in AGENTS.md?

Never. It is committed to version control — treat it as fully public. Document the names of env vars and where to fetch the values from (Vault, AWS Secrets Manager, 1Password), not the values.

What if my agent ignores AGENTS.md?

Check the filename is uppercase and plural at the right directory level. Check the file is inside the tool's size cap. Restart the session, since most tools load instruction files at session start. On Claude Code specifically: confirm you are on v2.1.281+, confirm no CLAUDE.md or CLAUDE.local.md is shadowing it at or above your working directory, confirm the agents-md plugin is enabled in /plugin, and run /context to see what actually loaded under Memory files. Remember too that these files are guidance, not enforcement — for a hard block, use a permissions rule or a PreToolUse hook.

References

• agents.md — official spec page
• AGENTS.md v1.1 frontmatter proposal (issue #135, closed August 2026)
• Claude Code — How Claude remembers your project (CLAUDE.md, AGENTS.md, rules, auto memory)
• Claude Code — Mods overview
• anthropics/claude-code — mods/agents-md source
• anthropics/claude-code#6235 — Feature Request: Support AGENTS.md
• Hacker News — Claude Code now reads AGENTS.md if there is no CLAUDE.md
• Hacker News — Claude Code reads AGENTS.md only when telemetry is on [fixed]
• OpenAI Codex — AGENTS.md configuration
• Cursor — Rules and AGENTS.md
• GitHub Copilot — repository custom instructions and agent instructions
• Google Antigravity CLI — Gemini CLI migration
• arXiv 2602.11988 — Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
• GitHub Blog — How to write a great AGENTS.md
• Codersera — AGENTS.md vs CLAUDE.md vs Cursor rules
• Codersera — Claude Code vs OpenAI Codex (2026)

What should you actually do?

If you are starting from nothing: commit a 100–200 line AGENTS.md at the repository root, heavy on commands and boundaries, light on prose. Do not create a CLAUDE.md unless you have Claude-Code-specific content to put in it. Pin Claude Code to v2.1.281 or later. Nest per package once the monorepo justifies it.

If you already have the old CLAUDE.md-imports-AGENTS.md workaround: you can leave it, and it is still the most portable form. But if the CLAUDE.md holds nothing but the import, deleting it is now the cleaner setup.

And keep the file honest. The measured benefit comes from the instructions an agent can act on, not from explaining your architecture to a model that can read the code. That is the one piece of guidance most AGENTS.md advice still gets backwards.

If you are extending your engineering team with people who already work this way in production — fluent in agent context files, monorepo nesting and MCP integration — Codersera vets senior remote engineers for exactly that kind of orchestration fluency.