Claude Code AGENTS.md support for shared project instructions

For information about the service, see the Ailoot documentation.

What changes when you use Claude Code, Codex, and Cursor together?#

In the example described, Claude Code is the main tool, while Codex and Cursor are used for specific tasks. My CLAUDE.md has about 250 lines of instructions: what to read and in what order, what must not be touched, which commands to use for deployment, and the commit formatting rules. When I first tried Codex CLI on the project, it didn’t know any of the rules: it ran git push --force, poked around in .env, and renamed files carelessly.

I first copied CLAUDE.md to AGENTS.md by hand. Two weeks later, I discovered that the project already had four versions of the same instruction: in CLAUDE.md, AGENTS.md, .cursorrules, and .windsurf/rules/. They all differed a little. This is not a Claude or Cursor problem; it is the basic trap of any system with multiple sources of truth. I discuss this problem in more detail in the guide to multi-agent work.

In June 2026, Anthropic’s Claude Code memory documentation gave one answer: a shared file plus an import. Since September 2026, Claude Code has read AGENTS.md itself if the project has no CLAUDE.md, and an import is needed when you have rules specifically for Claude. Below, I explain when a single AGENTS.md is enough, how to set up an import, and how to separate shared rules from Claude-specific ones.

Does Claude Code read AGENTS.md itself?#

Before September 2026, the answer was “no.” Issue #6235, which requested support for AGENTS.md, had been open since August 2025 and was closed on August 17, 2026. The memory documentation pointed to one solution all that time: create a CLAUDE.md and include AGENTS.md in it as an import. Starting with version 2.1.277, the documentation says something different:

Exactly what Claude Code reads depends on which files are in the project:

For this check, CLAUDE.md, .claude/CLAUDE.md, and CLAUDE.local.md in the working directory and any directory above it count. A personal ~/.claude/CLAUDE.md, a corporate managed file, and rules from .claude/rules/ do not count: they are loaded alongside AGENTS.md.

When there is no CLAUDE.md, Claude Code reads all AGENTS.md and .claude/AGENTS.md files in the working directory and above it at startup, and picks up an AGENTS.md in a subdirectory when it opens a file in that subdirectory. @path imports inside AGENTS.md also work. Claude Code does not read AGENTS.local.md, AGENTS.override.md, or the contents of the .agents/ directory.

The catch: a personal CLAUDE.local.md counts too. Create one to keep your uncommitted rules, and Claude Code will silently stop reading AGENTS.md. The setting below is the solution.

The behavior changes in /config, under Project instructions:

If you want to keep CLAUDE.local.md without losing AGENTS.md, set claude-md-and-agents-md. There will be no duplicate reading: if AGENTS.md is already included through the @AGENTS.md line or a symbolic link, Claude Code does not load it a second time, regardless of the setting.

You can check whether the file was picked up with the /memory command: starting with version 2.1.280, the path to AGENTS.md appears in the list. On versions before 2.1.277 and in sessions where the built-in agents-md plugin is disabled, Claude Code reads only CLAUDE.md, and there is no Project instructions item in /config. Before version 2.1.281, sessions through Amazon Bedrock and sessions with telemetry disabled behaved the same way. In the first session after updating from an older version, AGENTS.md may also not be picked up; it works from the next session onward.

What does this mean for a setup with one file? If you have no rules just for Claude, you can skip CLAUDE.md: AGENTS.md is enough, and Claude Code, Codex, and Cursor will read it. If you do have such rules (plan mode for risky directories, skills, hooks), you need CLAUDE.md, and Claude Code will stop reading AGENTS.md by itself. Then include AGENTS.md inside CLAUDE.md with the line @AGENTS.md; this setup works just as it did before September. It also helps with older Claude Code versions. I explain it in detail below.

How do you import @AGENTS.md inside CLAUDE.md?#

A minimal working example from the official documentation:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Here is what happens. The first line, @AGENTS.md, is an import directive. When Claude Code parses CLAUDE.md at the start of a session, it finds this import and inserts the entire contents of AGENTS.md in its place. Next comes the ## Claude Code heading: it is just markdown, but it acts as a “Claude-specific additions” section. Under it is a rule that applies only to Claude Code: use plan mode for changes in the billing directory. Codex CLI or Cursor does not open this file at all; they use the plain AGENTS.md.

A quote from the documentation about how imports work:

A few practical details:

• Relative and absolute paths. @AGENTS.md is relative to the file containing the import. @/Users/me/shared/rules.md or @~/.claude/personal.md are absolute. I use @~/.claude/personal.md for personal preferences I don’t want to put in the repo.
• Four-hop depth. AGENTS.md can import @docs/coding-style.md, and coding-style.md can import something else, up to four levels. That is enough for any real structure.
• Backticks block imports. If the text says `@README`, that is just a mention of the name, not an import. This is useful when explaining to readers how imports work without triggering one.
• Approval for files outside the project. If an import points outside the working directory, as in @~/.claude/personal.md, Claude Code shows a dialog listing those files the first time. If you decline, external imports stay disabled and the dialog is not shown again. @AGENTS.md at the project root does not trigger a dialog. This protects you from accidentally loading an unrelated file into context.

After I switched to this setup in the project described, my CLAUDE.md shrank from 250 lines to 60: @AGENTS.md plus five to seven rules that apply only to Claude Code (plan mode for risky directories, what not to touch in the admin area, and how to phrase commits). Everything shared lives in AGENTS.md, which Codex and Cursor read.

When should you choose a symlink, and when an import?#

The documentation shows the symlink option like this:

ln -s AGENTS.md CLAUDE.md

And it immediately gives a frank warning about Windows:

Comparison table:

I use imports in the project described. Reasons:

1. The team is mixed. I’m on Mac; in the example, the team is split roughly evenly between Windows and Mac. If a symlink appears in the repo, for Windows users without Developer Mode it will be checked out as an ordinary text file containing a single line, AGENTS.md. This causes strange bugs: sometimes the rules work, sometimes they don’t, and it’s unclear why.
2. I want Claude-only rules. Under @AGENTS.md, my CLAUDE.md has a “Claude Code” section with rules: use --effort high for architecture tasks, run npm run build before git push, and don’t call /api/v1/deploy by hand. Codex does not understand these commands.
3. It is easier to debug. When something goes wrong, I open CLAUDE.md and see the import and my overrides. A symlink has no “this was added here.” For more about debugging Claude Code settings, see the safe mode guide.

If you have no Claude-specific rules, a symlink is no longer needed starting with version 2.1.277: delete CLAUDE.md, and Claude Code will read AGENTS.md itself. Keep the symlink only if someone on the team is on a version older than 2.1.277 and cannot update. If you have Claude-specific rules, an import is more convenient in nine cases out of ten.

What do Codex, Cursor, Copilot, Windsurf, and Gemini CLI read?#

A map of the seven main tools (based on each tool’s official documentation):

What follows from this? If a repo has AGENTS.md (plus a CLAUDE.md with an import when Claude-specific rules are needed), five of the seven tools get fresh instructions automatically. Cursor and Windsurf, which have native files of their own, can either be left as they are (AGENTS.md is also read by them) or can have an @AGENTS.md import added—but their syntax differs and is not always supported.

The simplest strategy for a new project:

1. Put all shared rules in AGENTS.md—95% of the rules belong there.
2. Create CLAUDE.md if you need rules just for Claude: put @AGENTS.md on the first line, then add a section with Claude-only rules below. If there are no such rules, CLAUDE.md is unnecessary; Claude Code has read AGENTS.md itself since version 2.1.277.
3. Keep .cursor/rules/ for Cursor for rare cases when something Cursor-specific is needed (its @Codebase and @Docs commands).
4. For Windsurf, do the same: forget the old .windsurfrules; use the new .windsurf/rules/ only when patterns for its syntax are needed.

This approach gets you 80% of the benefit for 20% of the work. In my experience, maintaining more than two sources of truth (shared plus Claude-only) becomes painful. If someone on the team adds a rule to .cursorrules and forgets AGENTS.md, a week later Cursor and Codex will disagree with each other.

How does /init in Claude Code pick up an existing AGENTS.md?#

Anthropic describes /init this way in its documentation:

What does this mean in practice? The repo I described had a .cursorrules from when I tried Cursor (about 80 lines), and an AGENTS.md (120 lines, assembled by hand). When I ran claude /init, the command took both files, deduplicated similar rules, and assembled a clean CLAUDE.md in a minute. I checked it afterward and made light edits—removed outdated items and added a structure with headings. It was faster than rewriting from scratch.

The interactive mode, in which /init also reads AGENTS.md, is enabled through an environment variable:

CLAUDE_CODE_NEW_INIT=1 claude

After /init starts, Claude asks a series of clarifying questions: which artifacts to configure (CLAUDE.md, skills, hooks), what stack the project uses, and which commands to use for tests. Then a subagent explores the codebase—reading package.json, README.md, and configuration files—and fills in missing parts. At the end, it shows a proposal that you can edit before saving. For more on configuring Claude Code when starting a project, see the separate guide.

Now for the downside. If the project already has an active AGENTS.md, /init will create a CLAUDE.md alongside it containing a copy of its rules. From that point on, Claude Code reads only CLAUDE.md by default, so there are two sources of truth again: you update AGENTS.md, while Claude continues to work from the old copy. The /import command does something similar: it appends a one-time copy of AGENTS.md to CLAUDE.md. To keep a single source, put the @AGENTS.md import on the first line of CLAUDE.md after /init, and remove anything from CLAUDE.md that repeats AGENTS.md.

/init is the right starting point for a new project or one you are moving over from Cursor or Copilot. There is no need to search online for the “best CLAUDE.md template”—Anthropic already takes what is in the repo into account. If the project already has an active AGENTS.md and there are no Claude-only rules, /init is unnecessary: Claude Code will read AGENTS.md itself.

How do you separate shared and Claude-specific instructions?#

I separate them by this principle. Shared rules that go in AGENTS.md:

• What not to touch in the code. The .env, node_modules, prisma/migrations folders (only through prisma migrate), .next/, .git/.
• How to name things. Branches: feat/, fix/, chore/. Commits: feat:, fix:, docs: prefixes plus a short description. Component files in kebab-case.
• Test/lint commands. npm run build, npm run lint, npm test. Which command to run before git push.
• Architectural principles. What goes in src/lib/, what goes in src/components/, where business logic lives, and where the UI lives.
• Security. Never commit secrets. Access the production database only through prod-psql. Access production over SSH only through the prod alias, not root@IP.

Claude-specific rules that go in CLAUDE.md (below @AGENTS.md):

• Plan mode. Use plan mode for changes in risky directories (for example, src/billing/).
• Effort level. Use --effort high for architecture tasks and medium for routine work.
• Skills. Which AI agents and skills to run in which situations. For example: “when working on a guide, run the build-guide skill.”
• Claude memory. What to put in auto memory and what to put in CLAUDE.local.md. For more about Claude memory, see the guide to Memory and CLAUDE.md.
• Hooks. If .claude/settings.json has hooks configured, describe in CLAUDE.md what they do (Codex and Cursor do not know about them, and do not need to).
• Skills and commands. A list of slash commands I often use (/init, /cd, /memory, /plan).

The boundary is not always clear. For example, “never run git push --force to main” is clearly shared, so it goes in AGENTS.md. But “when running git push to a hot branch, use plan mode first” is specific to Claude Code, so it goes in CLAUDE.md. The test: “If I removed Claude Code tomorrow and kept only Codex, would this rule still apply?” If yes, put it in AGENTS.md. If no, put it in CLAUDE.md.

What belongs in AGENTS.md, and what belongs in CLAUDE.md or .claude/rules?#

If the rules exceed 200 lines, it is time to split them up. Anthropic’s documentation recommends aiming for 200 lines per file, because long CLAUDE.md files start to silently lose adherence: Claude seems to read them but follows them less often.

A structure for a large project that works for me:

my-project/
├── AGENTS.md                    # 100-150 lines, shared
├── CLAUDE.md                    # 30-50 lines: @AGENTS.md + Claude-only
└── .claude/
    ├── CLAUDE.md                # alternative to root file, same file
    └── rules/
        ├── api.md               # with paths: ['src/api/**']
        ├── components.md        # with paths: ['src/components/**']
        ├── testing.md           # without paths, always active
        └── security.md          # without paths, always active

Each file in .claude/rules/ can have frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required

Claude loads these rules only when working with files matching this pattern. If it touches src/components/Button.tsx, the API rules are not added to the context. This way, the context window is spent only on what is relevant. The .claude/rules/ directory also works without CLAUDE.md: if the project contains only AGENTS.md, its rules are loaded alongside it and do not disable direct reading of AGENTS.md.

Cursor and Windsurf support the same approach through their .cursor/rules/ and .windsurf/rules/ directories. The AGENTS.md standard can refer to these directories, but cross-tool syntax is not fully stable yet. It is safer to keep shared rules in AGENTS.md and duplicate path-scoped rules in .claude/rules/ and .cursor/rules/—these are rare specific cases, not the bulk of the rules.

Useful locations for CLAUDE.md (ordered from broadest to narrowest):

An example ~/.claude/CLAUDE.md might contain two rules: “respond in the user’s preferred language” and “spell Ailoot exactly this way.” These rules apply to every project, so there is no need to duplicate them in each repository.

Of these four levels, only a project-level CLAUDE.md and CLAUDE.local.md disable direct reading of AGENTS.md. A personal ~/.claude/CLAUDE.md and managed policy do not get in the way; Claude Code reads them alongside AGENTS.md.

What should you do if AGENTS.md is already outdated in your project?#

In the project I described, I had an AGENTS.md from May 2025—180 lines, many of them outdated (it mentioned Anthropic API endpoints that had changed since then; examples with claude --tools syntax that no longer exists; and rules about ~/.claude/projects/ with an outdated structure).

The plan I used to update it:

1. Review it with claude in plan mode. I open the repo, run claude --safe-mode, and ask: “Reread AGENTS.md and suggest a list of items that are outdated or repeated. Don’t edit it; list them only.” In two minutes, I got a list of 23 items to review.
2. Remove obviously obsolete items. Of the 23 items, 9 were clearly outdated—command syntax, endpoints, and flag names. I deleted those lines.
3. Combine duplicates. Another 6 items repeated each other in different wording (“don’t force-push,” “never use --force,” “avoid git push -f”). I combined them into one line.
4. Add new items. I added what I noticed Claude/Codex had been getting wrong regularly over the past month, following the rule “one line per error pattern.” That resulted in 8 new items.
5. Run a subagent for a final review. I requested a Claude review with the instruction “find contradictions, ambiguities, and duplicates.” It found three phrasings that could be made clearer. I fixed them.

After an hour, AGENTS.md was 110 lines long, up to date, and I knew every line personally. It was easy to build a 30-line CLAUDE.md from it. Codex also became noticeably more careful about tests afterward—I suspect some of its “strange” decisions came from outdated instructions that it had been following in good faith.

The main principles for a living AGENTS.md:

• Every rule answers a recurring mistake. If I did not think of a rule once during the month, there is no point in keeping it.
• Write rules as commands, not theory. “Use two spaces” is a rule. “Code style should be neat” is not.
• Specifics beat generalities. “Run npm run build before git push” is a rule. “Test your changes” is not.

What definitely DOES NOT work with this setup?#

A few things I learned the hard way during six months of working with this setup:

1. Cursor autocomplete does not use AGENTS.md. When Cursor suggests completing a line in the editor, it does not read AGENTS.md in real time—there is a separate fast engine at work. Rules in AGENTS.md matter only when you make a chat request inside Cursor. This means that writing “don’t use var, use const” in AGENTS.md will not affect autocomplete; you need to configure this through ESLint or the TypeScript config.

2. Claude Code hooks in AGENTS.md do not work for Codex. If .claude/settings.json has a PreToolUse hook configured to block a certain action, this information is useful only to Claude. Codex does not know about hooks; to it, this is “the tool decides for itself.” It makes sense to write “don’t do X” in AGENTS.md, and “there is a hook that physically blocks X” in CLAUDE.md below the import.

3. Copilot and .github/copilot-instructions.md. GitHub Copilot reads its own file and still does not read AGENTS.md very well. If your team actively uses Copilot, either add a separate .github/copilot-instructions.md with a shortened version of the rules, or use Copilot Extensions that know about AGENTS.md. This is changing rapidly, so the picture may be different in three to six months.

4. Git does not track a symlink as a CLAUDE.md change. If you run ln -s AGENTS.md CLAUDE.md and update AGENTS.md a week later, Git will show a diff only for AGENTS.md. That is normal, but a colleague reviewing the PR may not realize that CLAUDE.md has also been updated (through the symbolic link). Solution: explicitly write in the PR description, “updated AGENTS.md; Claude Code sees the same file through the symlink.”

5. Deep imports are hard to debug. If AGENTS.md imports @docs/coding-style.md, which imports @docs/typescript.md, and some rule conflicts with another, debugging is difficult. I keep imports to one level (CLAUDE.md → AGENTS.md) and do not nest further. Anthropic provides an InstructionsLoaded hook that logs which files were loaded—useful for debugging layered setups. Note: the hook fires for AGENTS.md included through an import or symlink, but not for AGENTS.md that Claude Code read itself.

Get to know Ailoot.