Claude Code reads CLAUDE.md, most other agents read AGENTS.md: let one import the other

Keep the instructions in AGENTS.md and make CLAUDE.md a single line that imports it. And grep your global instructions before you rename anything, because a renamed file they point at breaks every session without an error.

My notes repo carries a contract that tells an AI coding agent how to file what it learns: where entries go, what format they take, how to commit. For weeks it lived in CLAUDE.md, because that was the agent I used. Then I wanted any other client to follow the same rules, and that file name was the problem. Claude Code loads only CLAUDE.md; most other agents look for AGENTS.md.

Copying the rules into both files would give me two versions that drift apart. Instead the rules moved to AGENTS.md, and CLAUDE.md became one line:

@AGENTS.md

Claude Code expands @path imports when it loads a memory file, so it ends up reading the real contract, and every other client reads AGENTS.md directly. The rules have one home.

The rename that breaks silently

I use a global instructions file in my home directory that tells every session to read the contract in that repo, by path. After git mv CLAUDE.md AGENTS.md that path pointed at nothing. A missing file isn’t an error for an instruction like that. The agent just carries on without the rules, and I would have found out when entries stopped appearing.

So before renaming a file that instructions point at, grep for the old name in the repo and in the files outside it:

grep -rn "second-brain/CLAUDE.md" ~/.claude/CLAUDE.md

Mine was the only hit, and it lives outside the repo, so it isn’t in any commit and no diff would have shown it.

A snippet for other clients

For a client without that import mechanism I wrote a short block to paste into its global instructions. It points at AGENTS.md instead of restating it, for the same reason as above. The client needs a shell, a filesystem and push rights to the repo. A search tool is optional, since the plain index files work as a fallback.

What I tested

I started a fresh non-interactive session inside the repo with all tools turned off and asked what instructions it had loaded. It quoted the heading of the contract and its nine steps, and named CLAUDE.md and the global file as the sources, so the import works. That’s all I tested. I haven’t had another client write an entry from the pasted block yet.