Skip to main content

AGENTS.md & Cross-Tool Interop

Intermediate

You already know CLAUDE.md — Claude Code's project briefing. But your repo is probably touched by more than one agent: a teammate runs Codex, CI uses a coding bot, someone opens the repo in Cursor. AGENTS.md is the open standard those tools agree to read, so you write your project's instructions once instead of maintaining a different file per tool.

What you'll learn
  • What AGENTS.md is and who stewards it
  • Why Claude Code reads CLAUDE.md and not AGENTS.md
  • Three reliable ways to keep one source of truth across tools
  • How nested and global AGENTS.md files merge
  • What belongs in the file — and what to keep out

What AGENTS.md is​

AGENTS.md is a plain Markdown file at the root of your repo — think of it as a README written for agents instead of humans. It tells a coding agent how to build, test, and contribute to the project. The format has no required fields: agents simply read the prose.

It's an open standard stewarded by the Agentic AI Foundation (AAIF) under the Linux Foundation, and as of mid-2026 it's used by 60k+ open-source projects and read by 20+ tools — including OpenAI Codex, Google's Jules and Gemini CLI, Cursor, Windsurf, Devin, Zed, Warp, Aider, goose, Amp, VS Code, JetBrains Junie, Factory, Semgrep, and GitHub Copilot's coding agent.

What you'll learn
  • AGENTS.md is a convention, not a runtime: each tool decides how it discovers, merges, and injects the file.
  • No schema is enforced — clear prose beats rigid structure.
  • It complements your README; it does not replace it.

The Claude Code catch​

Here's the part people trip on: Claude Code reads CLAUDE.md, not AGENTS.md. If your repo only has an AGENTS.md, Claude Code ignores it by default. That's not a bug — it predates the standard — but it means a multi-tool repo needs a deliberate sync strategy, or your instructions silently drift apart.

Watch out
  • Do not assume Claude Code falls back to AGENTS.md — it does not read it automatically.
  • Two hand-maintained files (CLAUDE.md and AGENTS.md) will drift. Pick one source of truth.
  • Verify current behavior in the official memory docs before relying on any fallback claim.

Keep one source of truth​

Three patterns keep CLAUDE.md and AGENTS.md in sync without duplicating content. Pick by your team's platform.

Guided walkthrough1 of 3
  1. Make CLAUDE.md a symlink to AGENTS.md. Claude Code follows symlinks and reads the target byte-for-byte — one real file, zero merge logic. Caveat: on Windows, creating a symlink needs Developer Mode or admin rights, so cross-platform teams may prefer the import method.

Symlink CLAUDE.md to the shared standard (macOS / Linux)

ln -s AGENTS.md CLAUDE.md

Or keep a one-line CLAUDE.md that imports it

@AGENTS.md
Pro tip
  • Symlink when your whole team is on macOS/Linux — it's the least to maintain.
  • Use @import when Windows contributors are in the mix.
  • Commit whichever you choose so the whole team gets the same behavior.

How nested and global files merge​

The richer agents treat AGENTS.md hierarchically — the same mental model as the CLAUDE.md memory hierarchy. Codex, for example, walks from a global file in your home directory down through the Git root to your current folder, concatenating as it goes:

Files closer to the work win, because they're concatenated last and override earlier guidance. So a services/payments/AGENTS.md inherits the repo-root instructions and adds rules that apply only inside that service — drop specialized guidance as close to the specialized code as possible.

Interop at a glance
Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.
1 / 5

What to put in it​

The same discipline as a good CLAUDE.md — the standard just suggests a few common sections:

  • Project overview — what this is, in two sentences.
  • Build & test commands — how to run, test, and lint.
  • Code style — conventions an agent can't infer.
  • Testing instructions — what "done" means.
  • Security considerations — what never to touch or commit.
  • Commit / PR guidelines — message format, branch rules.
Watch out
  • Agents follow the file literally — stale or aspirational instructions actively hurt, exactly like CLAUDE.md.
  • Keep it short and true; describe how the project works today.
  • Never commit secrets; reference big docs instead of pasting them.

Check yourself​

Check yourself

0/3
  1. Does Claude Code read AGENTS.md automatically?
  2. Your team is fully on macOS and Linux. What's the lowest-maintenance way to share one instruction file across Claude Code and Codex?
  3. When agents merge a global, a repo-root, and a subdirectory AGENTS.md, which one wins on conflicts?
Key takeaways
  • AGENTS.md is the open, Linux-Foundation-stewarded standard 30+ coding agents read — a README for agents.
  • Claude Code reads CLAUDE.md, not AGENTS.md, so multi-tool repos must keep them in sync.
  • Symlink CLAUDE.md → AGENTS.md on Mac/Linux, or use a one-line @AGENTS.md import for cross-platform teams.
  • Nested files merge global → root → subdirectory, with the closest file winning.
  • Fill it like a great CLAUDE.md: overview, build/test commands, conventions, security, and guardrails — short and true.

Next​

Sources & further reading​