Jonathon's AI Wiki

AGENTS.md — One Instructions File for Codex, Cursor, Copilot and Claude Code

8 min read

Source: Claude Code docs “How Claude remembers your project” (ai-research/claude-code-docs-memory-2026-09-29.md); v2.1.277 and v2.1.283 release notes and changelog (raw/anthropic-watch-claude-code-tag-v2-1-277.md, raw/anthropic-watch-claude-code-tag-v2-1-283.md, ai-research/claude-code-docs-changelog-2026-09-18.md); agents.md site (ai-research/agents-md-official-site-2026-09-29.md); The New Stack (ai-research/thenewstack-claude-code-vs-cursor-vs-codex-vs-antigravity-2026-07-02.md); Peter Steinberger (ai-research/steipete-just-talk-to-it-2026-07-03.md); repos (ai-research/jcodesmore-ai-website-cloner-template-2026-04-27.md, ai-research/mvanhorn-last30days-skill-2026-04-27.md); videos (raw/I_figured_out_the_best_way_to_vibe_code.md, raw/You_aren_t_using_Codex_like_me....md, raw/Build_Sell_with_Codex_5+_Hour_Course.md, raw/Building_a_Software_Factory_that_actually_works_Full_Course.md, raw/Build_An_AI_Second_Brain_Knowledge_Base_Step-By-Step.md, raw/DHH_-_Future_of_Programming_AI_Agentic_Engineering_Vibe_Coding_Linux_Lex_Fridman_Podcast_501.md, raw/Every_OpenClaw_Concept_Explained_for_Normal_People.md, raw/Tips_to_get_better_at_Using_Hermes_Agent_Live_Tutorial.md); Reddit (raw/reddit-1ths4dt.md, raw/reddit-1vhmb7f.md).

AGENTS.md is a plain Markdown file that tells coding agents how to work on a project; its official site calls it “a README for agents” and lists 23 compatible tools, among them Codex, Cursor, Gemini CLI, GitHub Copilot’s coding agent and Windsurf. Claude Code did not read it on its own until v2.1.277 (2026-09-18), which “Added AGENTS.md support for project instructions (when no CLAUDE.md exists)”.

Key Takeaways

  • No required fields. “Just standard Markdown”, used by 60k+ open-source projects per the site, “now stewarded by the Agentic AI Foundation under the Linux Foundation”.
  • Claude Code reads it only when no CLAUDE.md is in the way. A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md at or above the working directory wins by default; even a lone CLAUDE.local.md stops AGENTS.md loading.
  • /config → Project instructions can load both files instead (claude-md-and-agents-md) without reading any AGENTS.md twice.
  • One file for every tool: @AGENTS.md at the top of a CLAUDE.md (Windows-safe, allows Claude-only rules) or a CLAUDE.md symlink. If a CLAUDE.md only says “read AGENTS.md”, Claude sees it “only if it decides to open the file”.
  • Keep it lean: skip what the code already says; keep workflows, routing and notes on tools newer than the model; prune after model releases.
  • In OpenClaw, agents.md is the operating manual injected with soul.md, user.md and tools.md, so its length is a recurring token cost.

What it is and who reads it

  • Purpose: READMEs are for humans; AGENTS.md holds “build steps, tests, and conventions that might clutter a README”.
  • Suggested sections: overview, build and test commands, code style, testing, security, PR rules, deployment: “anything you’d tell a new teammate”. Agents “will attempt to execute” listed checks.
  • Monorepos: one per package; “the closest one takes precedence” (OpenAI’s main repo had 88), and “explicit user chat prompts override everything”.
  • Readers: The New Stack (2026-06-01) named Codex, Cursor, Copilot and Windsurf and called Claude Code “the holdout”. Matthew Berman: “basically all of these tools support agents.md” except Claude Code. The agents.md list fetched 2026-09-29 still omits Claude Code.
  • Origin:^[ambiguous] The New Stack: “OpenAI started it; Google, Cursor, and Sourcegraph joined”, under the Agentic AI Foundation “since December 2025”. The official site: it “emerged from collaborative efforts” including OpenAI Codex, Amp, Jules, Cursor and Factory; no date.

How Claude Code reads it (v2.1.277+)

Your repository hasClaude reads
AGENTS.md, no CLAUDE.md or CLAUDE.local.md at or above the working directoryAGENTS.md
AGENTS.md plus a CLAUDE.md or CLAUDE.local.mdCLAUDE.md files only
A CLAUDE.md that imports AGENTS.mdCLAUDE.md, with AGENTS.md via the import
  • Directory levels: yes. At session start Claude reads every AGENTS.md and .claude/AGENTS.md in the working directory and above; a subdirectory’s AGENTS.md loads when Claude reads a file there and that folder has no CLAUDE.md files of its own.
  • Alongside it: ~/.claude/CLAUDE.md, the managed CLAUDE.md and .claude/rules/ still load; inside it, @path imports expand and claudeMdExcludes applies.
  • Never read: AGENTS.local.md, AGENTS.override.md, anything under .agents/.
  • Unlike CLAUDE.md: InstructionsLoaded hooks don’t fire; --add-dir directories never contribute theirs; external @path imports load only if already approved, with no prompt.
  • Check it loaded: interactive sessions show a line such as no CLAUDE.md found; AGENTS.md loaded: <path>; /memory lists it from v2.1.280.
  • Not loaded: before v2.1.277, with the built-in agents-md plugin disabled, or sometimes in the first session after upgrading from v2.1.276 or earlier. The v2.1.277 note said “not yet on Bedrock, Vertex or Foundry”; per the docs, Bedrock and telemetry-off sessions load it from v2.1.281.
Project instructions valueLoads
claude-md-or-agents-md (default)CLAUDE.md, or AGENTS.md when no CLAUDE.md/CLAUDE.local.md exists
claude-md-and-agents-mdBoth; each directory’s CLAUDE.md first, then its AGENTS.md
claude-mdCLAUDE.md only
managed-onlyManaged CLAUDE.md and auto memory at launch

One file for several agents

  • Import: @AGENTS.md first, Claude-only rules below; the docs’ route when you also keep a CLAUDE.md or a session can’t load AGENTS.md.
  • Symlink: ln -s AGENTS.md CLAUDE.md. Edit and Write refuse to write through it and point Claude at AGENTS.md. On Windows, Git checks a committed symlink out as a plain text file unless core.symlinks is on, leaving “a one-line CLAUDE.md”.
  • Steinberger’s caveat: he symlinks, but GPT-5 and Claude want different prompting, so “these files can’t optimally be shared”.
  • Sync script: JCodesMore’s cloner template keeps AGENTS.md as the “single source of truth”; CLAUDE.md and GEMINI.md import it and scripts/sync-agent-rules.sh regenerates the other platform files.
  • Reverse pointer or copy: mvanhorn/last30days-skill added an AGENTS.md “pointing to CLAUDE.md”; Nate Herk recommends copying CLAUDE.md to AGENTS.md (“It’s the exact same thing”) and has /audit check they’re “synced up”.
  • Retire workarounds (docs): an @AGENTS.md import can stay (never double-loads); swap a sentence-style pointer for an import; delete a SessionStart hook that prints AGENTS.md. DHH (Lex Fridman #501) on his CLAUDE.md files: “all it includes is a pointer to the agents MD”.
  • Migration: /init with CLAUDE_CODE_NEW_INIT=1 incorporates relevant parts of AGENTS.md; /import (v2.1.213+) appends a one-time copy, which will drift where an import won’t.

What to put in it

  • Only what the agent can’t derive. Ross Mike: “most people’s agents.md file is useless because they were telling the agents.md file what the code looked like”. His holds a workflow “not native to the agent”, starting with a new-feature skill: “Every new feature starts in a fresh Git work tree branched from origin main … Never build on main.”
  • What’s newer than the model. Steinberger’s covers git, product context, naming and API patterns, React patterns, migrations, testing and ast-grep rules, “often it’s things that are newer than world knowledge”; he deleted Tailwind 4 notes once models knew it.
  • Routing. Nate Herk: “the real bulk of my agent MD is what I call routing” (“If you need business stuff, you go to the wiki”). An r/hermesagent megathread relays a Codex layout with the “root AGENTS.md as routing rules only” and detail in agents/, standards/, workflows/, and says to “put delegation policy in AGENTS.md / skills”.
  • Preferences. Berman: workflow, commit style, personality, deploy process; start with “the vibe of the model”.
  • Prune. After each model release Berman asks Codex to “Review my agents.md file for any stale rules”, since it loads “very frequently into the context window”. Claude Code’s /doctor prompt-audit (v2.1.283+) reads AGENTS.md files too.
  • Beyond code. A Codex second brain keeps its ingest and query operations in AGENTS.md and grows by asking Codex to “update the agents.md file”.

Agent workspaces: OpenClaw and Hermes

  • OpenClaw files: soul.md (personality), identity.md (name, vibe, emoji), agents.md (“your operating manual, your rules, your priorities, your boundaries”), user.md (you), tools.md (tool notes), memory.md, heartbeat.md. The video suggests a daily loop where the agent proposes edits to them.
  • Token cost: the video says they are re-injected with every message, so 10,000 tokens of files cost 10,000 tokens per message. One Reddit operator cut a ~300-line AGENTS.md (~3,000 tokens) to a 56-line index (~570) with rules moved to docs/ read on demand; bootstrap fell from ~6,115 to ~2,082 tokens.
  • Hermes layering: one agents.md for the server, one saying “this is the Git repo for all of your projects”, one per project folder, which the host compares to CLAUDE.md. Link the Hermes docs and GitHub there, “because the agents.md file is the first thing they read”.

Try It

  1. Find every CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md from your repo up to /; any one blocks AGENTS.md by default.
  2. AGENTS.md only: update Claude Code to v2.1.281+, start a session, and find the file in /memory.
  3. Need Claude-only rules: create CLAUDE.md with @AGENTS.md on line 1; confirm under Memory files in /context.
  4. Cut what the agent can read from the code, then run /doctor prompt-audit after the next model upgrade.

Implementation

Tool/Service: Claude Code v2.1.277+ (built-in agents-md plugin); any AGENTS.md-compatible agent. Setup: /config → Project instructions, or pluginConfigs in ~/.claude/settings.json, a --settings file or managed settings (project and local settings files are ignored). Cost: No separate charge is stated; the file’s tokens enter context every session. Integration notes: per the agents.md FAQ, Gemini CLI needs { "context": { "fileName": "AGENTS.md" } } in .gemini/settings.json and Aider needs read: AGENTS.md in .aider.conf.yml.

{ "pluginConfigs": { "agents-md@builtin": { "options": { "instructionFiles": "claude-md-and-agents-md" } } } }
@AGENTS.md
 
## Claude Code
Use plan mode for changes under `src/billing/`.

Open Questions

  • Vertex and Foundry: the docs name only Bedrock (fixed by v2.1.281); the vault’s v2.1.281 release note doesn’t mention AGENTS.md.
  • omitClaudeMd (v2.1.271): the docs say subagents that “skip project instructions” skip AGENTS.md, without naming this field.
  • Origin: “OpenAI started it” and “December 2025” come only from The New Stack.
  • Other tools: whether Codex or Cursor also load parent-directory AGENTS.md files isn’t in these sources.

Graph View

Backlinks