# Claude Code AGENTS.md support for shared project instructions
> Create a Claude Code AGENTS.md file, choose a Claude Code AGENTS.md symlink or import, and share rules with Codex and Cursor.
Source: https://ailoot.ai/blog/en/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/en/agents-md-claude-md-one-instruction-file/
Language: en
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-b166b786813322849380f57b7489578bccf5e512b71029ab46fc291be816fd62
For information about the service, see the [Ailoot documentation](https://ailoot.ai/docs/).
## What changes when you use Claude Code, Codex, and Cursor together?
Key takeaway
In 2026, a typical vibe coder’s setup is not one tool, but 3–5. Claude Code as the main tool, Codex for long autonomous tasks, Cursor for quick edits in the IDE. Each has its own instruction file: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. If you keep them synchronized manually, you edit one line in five places, forget to update Cursor, and a week later Claude and Codex give different results for the same prompt.
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](https://ailoot.ai/blog/en/claude-code-codex-together/).
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?
Key takeaway
Yes, starting with version 2.1.277, released on September 18, 2026, but only if there is no `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` in the working directory or above it. If `CLAUDE.md` exists, Claude Code reads only that file by default, and `AGENTS.md` is included with the line `@AGENTS.md` inside `CLAUDE.md` or with a symbolic link. The behavior changes in `/config`, under Project instructions. Before September, Claude Code did not read `AGENTS.md` at all, and importing it was the only way.
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:
Claude Code can read AGENTS.md as project instructions, so a repository already set up for other agents works without CLAUDE.md, an import, or configuration.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
Exactly what Claude Code reads depends on which files are in the project:
| Files in the project | What Claude Code reads |
|----|----|
| `AGENTS.md`, with no `CLAUDE.md` or `CLAUDE.local.md` in the working directory or above it | `AGENTS.md` |
| `AGENTS.md` and `CLAUDE.md` (or `CLAUDE.local.md`) in the working directory or above it | Only `CLAUDE.md` |
| `CLAUDE.md` with the line `@AGENTS.md` | `CLAUDE.md`, and `AGENTS.md` inside it through the import |
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:
| Setting | What Claude Code reads |
|----|----|
| `claude-md-or-agents-md` (default) | `CLAUDE.md`, or, if neither it nor `CLAUDE.local.md` exists, `AGENTS.md` |
| `claude-md-and-agents-md` | Both files: in each directory, `CLAUDE.md` first, then `AGENTS.md` |
| `claude-md` | Only `CLAUDE.md` |
| `managed-only` | Only the corporate managed `CLAUDE.md` and auto memory |
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?
Key takeaway
An import is needed when the project has a `CLAUDE.md`: with one present, Claude Code does not read `AGENTS.md` itself by default. To set it up, write the line `@AGENTS.md` at the top of the `CLAUDE.md` file. When Claude Code starts a session, it inserts the contents of `AGENTS.md` in place of that line and reads the result as a single text. Below the import, you can add a “Claude Code” section with rules that apply only to Claude. Imports work with relative and absolute paths, and can be nested up to four levels deep.
A minimal working example from the official documentation:
```markdown
@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:
CLAUDE.md files can import additional files using the @path/to/import syntax. Imported files are expanded and loaded into context at session startup along with the CLAUDE.md that references them.
— Anthropic, https://code.claude.com/docs/en/memory
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?
Key takeaway
Anthropic offers two mechanisms: an import through `@AGENTS.md` or a symbolic link, `ln -s AGENTS.md CLAUDE.md`. A symlink is simpler—it is just an alias and requires no file changes. But it has three drawbacks: Windows requires administrator privileges, you cannot add Claude-specific rules to `CLAUDE.md`, and Git sometimes shows a symlink as junk in the diff. Importing is the universal approach. If you have no rules just for Claude, then starting with version 2.1.277 you need neither: Claude Code will read `AGENTS.md` itself.
The documentation shows the symlink option like this:
```bash
ln -s AGENTS.md CLAUDE.md
```
And it immediately gives a frank warning about Windows:
If you or anyone cloning the repository works on Windows, use the @AGENTS.md import. Creating a symbolic link there requires administrator privileges or Developer Mode, and Git without core.symlinks enabled checks out a committed link as an ordinary text file, leaving a one-line CLAUDE.md instead of the instructions in that copy.
— Anthropic, https://code.claude.com/docs/en/memory
Comparison table:
| Criterion | `@AGENTS.md` import | Symlink `ln -s` |
|----|----|----|
| **Works on Windows without admin privileges** | yes | no (Developer Mode required) |
| **Can add rules only for Claude** | yes, below the import | no, the file is identical |
| **Appears in Git as ordinary markdown** | yes | as a link (depends on `core.symlinks`) |
| **Can import multiple files** | yes, up to four hops | no, one-to-one |
| **Caching/invalidation in Claude Code** | standard for CLAUDE.md | works, but symlinks have meta pitfalls |
| **Default choice** | suitable for everyone | only if cross-platform use doesn’t matter |
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](https://ailoot.ai/blog/en/claude-code-safe-mode-recovery/).
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?
Key takeaway
Each tool reads its own file, sometimes more than one. Claude Code reads `CLAUDE.md`, and since September 2026 also reads `AGENTS.md` if the project has no `CLAUDE.md`. Codex CLI reads `AGENTS.md` plus `AGENTS.override.md`. Cursor reads the older `.cursorrules` format or the newer `.cursor/rules/*.mdc`, and since summer 2026 it also reads `AGENTS.md`. Copilot reads `.github/copilot-instructions.md` or `.github/instructions/*.instructions.md`. Windsurf reads the older `.windsurfrules` or the newer `.windsurf/rules/`. Gemini CLI reads `GEMINI.md`. Aider and Cline have already adopted `AGENTS.md`.
A map of the seven main tools (based on each tool’s official documentation):
| Tool | Main instruction file | Alternatives | Reads AGENTS.md? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, managed policy | yes, if the project has no `CLAUDE.md` (since 2.1.277), otherwise through an import |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | yes (native) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (deprecated) | yes |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | through extensions |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (deprecated) | yes |
| **Gemini CLI** | `GEMINI.md` | \- | no |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | yes (native) |
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?
Key takeaway
`/init` builds a `CLAUDE.md` from what is already in the repo and saves 20–30 minutes of manual work. By default, it picks up Cursor rules (`.cursor/rules/`, `.cursorrules`) and Copilot rules (`.github/copilot-instructions.md`), while it reads `AGENTS.md`, `.windsurfrules`, and `.clinerules` in `CLAUDE_CODE_NEW_INIT=1` mode. This same mode starts an interactive, multi-phase flow: it asks questions, explores the code through a subagent, and proposes a plan before writing. Since September 2026, `/init` has a downside in a project with `AGENTS.md`: a new `CLAUDE.md` disables direct reading of `AGENTS.md`, and the rules end up in two files.
Anthropic describes `/init` this way in its documentation:
Running /init reads other tools’ instruction files and moves relevant parts into the generated CLAUDE.md: Cursor rules from .cursor/rules/ or .cursorrules, Copilot rules from .github/copilot-instructions.md, and, with CLAUDE_CODE_NEW_INIT=1, also AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules.
— Anthropic, https://code.claude.com/docs/en/memory
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:
```bash
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](https://ailoot.ai/blog/en/spec-kit-claude-code-spec-driven-development/).
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?
Key takeaway
Put rules that any AI agent can understand in `AGENTS.md`: what not to touch, how to name branches, that `.env` contains a secret, and which commands to use for tests. Put rules specific to Claude Code in `CLAUDE.md` (below the import): plan mode, skills, hooks, skill references, and model names by version. The distinction is simple: if a rule begins “Claude should,” it belongs in `CLAUDE.md`. If it begins “the tool should,” it belongs in `AGENTS.md`.
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](https://ailoot.ai/blog/en/claude-memory-claude-md-auto-memory/).
- **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?
Key takeaway
For a large project, one `AGENTS.md` is not enough—it grows too large, and every agent brings unnecessary material into its context. The solution is a `.claude/rules/` directory with separate files by topic and YAML frontmatter `paths:` for path-based triggers. For example, an API rule applies only when Claude works in `src/api/`. This saves a lot of context window space. The equivalent for Cursor is `.cursor/rules/`, and for Windsurf it is `.windsurf/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:
```markdown
---
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):
| Level | Location | Purpose |
|----|----|----|
| **Managed policy** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Corporate rules, IT/DevOps |
| **User** | `~/.claude/CLAUDE.md` | Personal preferences across all projects |
| **Project** | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Project team rules |
| **Local** | `./CLAUDE.local.md` (in `.gitignore`) | Personal preferences for a specific project |
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?
Key takeaway
If `AGENTS.md` was assembled back in 2025 for Codex or Aider and has not been edited since, open the project in Claude Code and ask Claude to edit the file. AGENTS.md is a living document; the Linux Foundation specification is updated. The main rule for keeping it current: every rule must answer “What am I tired of repeating to Claude/Codex?” If it does not, archive it.
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?
Key takeaway
Importing `@AGENTS.md` does not make different tools behave as one. Each has its own quirks: Codex CLI does not know about `.claude/rules/` or hooks. Cursor has its own autocomplete engine, which does not read CLAUDE.md while completing text. Copilot follows `.github/copilot-instructions.md`, and rules in AGENTS.md alone are not enough for it. This is not “one file = one behavior”; it is “one source for the baseline rules, then each tool has its own additions.”
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](https://github.com/marketplace?type=apps&category=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.
### Sources
- [Claude Code Memory documentation - AGENTS.md section](https://code.claude.com/docs/en/memory#agents-md) - when Claude Code reads AGENTS.md itself, Project instructions settings, imports and symlinks, and `/init` behavior.
- [Claude Code Memory documentation - importing additional files](https://code.claude.com/docs/en/memory#import-additional-files) - `@path/to/file` syntax, four-hop depth, relative and absolute paths.
- [agents.md - Linux Foundation standard](https://agents.md/) - official AGENTS.md standard and list of supporting tools.
- [Cursor Rules Documentation](https://docs.cursor.com/context/rules-for-ai) - what Cursor reads (`.cursor/rules/*.mdc`, AGENTS.md).
- [GitHub Copilot Custom Instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) - `.github/copilot-instructions.md` format.
- [AGENTS.md specification at the Linux Foundation](https://aaif.io/projects/agents-md/) - living specification.
Get to know [Ailoot](https://ailoot.ai/).
## Questions about One Instruction File for Claude Code, Codex, and Cursor in 2026
### When should I use an import instead of a symlink?
Use `@AGENTS.md` in `CLAUDE.md` when you need Claude-specific additions or teammates use Windows. A symlink makes both names refer to the same content, so it cannot hold a separate Claude-only section.
### How can I check that shared instructions were loaded?
Run `/memory` and check the listed instruction files. If `CLAUDE.md` or `CLAUDE.local.md` suppresses direct AGENTS.md loading in your configuration, add the import or choose the setting that loads both, then start a fresh session.
## Ailoot · The company and its project portfolio
Ailoot combines established operating experience, a large client base, stable service and ongoing KPI control.
The company and its project portfolio: millions of customers; monthly sales in the billions.
Ailoot brings that operating experience to API access for AI features in customer products, agents, applications and automations.