[Docs] Replace the prose pointer in CLAUDE.md with an @AGENTS.md import

[zaerl]

Why

CLAUDE.md told Claude Code in words to read AGENTS.md. Claude only sees AGENTS.md that way if it decides to open the file, so the repository's instructions were not guaranteed to be in context at session start. The file also carried a "Claude Code specifics only" bullet about /self-review that repeats what AGENTS.md says under "Where things are", which is the duplication the file's own first paragraph forbids. #526 makes the full case.

What changes

CLAUDE.md becomes the single line @AGENTS.md. Claude Code expands the import at launch, so AGENTS.md is loaded on every version, including the ones that cannot read AGENTS.md natively (before 2.1.277, before 2.1.281 on some backends, with the built-in agents-md plugin off, or the first session after an upgrade). On versions that can, the docs state an imported AGENTS.md is never read twice, whichever "Project instructions" setting a contributor has chosen.

The /self-review bullet is dropped. Its three claims all survive in AGENTS.md and in .claude/skills/self-review/SKILL.md, and Claude Code discovers the skill from its directory without a pointer.

Line 3 of AGENTS.md now describes the import instead of the prose pointer.

Deliberately not done: deleting CLAUDE.md. See the alternatives block.

How to test this

Platforms: any. Current head, no build needed.

There is no user-visible surface. The command that demonstrates it:

Starting state: a fresh Claude Code session started from the repository root on this branch.

1. Run /context.
2. Under Memory files, CLAUDE.md is listed, and its token count is in the thousands rather than the ~200 the old seven-line file loaded, because the imported AGENTS.md is counted with it.
3. Ask Claude what it must do before opening a pull request. It describes running the review in .github/instructions/code-review.instructions.md without first opening any file.

What must not have happened: on Claude Code 2.1.277 or later, /context must not list AGENTS.md a second time on its own line. The import is the only route by which it loads.

Risks and limitations

The behaviour depends on the Claude Code version a contributor runs, and the unit suite has no layer that reads either file, so nothing in CI covers it. The /context check above is the whole verification. The author ran it in a fresh session on this head and confirmed the imported AGENTS.md is counted under Memory files.

Other agents are unaffected: Codex, Copilot, CodeRabbit and the Agent Skills path all reach AGENTS.md or the instructions file directly and never read CLAUDE.md.

Related

Fixes #526

---

Design decisions and alternatives considered

Delete CLAUDE.md entirely. This is what the Claude Code docs offer as the other option, and it works on 2.1.281 or later. Rejected for now: Homebrew releases lag about a week, so contributors on older versions would silently get no project instructions, and any contributor who adds a CLAUDE.local.md for personal notes stops loading AGENTS.md for themselves under the default setting. Revisit once the project can assume a minimum Claude Code version.

Symlink CLAUDE.md to AGENTS.md. Rejected because Git checks a committed symlink out as a plain text file on Windows unless core.symlinks is enabled, leaving Windows clones with a one-line file containing a path. The docs recommend the import over the symlink for exactly this case, and Windows is a primary target here.

Keep a Claude-only section under the import. Nothing currently qualifies. The docs' pattern of an import followed by tool-specific notes is available if something does later.

The @AGENTS.md on line 3 of AGENTS.md is inside backticks on purpose. Imports are expanded inside AGENTS.md too and import parsing skips code spans, so the backticks are what stop that line from importing the file into itself.

Review outcome (required — see AGENTS.md)

0 [fix here] · 0 [follow-up] — no findings across the five dimensions.

Deterministic layer: npm run lint clean, npm test 1646 pass, 0 fail, 2 skipped, run on the working tree before commit.

The judgement pass raised one wording note, that "on every version" overreached, since @path imports are themselves a Claude Code feature. The sentence in AGENTS.md was reworded before commit to say the file loads whether or not Claude can read AGENTS.md on its own.

• Review: completed — fresh Explore subagent context given the diff and .github/instructions/code-review.instructions.md; reviewed the uncommitted working tree against base b3da571 (origin/trunk); no findings
• Since review: uncommitted tree → b664bc9 checked; the only change is the wording fix the review itself asked for on AGENTS.md line 3, verified by reading the diff

Implementation notes

The subagent grepped the repository outside node_modules for CLAUDE, AGENTS.md, self-review and Claude Code. The only remaining CLAUDE references are .gitignore (CLAUDE.local.md, unchanged) and the reworded line in AGENTS.md. The instructions file names AGENTS.md and the skill as its pointers, never CLAUDE.md, so it needs no edit. .coderabbit.yaml, docs/, .agents/ and .claude/ carry no reference to either changed file.

Docs consulted: https://code.claude.com/docs/en/memory#agents-md, in particular "Remove an earlier AGENTS.md workaround" and "Share one file with other coding tools".

Nothing on screen changed, so the screenshots block is omitted.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: WordPress/contributor-toolkit/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 76f4e065-d682-4187-b859-ccba3442243b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}