Skip to content

Claude Code reads AGENTS.md: how to write it and pair it with CLAUDE.md

Update/ 9 min read

Since 2.1.277, Claude Code reads AGENTS.md when there is no CLAUDE.md. What to put in it, how it is read, and how to import it from CLAUDE.md with one line.

  • Claude Code
  • AI
In this article (8)
  1. What AGENTS.md is
  2. What to put in it
  3. How Claude Code reads it
  4. AGENTS.md and CLAUDE.md together: import with @
  5. Keep it short
  6. Common mistakes
  7. Frequently asked questions
  8. Checklist

Since version 2.1.277, published on September 18, 2026, Claude Code reads AGENTS.md when your project has no CLAUDE.md. If you have both, it reads only CLAUDE.md, and from there you can import AGENTS.md with the line @AGENTS.md. That way one instructions file serves several agents.

What each source says, with its date: the spec at agents.md (read November 12, 2026), the release notes for 2.1.277 (September 18, 2026), the Claude Code changelog, which includes 2.1.281 (September 23), and the memory documentation (read November 12). We did not run Claude Code for this: what it does is what its documentation describes. At the end there is a 28-line template and the CLAUDE.md that imports it. To keep CLAUDE.md short, see AI coding agent context.

What AGENTS.md is

Per agents.md, it is "a simple, open format for guiding coding agents", a "README for agents". The README is for people: quick start, project description, how to contribute. AGENTS.md holds what an agent needs and would clutter the README: build steps, tests and conventions. It is plain Markdown: the page answers that there are no required fields and any headings work.

The spec is now stewarded by the Agentic AI Foundation, under the Linux Foundation, and says it emerged from the collaboration of OpenAI Codex, Amp, Jules from Google, Cursor and Factory. Its page showed 23 compatible tools on November 12, among them Aider, Gemini CLI, Windsurf and GitHub Copilot's coding agent, with a link to the full list. Claude Code does not appear on the page: that it reads the file is in its changelog and its documentation, not on agents.md. Two tools are configured with a setting: Aider with read: AGENTS.md in .aider.conf.yml, and Gemini CLI with "context": { "fileName": "AGENTS.md" } in .gemini/settings.json.

In a monorepo you can put another AGENTS.md inside each package: agents read the nearest one in the directory tree, and whatever you ask directly in chat overrides everything.

one AGENTS.md at the root, several agents that read iton the agents.md pageCodexJulesCursorAmpFactory+ 16 more on the pageAGENTS.mdwith one settingAider.aider.conf.ymlread: AGENTS.mdGemini CLI.gemini/settings.jsoncontext.fileNameClaude Code v2.1.277+when there is no CLAUDE.mdplain Markdown, no required fieldsClaude Code is not on agents.md's list; this comes from its changelog

Scroll the figure sideways to see all of it

What to put in it

agents.md suggests sections for a project overview, build and test commands, code style, testing instructions and security, and adds commit or PR guidelines and deployment steps: anything you would tell a new teammate. If you list the test commands, the agent will try to run them and fix failures before finishing. This is the guide's template, for an example store; swap in your own project:

# AGENTS.md

## Project
- Next.js store with the App Router and strict TypeScript.
- Code in `src/`, routes in `src/app/`, tests in `tests/`.

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Tests: `npm test`
- Lint and types: `npm run lint` and `npx tsc --noEmit`

## Code style
- One component per file, in PascalCase.
- Before creating a component, look for a similar one in `src/components/`.
- Do not add dependencies without asking.

## Testing
- Run `npm test` and `npm run lint` before calling a task done.
- If a test fails, fix the code: do not delete or skip the test.

## Security
- Do not read, print or edit `.env*` files.
- Do not run `git push` or deploy.

## Commits and PRs
- Small commits, with the message in the imperative mood.
- In the PR description, list the commands you ran and their results.
  1. # AGENTS.md is just a title; what counts is the file name, not the headings.
  2. ## Project says what it is and where the code lives, so the agent does not explore blind.
  3. ## Commands are the ones the agent will run verbatim; if they are not here, it guesses.
  4. ## Code style holds rules you can check, like looking for a similar component before creating another.
  5. ## Testing defines when a task is done and closes the easy way out of deleting the test.
  6. ## Security lists what it must never do. It is context, not a block.
  7. ## Commits and PRs sets how it hands over the work.

That note on item 6 comes from the Claude Code documentation: instructions are context, not enforced configuration, and to block something for real, like reading a .env, you need a PreToolUse hook. Reviewing an AI agent's changes shows how to enforce a rule with one.

the AGENTS.md template, section by section# AGENTS.md## Projectwhat it is and where code lives## Commandswhat the agent runs, verbatim## Code stylerules you can check## Testingwhen a task counts as done## Securitywhat it must never do## Commits and PRshow it hands over the workconcrete lines the agent can check28-line template · Claude Code suggests under 200 lines per CLAUDE.md

Scroll the figure sideways to see all of it

How Claude Code reads it

Per the memory documentation, Claude Code can read AGENTS.md as your project instructions with no CLAUDE.md, no import and no setting. This is what it reads by default, depending on what your repository has:

Your repository hasClaude Code reads
An AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in your working directory or above itYour AGENTS.md
An AGENTS.md and a CLAUDE.md or CLAUDE.local.md in your working directory or above itYour CLAUDE.md files only
A CLAUDE.md that imports AGENTS.mdYour CLAUDE.md, with AGENTS.md included through the import

Two details that surprise people. First, CLAUDE.local.md counts as a CLAUDE.md: if you add one for your personal preferences in a project that only uses AGENTS.md, Claude stops reading AGENTS.md. Second, your ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md and the files in .claude/rules/ do not count for that check.

At session start, Claude Code loads every AGENTS.md and .claude/AGENTS.md in your directory and the ones above it; in an interactive session you will see a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. A subdirectory's AGENTS.md loads when Claude opens a file there with Read and that subdirectory has no CLAUDE.md of its own. It does not read AGENTS.local.md, AGENTS.override.md or anything under .agents/.

To change the behavior, type /config and set Project instructions: claude-md-or-agents-md (the default), claude-md-and-agents-md (reads both, CLAUDE.md first), claude-md (CLAUDE.md only) or managed-only.

which file Claude Code reads at session startCLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.mdin your directory or above it?noyesreads AGENTS.mdand .claude/AGENTS.mdthe session shows:no CLAUDE.md found;AGENTS.md loaded: …/AGENTS.mddoes your CLAUDE.mdimport @AGENTS.md?yesreads CLAUDE.md+ AGENTS.mdnoCLAUDE.md onlyAGENTS.md skippedthe import works even if Claude does not read AGENTS.md alonedefault Project instructions value: claude-md-or-agents-md

Scroll the figure sideways to see all of it

Updated November 12, 2026: the scope changed after 2.1.277. Version 2.1.281, from September 23, extended support to Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and sessions with telemetry disabled; before that, those sessions read only CLAUDE.md. And the current documentation describes the claude-md-and-agents-md value. If your version is older than 2.1.277, update or use the import in the next section. And if you just upgraded from 2.1.276 or earlier, the documentation says Claude reads it from your next session on.

AGENTS.md and CLAUDE.md together: import with @

If the project already has a CLAUDE.md, or your session cannot read AGENTS.md directly, use an import. The documentation frames it like this: put @AGENTS.md in a CLAUDE.md next to it and write below it whatever is only for Claude Code. Claude reads the imported file first, then the rest:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/checkout/`.
  1. @AGENTS.md, on the first line, imports the file: it is expanded and loaded alongside the CLAUDE.md. The path is relative to the importing file, and imports can chain up to four levels deep.
  2. ## Claude Code opens the part that is only for this tool; what serves every agent stays in AGENTS.md.
  3. The last line is an example of a Claude Code-only instruction. Replace it with yours.

Mind the at sign: import parsing skips code spans and fenced code blocks, so to mention a path without importing it, wrap it in backticks; a bare @README outside them does import the file. An import does not reduce context cost either, because the imported file loads together with the CLAUDE.md. And if Claude already reads AGENTS.md on its own, keeping the import is harmless: the documentation says it never reads it twice.

The alternative is a symlink, ln -s AGENTS.md CLAUDE.md, with two limits from the documentation. The Edit and Write tools refuse to write through the link and ask to edit its target. And on Windows, creating symlinks needs administrator rights or Developer Mode, and Git checks a committed symlink out as plain text unless core.symlinks is on; if anyone on your team uses Windows, use the import. With either one, run /context all in your next session and confirm CLAUDE.md appears under Memory files.

Keep it short

The documentation's guidance targets under 200 lines per CLAUDE.md file: longer ones use more context and reduce adherence. The number is for CLAUDE.md, but AGENTS.md goes into the same context, so applying it there is reasonable (our inference; the page does not say so). The same guidance asks for concrete, checkable instructions ("API handlers live in src/api/handlers/" rather than "keep files organized"), headers and bullets, and nothing contradictory: if two rules clash, Claude may pick one arbitrarily. And agents.md suggests treating the file as living documentation, not something you write once.

Common mistakes

  • Having a CLAUDE.md that does not import AGENTS.md. Claude Code reads only CLAUDE.md and your AGENTS.md is left out.
  • Adding CLAUDE.local.md to a project that only used AGENTS.md. It counts as a CLAUDE.md and switches off the AGENTS.md read; set Project instructions to claude-md-and-agents-md or import the file.
  • Writing "read AGENTS.md" in words inside CLAUDE.md. Claude sees it only if it decides to open the file; use the import.
  • Pasting the same text into both files. They drift apart; keep one and have the other import it.
  • Treating security rules as a block. They are context; to stop something for real, use a hook.

Frequently asked questions

Does Claude Code read AGENTS.md without my doing anything?

Yes, since 2.1.277, if there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. Check your version with claude --version; in an interactive session you will see the notice no CLAUDE.md found; AGENTS.md loaded.

I have both AGENTS.md and CLAUDE.md: which one is read?

By default, only the CLAUDE.md files. AGENTS.md comes in if your CLAUDE.md imports it with @AGENTS.md or if you set Project instructions to claude-md-and-agents-md. For other tools, agents.md says the AGENTS.md closest to the file being edited wins and what you type in chat overrides everything.

Does a symlink work?

It works: ln -s AGENTS.md CLAUDE.md. But the Edit and Write tools do not write through the link, and on Windows it needs special permissions or Developer Mode. On mixed teams, the import is safer.

How long should it be?

The documentation targets under 200 lines per CLAUDE.md; this article's template is 28. If something only matters for one part of the code, the documentation suggests path-scoped rules in .claude/rules/ instead of fattening the file.

Checklist

  • claude --version shows 2.1.277 or later, or you have the import in CLAUDE.md.
  • AGENTS.md sits at the root, in plain Markdown, with commands the agent can run.
  • If there is a CLAUDE.md, its first line is @AGENTS.md.
  • You did not add CLAUDE.local.md to a project that relies only on AGENTS.md.
  • Under 200 lines, no contradictory rules.
  • Anything critical has a hook, not just a line of text.
  • You ran /context all and saw the file under Memory files.

To fine-tune what goes into CLAUDE.md and what stays out, read AI coding agent context. And to turn a line in your instructions into a rule that actually holds, see how to review an agent's changes.

Saw this on Instagram? Comment AGENTS on the Reel and I'll send you the guide.

Written by

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 12, 2026 · updated November 18, 2026

← Blog