AGENTS.md vs CLAUDE.md: share one file across agents

The short answer

AGENTS.md and CLAUDE.md do the same job: a Markdown file in the repository that a coding agent reads at the start of a session, holding build commands, conventions and the rules you would otherwise repeat in chat. The difference is who reads them. AGENTS.md is an open format that emerged from OpenAI Codex, Amp, Jules from Google, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. CLAUDE.md is the file Anthropic's Claude Code was built around.

Claude Code v2.1.277 and later reads AGENTS.md as the project instructions, but only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. When both exist, it reads the CLAUDE.md files only. So the question is rarely which file to pick. It is how to keep one set of instructions that every tool on the team actually loads.

Sources: AGENTS.md open format; Anthropic, How Claude remembers your project (Claude Code)

Which file each tool reads

Each row below comes from the tool's own documentation, read on 31 October 2026. Defaults change between releases, so check the linked page before you rely on a detail.

The agents.md site lists many more tools that read the format, including the GitHub Copilot coding agent, VS Code, Windsurf, Zed, Warp, Aider and opencode. A listing says the tool supports the file, not how it orders or merges it, so the per-tool check in the last column still applies.

Sources: Anthropic, How Claude remembers your project (Claude Code); OpenAI, Custom instructions with AGENTS.md (Codex); Cursor, Rules; Gemini CLI, Provide context with GEMINI.md files; AGENTS.md open format

Where the two files behave differently

The content can be identical while the loading rules are not. These differences are the usual reason a rule works in one tool and is ignored in another.

• Overrides. Codex checks AGENTS.override.md before AGENTS.md in every directory, and an override replaces the regular file in that directory. Claude Code does not read AGENTS.override.md, AGENTS.local.md or anything under a .agents/ directory.
• Personal files. CLAUDE.local.md is the place for your own uncommitted notes in Claude Code, but it counts as a CLAUDE.md file, so adding one to a project that relies on AGENTS.md stops Claude Code from reading AGENTS.md for you. The fix is the claude-md-and-agents-md setting or an @AGENTS.md import.
• Imports. Claude Code expands @path imports up to four hops deep, and Gemini CLI supports the same @file.md syntax. The Codex AGENTS.md guide describes no import syntax: Codex concatenates one file per directory from the root down.
• Size. Codex stops adding files once the combined instructions reach project_doc_max_bytes, 32 KiB by default. Anthropic recommends keeping each CLAUDE.md under about 200 lines, because longer files consume context and reduce adherence.
• Nesting. Codex and Cursor combine nested AGENTS.md files with their parents, with the more specific file taking precedence. Claude Code loads a subdirectory's AGENTS.md when it reads a file there and that subdirectory has no CLAUDE.md of its own.

None of these files is enforced configuration. Anthropic's documentation says Claude treats them as context and points to hooks for anything that must be blocked regardless of what the model decides.

Sources: OpenAI, Custom instructions with AGENTS.md (Codex); Anthropic, How Claude remembers your project (Claude Code); Cursor, Rules; Gemini CLI, Provide context with GEMINI.md files

Three ways to keep one shared file

Every setup below keeps AGENTS.md as the single file people edit, because it is the one most tools read without configuration.

• AGENTS.md only. Delete or never create a CLAUDE.md. Codex and Cursor read the file natively, Claude Code v2.1.277 and later reads it when no CLAUDE.md exists, and Gemini CLI needs context.fileName. The weak point is Claude Code: older versions, sessions where its AGENTS.md plugin is disabled, and in some cases the first session after an upgrade read CLAUDE.md files only, and one person's CLAUDE.local.md switches the shared file off for them.
• AGENTS.md plus a CLAUDE.md that imports it. The CLAUDE.md starts with the line @AGENTS.md and adds only Claude-specific instructions below it, such as when to use plan mode. Claude reads the imported file first, then the rest. This works on every Claude Code version and in every session, so it is the safer default for a team.
• AGENTS.md plus a symlink. Running ln -s AGENTS.md CLAUDE.md makes both names point at one file. Anthropic lists two catches: Claude's edit tools refuse to write through the link and edit AGENTS.md instead, and on Windows a symlink needs Administrator rights or Developer Mode, while Git checks a committed symlink out as a one-line text file unless core.symlinks is enabled.

If a repository already has a large CLAUDE.md and the team is adding Codex, the reverse also works: list CLAUDE.md in project_doc_fallback_filenames so Codex reads it. That setting lives in each person's ~/.codex/config.toml, though, so every teammate has to set it, and a Codex user without it silently gets no project instructions. Moving the shared rules into AGENTS.md avoids that dependency.

Sources: Anthropic, How Claude remembers your project (Claude Code); OpenAI, Custom instructions with AGENTS.md (Codex)

Check that every tool loaded it

A shared file only helps if each tool actually loads it, and the failure is silent: the agent simply works without your rules. A five minute check catches it:

• Add a harmless marker line to AGENTS.md, for example: If asked for the instructions marker, answer blue heron.
• In Claude Code, start a new session, run /context and confirm the file appears under Memory files, then ask for the marker. In an AGENTS.md-only repository, Claude Code also prints a line such as no CLAUDE.md found; AGENTS.md loaded.
• In Codex, run codex --ask-for-approval never "List the instruction sources you loaded." from the repository and confirm the order: your global file, then the root AGENTS.md, then any nested file.
• In Gemini CLI, run /memory show. In Cursor, ask the agent for the marker in a new chat.
• Remove the marker once every tool has answered, and repeat the check after upgrading a tool or adding a CLAUDE.local.md.

Sources: Anthropic, How Claude remembers your project (Claude Code); OpenAI, Custom instructions with AGENTS.md (Codex); Gemini CLI, Provide context with GEMINI.md files

What one file cannot do

A shared AGENTS.md solves the repository layer well. It does not reach three places that teams usually expect it to.

First, other repositories. The file lives in one repository, so a convention that applies to every project has to be copied into each one and kept in step by hand. Second, personal and company-wide defaults. Each tool keeps its global layer in its own place: ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, Cursor's User Rules, ~/.gemini/GEMINI.md. There is no single global file they all read. Third, chat apps. Claude, ChatGPT and Gemini in the browser do not read a repository file, so the people on a team who work there never see the rules the coding agents follow.

A file is also only as current as its last commit. A decision made in a session yesterday is not in it until someone writes it down.

Sources: Anthropic, How Claude remembers your project (Claude Code); OpenAI, Custom instructions with AGENTS.md (Codex); Cursor, Rules

Where Space fits, and where it does not

Space is the workspace this site documents. It does not replace AGENTS.md: build commands, test commands and the conventions of one codebase belong in the repository, next to the code they describe, where every coding agent reads them without a network call.

Space covers the layers a file cannot reach. It keeps a team's playbooks (skills), documents, decisions and memory in one place and serves them over MCP to the AI tools its people connect, including the chat apps. Claude Code, Codex, Hermes, Cursor, Claude, ChatGPT, Gemini and Cline have each been tested with Space. When a request matches a skill, Space instructs the agent to offer it and to apply it only once the person agrees, and only the Space's owner can change a skill.

The limits are specific. Space is a hosted service that each tool must be connected to. Memory extraction may be asynchronous, and it may be wrong. Connecting an agent does not import earlier conversations, so the first useful memory is one someone saves on purpose. If your whole team works in one repository with coding agents, a well kept AGENTS.md may be all you need. If the same playbook has to reach several repositories and the chat apps, create an account at app.getspace.sh, or book a call to start a pilot on one playbook.

Sources: Space, Agent connections; Space, Agent skills for teams: one playbook in Claude, ChatGPT and Codex