AGENTS.md vs CLAUDE.md: How to Use Both

AGENTS.md is a Markdown file at the root of a repository that tells AI coding agents how to work on the project: setup and test commands, code style, conventions, anything you would tell a new teammate (agents.md). It is an open format read by agents such as OpenAI Codex, Cursor, Gemini CLI and GitHub Copilot's coding agent, and Claude Code reads it too, but by default only when the project has no CLAUDE.md (Claude Code docs: AGENTS.md). Below is what each file does, how Claude Code decides between them, and the setup this site's repository uses: a CLAUDE.md whose first line imports AGENTS.md. Every Claude Code detail was checked against the docs on October 3, 2026.

What is AGENTS.md?

Its site calls it a README for agents: a predictable place for the build steps, tests and conventions that would clutter a README or do not matter to human contributors (agents.md). There are no required fields. It is standard Markdown, and the agent reads whatever headings you write. The site suggests a project overview, build and test commands, code style, testing instructions and security considerations, plus commit and pull request rules. In a monorepo you can put another AGENTS.md inside each package: agents read the nearest file in the directory tree, and an explicit prompt in the chat overrides all of them.

A minimal file, from the site's own example:

# AGENTS.md
 
## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`
 
## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

Which coding agents read AGENTS.md?

The site says the format is used by over 60,000 open-source projects and lists agents including Codex from OpenAI, Jules and Gemini CLI from Google, Cursor, GitHub Copilot's coding agent, Devin, Windsurf, Junie from JetBrains, Zed, Warp, VS Code, Aider and Factory (agents.md). The site's FAQ gives the config line for two of them: Aider takes read: AGENTS.md in .aider.conf.yml, and Gemini CLI takes "context": { "fileName": "AGENTS.md" } in .gemini/settings.json. The format came out of work across OpenAI Codex, Amp, Jules, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation.

How is CLAUDE.md different?

CLAUDE.md is Claude Code's own instruction file, and Claude Code defines where it lives (CLAUDE.md locations):

Claude Code concatenates the CLAUDE.md files it finds instead of letting one override another (how CLAUDE.md files load), and a CLAUDE.md can pull in other files with @path imports up to four hops deep (import additional files). What matters more than the differences: Claude treats CLAUDE.md as context, not enforced configuration (CLAUDE.md vs auto memory), and it can read AGENTS.md as your project instructions, in place of CLAUDE.md, alongside it or through an import (AGENTS.md).

Does Claude Code read AGENTS.md?

Yes, from v2.1.277, and the default depends on what else is in the repository (AGENTS.md):

The middle row is the trap. A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md anywhere from your working directory up makes Claude skip AGENTS.md, so adding a personal CLAUDE.local.md to a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you (when Claude Code reads AGENTS.md). Your ~/.claude/CLAUDE.md, a managed CLAUDE.md and .claude/rules/ files do not count, and keep loading alongside it. Claude Code does not read AGENTS.local.md, AGENTS.override.md or anything under a .agents/ directory. When it loads AGENTS.md on its own, an interactive session shows a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. If a guide says Claude Code reads only CLAUDE.md, check whether it predates v2.1.277.

How do you change which file Claude Code loads?

Type /config and set Project instructions (choose which instruction files load). claude-md-or-agents-md is the default described above, claude-md-and-agents-md reads both with each directory's CLAUDE.md first, claude-md reads only CLAUDE.md, and managed-only reads only your organization's managed CLAUDE.md and auto memory at launch. The same value can go in ~/.claude/settings.json, a --settings file or managed settings, but Claude Code ignores it in project and local settings files:

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

The setting does not appear in /config on versions before v2.1.277 or with the built-in agents-md plugin disabled, and those sessions read CLAUDE.md only (when AGENTS.md support is unavailable).

How do you use both files in one repository?

Keep AGENTS.md as the file every tool shares and put @AGENTS.md at the top of CLAUDE.md, with anything Claude-specific below it. Claude reads the imported file first, then the rest (share one file with other coding tools):

@AGENTS.md
 
## Claude Code
 
Use plan mode for changes under `src/billing/`.

The import never makes Claude read AGENTS.md twice, whichever Project instructions value you use (earlier AGENTS.md workarounds). A CLAUDE.md that only tells Claude in words to read AGENTS.md is weaker: Claude sees the file only if it decides to open it. With nothing Claude-specific to add, ln -s AGENTS.md CLAUDE.md also works (symlink constraints), but Claude's Edit and Write tools refuse to write through the link, and on Windows a committed symlink can check out as a one-line text file. Running /import instead appends a one-time copy of AGENTS.md to CLAUDE.md, on v2.1.213 or later (migrate instructions). Whichever you choose, run /context in the next session and confirm CLAUDE.md is listed under Memory files.

How is this site's repository set up?

It has both files. The first line of the project CLAUDE.md is @AGENTS.md; below it sit the positioning and copy rules for this site. AGENTS.md holds what any coding agent needs in this repository: a warning that its Next.js version has breaking changes, with a pointer to the guides in node_modules/next/dist/docs/, and the rule that project docs live in docs/. Claude Code loads CLAUDE.md with AGENTS.md included through the import, and an agent that reads only AGENTS.md still gets those shared rules, so they are written once.

Personal rules stay out of the repository. My ~/.claude/CLAUDE.md holds how I work in every project: the language I talk in, never commit or push without my explicit approval, no AI attribution in commits. It loads alongside either file and does not stop Claude from reading AGENTS.md. Auto memory adds what Claude learned along the way, one fact per file under a MEMORY.md index, such as running the dev server on port 3100 and never 3000.

What should go in which file?

Put anything another agent would also need in AGENTS.md: commands, layout, conventions. Put what only Claude Code understands below the import in CLAUDE.md, the way the docs' example names plan mode. The docs target under 200 lines per CLAUDE.md file, and an import does not reduce the context cost, because imported files also load at launch (write effective instructions). A rule that must hold every time belongs in neither file. Mine went into scripts/content_lint.py, which fails the run on em dashes, links to removed pages and over-long titles whether or not an agent remembered the rule.

Where to go next

Both files are instructions an agent reads, not checks that run. The step after a good AGENTS.md is a check that runs on its own, which is what Claude Code hooks are for.