AGENTS.md vs CLAUDE.md: which file do agents read?

When several coding agents share a repository, each tool looks for instructions in its own place. This guide covers what each file is, which tools read which, and how to write one set of rules they all follow. We checked every tool claim against that tool's own documentation on October 20, 2026.

What is AGENTS.md?

AGENTS.md is a plain Markdown file, usually at the root of a repository, that tells coding agents how to work on the project. The official AGENTS.md site calls it "a README for agents": the place for build steps, test commands and conventions that would clutter a README for humans. It has no required fields, so use any headings you like.

In a monorepo you can add more AGENTS.md files inside packages. The site explains that agents read "the nearest file in the directory tree, so the closest one takes precedence", and that explicit chat prompts override everything. The format came out of work by OpenAI Codex, Amp, Google's Jules, Cursor and Factory, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation.

What is a CLAUDE.md file?

CLAUDE.md is the Markdown file that Claude Code reads at the start of every session to get your persistent instructions. Anthropic's Claude Code memory docs list four places it can live, loaded from the broadest to the most specific:

Claude Code combines these files; none replaces another. Files in your working directory and above it load at launch, and files in subdirectories load once Claude reads or edits a file in that folder. A CLAUDE.md can pull in other files with @path imports, up to four hops deep. Anthropic suggests keeping each file under 200 lines, because "longer files consume more context and reduce adherence."

Which coding agents read AGENTS.md and CLAUDE.md?

Codex, Cursor and GitHub Copilot read AGENTS.md. Claude Code reads CLAUDE.md first and AGENTS.md as a fallback, and GitHub Copilot also accepts a CLAUDE.md in the repository root. Each tool also has its own extra format. As of October 2026:

Sources: Claude Code memory docs, Codex custom instructions with AGENTS.md, Cursor rules and GitHub's repository custom instructions. The AGENTS.md site lists more tools that read the format, including Jules, Aider, Gemini CLI, Zed, Windsurf and Devin.

How does Claude Code choose between AGENTS.md and CLAUDE.md?

By default, Claude Code reads your CLAUDE.md files if you have any, and falls back to AGENTS.md only when you don't. Anthropic's docs spell out three cases:

Three details catch people out:

• CLAUDE.local.md counts. Adding a personal CLAUDE.local.md to a project that relies on AGENTS.md stops Claude Code from reading AGENTS.md for you. Your ~/.claude/CLAUDE.md, a managed CLAUDE.md and .claude/rules/ files don't count, so they load alongside AGENTS.md.
• Override and local variants are ignored. Claude Code does not read AGENTS.override.md, AGENTS.local.md or anything under .agents/. Rules you put in a Codex override are invisible to Claude.
• You can change the default. In a session, open /config and set Project instructions to claude-md-or-agents-md (the default), claude-md-and-agents-md (both, CLAUDE.md first), claude-md or managed-only.

How do you keep one instructions file for every agent?

Write the shared rules once in AGENTS.md, and give Claude Code a CLAUDE.md that imports it. Every tool in the table above reads AGENTS.md. The import also works in Claude Code versions that can't read AGENTS.md directly, such as those before v2.1.277.

1. Put the shared rules in AGENTS.md at the repository root: commands, conventions, review rules and the board section further down.
2. Create a CLAUDE.md that starts with an import, then add anything only Claude needs below it. Claude reads the imported file first and never loads AGENTS.md twice.

@AGENTS.md

## Claude Code only
- Use plan mode before changing anything under src/billing/.

3. Or skip CLAUDE.md, or use a symlink, if you have nothing Claude-specific. With no CLAUDE.md, Claude Code v2.1.277 and later reads AGENTS.md directly. A symlink also works, but Anthropic recommends the import if anyone on the team uses Windows, where Git may check a committed symlink out as a one-line text file.

ln -s AGENTS.md CLAUDE.md

4. Keep personal notes out of the way. If you rely on the AGENTS.md fallback, don't add a CLAUDE.local.md. Put personal notes in ~/.claude/CLAUDE.md, which applies to every project and doesn't turn the fallback off, or set Project instructions to claude-md-and-agents-md. If your CLAUDE.md already imports AGENTS.md, a CLAUDE.local.md is fine.
5. Check what each agent loaded. In Claude Code v2.1.280 or later, run /memory or /context and look for the file. In Codex, OpenAI suggests codex --ask-for-approval never "Summarize the current instructions."

What should go in AGENTS.md, and what should stay out?

Put in the facts an agent needs in every session and can't work out from the code. Keep out secrets, long procedures and anything that must always happen. Anthropic's advice is to write instructions "concrete enough to verify", such as "Run npm test before committing" instead of "Test your changes".

Size matters too. Codex stops adding instruction files once their combined size reaches 32 KiB by default, and Claude Code warns at startup when a file is over its recommended length. For running several agents in parallel, with one git worktree each, see how to coordinate multiple AI coding agents.

How do you write board rules that every agent follows?

Write the rules against what the board's tools actually return, not what you assume they return. The Flux MCP server gives agents its 12 tool names and short descriptions but no workflow of its own, so your AGENTS.md is where the workflow lives. We read the server's code to find the details that change how a rule should be worded. As of October 2026:

• Cards are addressed by UUID. update_card, move_card, add_comment and reorder_cards take the card's id, which get_board and list_cards return. move_card also takes the target column's id, not its name. People see a short ID such as WEB-12 on the card and in its link, so tell agents which one to use.
• Comments come back without an author. get_card returns each comment's text and time but no name, and anything an API key writes shows under the name of the person who created the key. When several agents use keys from the same person, a signature in the comment is how you tell them apart.
• Only the description travels. get_card returns the card's own fields and its comments, not checklist items or assignees. Acceptance criteria belong in the description, as covered in how to write acceptance criteria for AI agents.
• Search is narrow. search_cards matches card titles only and returns at most 20 cards.
• Writes need the Write scope. Without it, the write tools reply "Error: write scope required". The key's creator also needs the member role or higher in the workspace.

An example board section for AGENTS.md, to adapt to your board and column names:

## Flux board (shared by every agent in this repo)
Board: "Website". Find it with list_boards, then read it with get_board.

- Use each card's id (a UUID) from get_board or list_cards in
  update_card, move_card, add_comment and reorder_cards. Not the
  short ID people see, such as WEB-12. move_card takes the
  column's id from get_board, not its name.
- Take cards only from "Ready for agent". Read the card with get_card
  first. The goal and acceptance criteria are in the description.
  Checklist items and assignees are not returned over MCP.
- Claim a card: move_card to "In Progress", then add_comment.
  Comments show under the key owner's name and come back without an
  author, so start every comment with [your agent name].
- search_cards matches card titles only and returns up to 20 cards.
  If you can't find a card by title, read the board with get_board.
- Finished means "Needs review": comment what changed, how to check it
  and the PR link, then move the card there. Never move a card to Done.
- Never put a Flux API key in this file, a comment or a commit.

The key itself goes in the client's MCP config, not in this file. The Flux MCP server setup shows the config for each client, including Codex's bearer_token_env_var. In Claude Code's .mcp.json you can write the header as Bearer ${FLUX_API_KEY}, and in Cursor's mcp.json as Bearer ${env:FLUX_API_KEY}.

Do AGENTS.md and CLAUDE.md enforce anything?

No. Both are guidance the model reads, not rules a program checks. Anthropic says Claude treats CLAUDE.md "as context, not enforced configuration", and points to a PreToolUse hook when you need to block an action whatever Claude decides. The AGENTS.md site notes that explicit chat prompts override the file.

The board works the same way. Flux does not stop an agent whose key has the Write scope from moving a card to Done. The review column is a convention, and a person checking Done keeps it honest. Changes made over MCP are not written to the Flux activity log as of October 2026, so the agent's signed comments are the record of what it did. For agents that only report, create a key without the Write scope. The human-in-the-loop guide shows how to set up that review gate, and the kanban board for AI agents page covers the board layout.