One AGENTS.md for every tool

In lesson 3 you learned where Claude Code looks for instructions and how the user, project, and local files stack. This lesson is about the day you open a second tool. Maybe you try Codex for a week. Maybe a contractor uses Cursor. The moment two tools read two different rules files, you have a maintenance problem, and it gets worse quietly. The fix is to keep one file that holds the rules and make every other file a pointer to it.

Why one file, not two

Picture a gutter company in Washington with a small internal app. The owner writes a CLAUDE.md in June: run the tests before every commit, never touch the generated PDF templates, use the staging database for anything destructive. In August a contractor shows up with Codex, which reads AGENTS.md, so the owner copies the file over and renames it. Both tools behave for a month.

Then a rule changes. The staging database moves. The owner updates the file he opens most, which happens to be CLAUDE.md. Codex keeps reading the old address. Nobody notices until the contractor's session runs a cleanup script against a database that no longer exists and, finding nothing, tries the next one it can reach. That is drift: two copies of the same rules that were identical on the day you made them and never again.

Drift is not a tooling bug. It is what happens to any duplicated text that humans maintain by hand. The cure is to stop having two copies: one source of truth, and every tool reads it, directly or through a pointer that contains nothing worth editing.

The file to pick is AGENTS.md. It is the name Codex and Cursor read on their own, it is not tied to any one vendor, and Claude Code's own documentation tells you how to point at it. This site does exactly that: the repo behind the lesson you are reading has an AGENTS.md with the real rules and a CLAUDE.md whose entire contents are the single line @AGENTS.md.

Which tool reads what

Each tool has its own idea of where instructions live. As of September 2026, verified against each vendor's documentation, this is the map for one repo. Tap a layer to see who reads it and what belongs there.

# Rules for this repo
- Run `npm test` before every commit.
- Never edit generated files under `dist/`.
- Use 2-space indentation.

The important asymmetry: Claude Code reads CLAUDE.md, not AGENTS.md. Codex reads AGENTS.md from its global folder and then from the git root down to your working directory, joining the files with blank lines so the closest one comes last. Cursor reads AGENTS.md at the project root and in subfolders without any setup; its .cursor/rules/ folder is for rules that need metadata, such as applying only to certain file paths, and those must be .mdc files. So two of the three tools need nothing from you. Claude Code needs a pointer.

If you are converting an existing setup rather than starting fresh, Claude Code has two helpers. Running /init reads Cursor rules in .cursor/rules/ or .cursorrules and Copilot rules in .github/copilot-instructions.md, and folds the useful parts into the CLAUDE.md it generates. Running /import (Claude Code 2.1.213 or later) copies a supported tool's configuration once, including instruction files like AGENTS.md, MCP servers, commands, subagents, and skills. Both are one-time copies, not links. Use them to migrate, then set up the pointer so you never copy again.

Import or symlink

There are two ways to make CLAUDE.md read AGENTS.md, and the Claude Code docs describe both.

The import. Create a CLAUDE.md whose first line is @AGENTS.md. The @path syntax is an import: Claude Code expands the named file into context at session start, right where the line sits. Relative paths resolve from the file that contains the import, not from the folder you launched in. You can add Claude-only lines below it, and the docs' own example does exactly that: the import, then a heading, then "use plan mode for changes under src/billing/." Claude reads the shared rules first and the extra lines after.

The symlink. A symlink is a filesystem alias: a name that points at another file so that opening one opens the other. Run this in the repo root:

ln -s AGENTS.md CLAUDE.md

It prints nothing on success. Now there is literally one file on disk, and Claude Code sees it under the name it wants. The cost is that you cannot add Claude-only lines, because there is no second file to put them in.

Which to choose: use the import by default. It costs one line, it survives being committed to git on any platform, and it leaves you a place for tool-specific notes when you eventually need one. Use the symlink only when you are certain the two files should be byte-for-byte identical forever. There is one hard rule on top of that preference: on Windows, creating a symlink requires Administrator privileges or Developer Mode, so the docs tell Windows users to use the @AGENTS.md import instead. If anyone on the team is on Windows, the import is the only choice that works for everyone who clones the repo.

The machine file pattern

The project pointer handles one repo. The site owner's setup goes one level up and applies the same idea to the user-level file, the one Claude Code loads for every project on the machine. Here is the structure on his laptop, verified the day this was written. The contents of the rules are private; the shape is the lesson.

• One rules file, in git. The master rules live in a repo he maintains for his whole fleet of machines, at a path like claude-fleet/claude/AGENTS.md. It is versioned, diffable, and the same on every computer that pulls the repo.
• A per-machine file that imports it. The same repo has a machines/ folder with one markdown file per computer. His laptop file begins with the line @../AGENTS.md, so the shared rules load first, and then the file continues with notes that only apply to that machine: which repos live there, which tools are installed, what this box is allowed to touch.
• The user CLAUDE.md is a symlink to the machine file. ~/.claude/CLAUDE.md is not a real file. It points at claude-fleet/claude/machines/laptop.md. Claude Code follows the link, reads the import, and ends up with shared rules plus laptop notes. A second computer symlinks to its own machine file and gets shared rules plus its own notes.
• Codex gets the same shared file. ~/.codex/AGENTS.md is a symlink to a file in the home folder, which is itself a symlink to the same claude-fleet/claude/AGENTS.md. Codex's global rules are therefore the identical bytes Claude Code imports.
• Every project CLAUDE.md is one line. @AGENTS.md, nothing else. Project rules live in the project's AGENTS.md, where Codex and Cursor read them directly.

One detail in that chain is worth noticing. The import line says @../AGENTS.md, one folder up. If imports resolved from ~/.claude/, that would point at the home folder. It works because imports resolve relative to the file that contains them, and that file is the real one inside the fleet repo, not the symlink name. That rule is what lets the whole structure live in one git repo.

One caveat from the Claude Code docs, as of September 2026: in Cowork desktop sessions, a ~/.claude/CLAUDE.md that is itself a symlink is skipped, along with user-scope imports that point outside the session's working directory. In a normal terminal session the symlinked user file loads as described. If you use Cowork, put a real file at ~/.claude/CLAUDE.md and import from it instead.

Skills shared the same way

A skill is a folder with a SKILL.md file that a tool loads only when the task calls for it. Lesson 5 covers writing them. The point here is that both Claude Code and Codex look for skills in a folder under your home directory, and on the site owner's machine both folders point into one tree by symlink. That canonical tree, claude-fleet/claude/skills, is checked into the same fleet repo as the rules.

On his machine ~/.claude/skills is a symlink to that tree. ~/.codex/skills is a folder of symlinks, one per skill, each pointing into the same tree. Edit a skill once, commit, and both tools see the change on every computer that pulls. The Codex documentation, as of September 2026, also lists ~/.agents/skills and a repo-level .agents/skills as places it scans, so check which folders your installed version reads before you link. The principle does not change: one tree, links everywhere else, never a copy.

What stays tool-specific, and why

Not everything should be shared, and it helps to know the line. Rules are prose that a model reads and tries to follow. Everything below is configuration: values a program enforces whether or not the model agrees. Configuration has a different schema in every tool, and it often names things that only exist in that tool.

• Settings files. Claude Code reads ~/.claude/settings.json and the project's .claude/settings.json. Codex reads ~/.codex/config.toml. Different formats, different keys. A permission rule that blocks a command in one is meaningless text to the other.
• Permission modes. Claude Code's modes, covered in lesson 2, are a Claude Code feature with Claude Code names. Writing "use plan mode" in a shared AGENTS.md just confuses Codex. That is the kind of line that belongs under the import in CLAUDE.md.
• MCP server config. Each tool has its own file for the servers it connects to, and often its own secrets handling. Keep those per tool. Lesson 7 covers Claude Code's.
• Hooks. Shell commands a tool runs at fixed moments are wired in that tool's settings. The docs are explicit that instructions are context, not enforcement; if something must happen every time, it is a hook, and hooks are per tool.

A good test for any line: could a tool that has never heard of Claude Code act on this sentence? "Run the tests before you commit" passes. "Prefer acceptEdits mode" fails. The first goes in AGENTS.md. The second goes under the import.

Try this yourself

Pick a repo you already use with Claude Code, on a laptop, and do this in order. It takes one file and one line.

1. If the repo has a CLAUDE.md with real rules in it, rename it to AGENTS.md. If it has neither, create AGENTS.md with three rules you actually want followed.
2. Create a new CLAUDE.md whose contents are exactly this:

@AGENTS.md

3. Start Claude Code in the repo and run /context. Look under Memory files. You should see CLAUDE.md listed for this project, and if you have a user-level ~/.claude/CLAUDE.md you will see that too. Ask Claude to state the three rules back to you to prove they arrived.
4. Open Codex in the same folder and ask it the same question. It will have read AGENTS.md on its own, with nothing extra from you. Now change one rule in AGENTS.md, restart both tools, and ask again. Both should report the new rule, because there was only ever one place to change it.

If step 3 does not show CLAUDE.md under Memory files, check that you started Claude Code in the repo folder or one of its subfolders, and that the import is not wrapped in backticks. The docs note that import parsing skips code spans, so `@AGENTS.md` in backticks is literal text, not an import.