CLAUDE.md vs AGENTS.md in the same repo

The SERP already sold the other move. Make them the same bytes with a symlink, or put @AGENTS.md on line one of CLAUDE.md. That is the right fix when both files are supposed to say the same thing.

They are not supposed to say the same thing.

Claude Code's memory docs load CLAUDE.md. Codex and Cursor load AGENTS.md. A photocopied rule still only reaches the tool that opens its own filename.

This walkthrough splits them. CLAUDE.md keeps projectProjectsA Claude Desktop feature giving a persistent workspace its own chat history and knowledge base, so uploaded documents and instructions carry into every chat inside it.See also Artifacts, Quick Entry law. AGENTS.md keeps the agent roster. You leave with both files on disk, two different hashes, and no duplicated rules.

What has to exist first#

A Claude Code session in the repo root. Git, so the before-state is a commit you can roll back. One of the two files already written, usually CLAUDE.md.

• Claude Code 2.1 or later, enough to run /context and see Memory files
• A second tool that actually reads AGENTS.md (Codex, Cursor, or Grok)
• The real agent files, if any, already living under .claude/agents/ or a plugin agents/ folder

No second tool in the mix? Skip AGENTS.md. A file no harnessharnessThe surrounding tooling and control logic that runs a model in a loop, deciding how it reads files, calls tools, and hands off work, separate from the model itself.See also execution subagent, tasks primitive opens is another place for the law to rot.

Claude concatenates every CLAUDE.md from the filesystem root down to the launch directory. Nested copies under the cwd load later, when a file in that subtree is read. Codex walks the other way, root down to cwd, and stops adding files at 32 KiB.

Give each file one job#

A photocopier is not a second filing cabinet. Two reserved spots with the same car parked in both still leave one door without a key.

1. Diff the twins before you edit#

You are looking at two markdown files that already feel interchangeable. That is the smell. Measure it before rewriting anything.

md5sum CLAUDE.md AGENTS.md
diff -u CLAUDE.md AGENTS.md | head

One hash printed twice means the copy tax is already paid. Empty diff is the same news.

forgeforgeA code-hosting platform combining version control with issue tracking, pull requests, and social features, such as GitHub, GitLab, or Codeberg.See also Codeberg-flow printed a68fa1c4f59ff21c68eb48887db8cb7e on both files. 162 lines. 9775 bytes. Commit 136b97c5 on 2026-07-30 had to sync them after AGENTS.md missed the glossary and indexnow verbs and still described pre-flatten category URLs.

That commit is the tutorial's scar. Nothing in CI checked they still agreed. Memory did, until it didn't.

2. Keep project law in CLAUDE.md#

Leave the file Claude actually loads. Layout, bindings, deploy, cache rules, the never git add -A line, flag conventions. Facts a new session has to hold without being asked.

The memory page targets under 200 lines per CLAUDE.md. Longer files eat context and follow less. Size is a different post, fat instruction files. Ownership is this one.

Claude-only machinery stays here too. @imports of architecture notes. Hook reminders. Planplan modeA Claude Code CLI mode that reads files and runs commands to explore a codebase but holds off making any changes until the user approves a proposed plan.See also Shift+Tab cycle, permission modes-mode defaults. Plugin paths that use ${CLAUDE_PLUGIN_ROOT}. Codex will ignore those lines even if you paste them into AGENTS.md.

# rizz.dev

Astro 7 on one Cloudflare Worker. `bun` is the package manager.

## Rules

1. Do not create tests unless asked, and then only under `.tmp/smoke-tests/`.
2. No benchmarks without explicit advance permission.
3. Never `git add -A` here.
4. Before renaming an exported symbol, run LSP findReferences on it.

## Layout

`workers/web/` is the deployable worker. `packages/engine/` is `@rizz/engine`.
Content verbs run from the repo root and write `.tmp/`.

CheckpointcheckpointA saved snapshot of a model's weights at a specific point in training or fine-tuning, the exact file that gets tested, released, or further modified.See also abliteration, frontier model. /context lists CLAUDE.md under Memory files. If it is missing there, Claude cannot see it.

3. Rewrite AGENTS.md as the roster#

The failure being prevented is a second copy of the layout table. AGENTS.md is a README for agents, plain markdown, no required fields. Closest nested file wins for tools that read it.

Put the named workers here. Where their files live. What they own. One pointer so Codex still finds the law.

# Agent roster

Project law lives in `CLAUDE.md`. Follow it. Do not restate it here.

## Named agents

- `blog-legwork` at `.claude/plugins/content-engine/agents/legwork.md`
- `blog-humanizer` at `.claude/plugins/content-engine/agents/blog-humanizer.md`
- Syndication writer, reviewer, humanizer in the same `agents/` folder

## Nested trees

A subdirectory `AGENTS.md` is package-local. HyperFrames law belongs under `videos/<slug>/`, not in this file.

## Other tools

Codex and Cursor load this file natively. They do not load `CLAUDE.md` unless you add a fallback. Grok reads both names.

Skills stay out of both files. A SKILL.md loads on demand. These two files load at session start. Triggering skills is a different walkthrough.

The pointer is an instruction, not a loader. Codex will not open CLAUDE.md unless you add that name to project_doc_fallback_filenames. Cursor stays on AGENTS.md. You'll hit this if the roster is twelve plugin markdown files and AGENTS.md still opens with the same heading as CLAUDE.md.

project_doc_fallback_filenames = ["CLAUDE.md"]

Skip that line if a human on Codex is expected to open CLAUDE.md the way they open a README. Keep it if the law has to ride into an unattended Codex run.

4. Point without importing the roster#

Claude's @path import expands at launch, up to four hops, and dumps the target into context beside CLAUDE.md. That is the documented same-job bridge. Use it when the two files really share one brief.

A roster is not a brief. Importing it makes every session pay for names it does not need yet.

## Agents

Named workers live in `AGENTS.md` and `.claude/plugins/content-engine/agents/`.
Mention `@AGENTS.md` only inside backticks so the import parser leaves it literal.
Do not paste the roster into this file.

Backticks keep a pathPATHThe shell environment variable listing directories searched in order when a command name is typed, so every lookup walks each entry until one matches.See also WSLENV, appendWindowsPath, command lookup literal. Bare @AGENTS.md is an import. Windows also prefers the import over ln -s, because a symlink there needs Administrator or Developer Mode, and an agent that deletes then recreates the file silently turns it back into a regular copy.

5. Prove the split with two hashes#

The 2026-07-30 sync existed because nobody ran this.

md5sum CLAUDE.md AGENTS.md
git grep -n "Never \`git add -A\`" -- CLAUDE.md AGENTS.md

Two hashes. The unique law line hits CLAUDE.md only. A unique roster line hits AGENTS.md only.

If the hashes still match, one of the rewrites did not land. Do not commit the twins again.

When it breaks#

Both files can exist and still fail. The three misses that actually show up.

Claude never saw AGENTS.md#

A clean directory with only AGENTS.md leaves Claude empty. A 2026-08-19 check planted a passphrase in that file and asked Claude Code for it. The reply was 不明. After a CLAUDE.md that imported the file, the passphrase came back.

Fallback lore is leftover. The docs already said there is no fallback. GitHub issue 6235 asked for native AGENTS.md support in August 2025. The documented answer is still the import or the symlink, not a loader change.

Explore skipped the law#

Explore and Plan skip CLAUDE.md on purpose so research stays cheap. Every other built-in and custom subagent loads it. A gotcha that only lives in project law is invisible to those two workers unless the parent prompt repeats it.

A r/ClaudeAI thread asked whether dispatched agents read CLAUDE.md. The parent had the gotcha list. The worker still coded past it.

Nested copies still match#

Root can be clean and a package still ships twins. videos/fat-instruction-files-hurt-coding-agents/ and videos/multi-session-agent-orchestration/ in this repo still share one HyperFrames CLAUDE.md / AGENTS.md hash, four files, same bytes.

Package-local law belongs in that tree's CLAUDE.md. Package-local workers belong in that tree's AGENTS.md. Copying the HyperFrames briefing into both names is the root bug, one directory down.

Codex will also truncate. Combined AGENTS.md files stop at 32 KiB by default. A photocopied 162-line CLAUDE.md plus nested copies can blow that cap while Claude still loads the twin in full. Claude's skip is 4 MiB. Different doors, different locks.

End state#

Both files exist. CLAUDE.md owns project law. AGENTS.md owns the agent roster and a pointer at the law. md5sum prints two hashes. git grep of a unique rule hits one file.

• /context lists CLAUDE.md under Memory files
• Codex or Cursor can summarize AGENTS.md and name the workers
• A unique law line is absent from AGENTS.md
• Nested package files, if any, are not photocopies of the root

The import and the symlink stay on the shelf for teams that truly want one shared brief. Same job, one file, two names. Different jobs, two files, no duplicates. Pick the second one unless the bytes are meant to match. If Codex must follow the law without a human opening CLAUDE.md, add that filename to its fallback list, or put the shared sentences in AGENTS.md and keep Claude-only lines in CLAUDE.md.