AGENTS.md and CLAUDE.md in one repo: what 1,203 folders do

By markdownregistry. Published October 3, 2026. Updated October 3, 2026.

Keep the instructions in AGENTS.md and start CLAUDE.md with an @AGENTS.md line. That is what Claude Code's docs show, and the most common single setup in the 1,203 folders the registry has collected from public GitHub that hold both files: 28.8% use the import, 23.8% a symlink and 3.2% identical copies. Another 8.8% only mention the other file in words, and 35.4% keep two separate files.

How the two files relate	Folders	Share
CLAUDE.md imports AGENTS.md with an @AGENTS.md line	347	28.8%
One file is a symlink to the other	286	23.8%
The two files are byte for byte identical	38	3.2%
One file names the other without an @AGENTS.md import	106	8.8%
Two files that share 80% or more of their lines	51	4.2%
Two files that share 30% to 80% of their lines	60	5.0%
Two files that share under 30% of their lines	315	26.2%

1,203 folders in 869 public GitHub repositories that hold both an AGENTS.md and a CLAUDE.md, each file read at its latest version in the registry on October 3, 2026. How each setup was decided is under How we counted.

Counted from the registry's own crawl of public GitHub, read on October 3, 2026. What Claude Code does with each setup is from its documentation, read the same day.

What the 1,203 folders do

The most common setup, in 28.8% of folders, is the one Claude Code's documentation shows: the instructions live in AGENTS.md, and CLAUDE.md starts with an @AGENTS.md line that pulls them in. 120 of those 347 CLAUDE.md files hold other lines as well, such as instructions for Claude Code only; the other 227 hold the import and nothing else. The two most starred repositories with a folder that uses the import are nexu-io/open-design and bytedance/deer-flow.

A symlink is next, in 23.8% of folders: one file is a link to the other, so both names open the same text. In 228 of those 286 folders CLAUDE.md points to AGENTS.md; in the rest AGENTS.md points to CLAUDE.md. The two most starred with a CLAUDE.md linked to AGENTS.md are code-yeongyu/oh-my-openagent and coreyhaines31/marketingskills. Only 3.2% keep two byte for byte identical copies, which stay identical only until someone edits one of them.

Then come the folders that keep two files. 51 hold two files that share most of their lines, the usual sign of a copy that has started to drift. 315, more than a quarter, hold two files that share under 30% of their lines. 807 of the 1,203 folders are the repository root; the rest sit inside packages and subdirectories. By a repository's stars when it was crawled, the import or a symlink is used about equally below 1,000 stars (51.3% of 811 folders in repositories with under 100 stars; 52.8% of 229 folders in repositories with 100 to 999 stars) and somewhat more often at 1,000 or more (58.9% of 163 folders in repositories with 1,000 stars or more).

What Claude Code reads in each setup

By default, Claude Code reads AGENTS.md only when there is no CLAUDE.md in the working directory or above it, according to When Claude Code reads AGENTS.md. In every folder counted here a CLAUDE.md exists, so by default CLAUDE.md is what Claude Code loads, and AGENTS.md reaches it only through that file, unless the Project instructions setting is changed to read both.

An import. The imported file is expanded and loaded at launch with the CLAUDE.md that names it, and the docs say keeping the import never makes Claude read AGENTS.md twice. Claude Code reads AGENTS.md on its own from version 2.1.277, so the docs say a CLAUDE.md that holds nothing but the import can be removed, or kept if some of your sessions cannot load AGENTS.md directly. 227 of the CLAUDE.md files here hold only the import; before removing one, check that no other CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the same folder or any folder above it, since that file would then be read instead of AGENTS.md.
A symlink. The docs say to leave it or delete it; either way Claude reads the content once.
A mention in words. A CLAUDE.md that tells Claude to read AGENTS.md works only if Claude decides to open the file. For that file the docs advise deleting it, with the same version and folder caveats as the import, or replacing the sentence with an @AGENTS.md import. 106 folders, 8.8%, fall in this group, which also counts an AGENTS.md that names CLAUDE.md, where that advice does not apply.
Two separate files. Claude Code follows CLAUDE.md, and an agent that reads AGENTS.md follows that file. The AGENTS.md site adds that the AGENTS.md closest to the edited file wins, so a package's own AGENTS.md beats the root one for those agents. In 315 folders the two files share under 30% of their lines.

When a symlink is the wrong choice

On macOS and Linux a symlink works, and Claude reads the instructions once. Claude Code's documentation names two limits on it, in Share one file with other coding tools. Its Edit and Write tools refuse to write through a symlink and send Claude to edit the target instead. And on Windows, creating one needs Administrator rights or Developer Mode, while a clone made without symlink support gets a one-line text file in place of the instructions. Git's own core.symlinks documentation says the same: with the setting false, symbolic links are checked out as small plain files that contain the link text.

So if anyone who clones the repository works on Windows, the docs recommend the import over the symlink. 286 of the folders counted here, 23.8%, depend on a symlink. In the 58 where AGENTS.md is the link, a clone without symlinks gives every agent that reads AGENTS.md a file holding only the link's target path.

Check which setup your repository uses

Git records a symlink with the mode 120000 and a regular file with 100644 (100755 when it is executable), so git ls-files -s shows which you have. grep -n '@' lists every line of a CLAUDE.md that may hold an import, since an import can sit anywhere in a line; one inside a code span or a code block does not count. This is the output from a scratch repository with a symlinked CLAUDE.md at the root and an importing one in web/:

$ git ls-files -s AGENTS.md CLAUDE.md web/CLAUDE.md
100644 c210dd0e847e27d735268681eea5d9f7f922dc99 0	AGENTS.md
120000 47dc3e3d863cfb5727b87d785d09abf9743c0a72 0	CLAUDE.md
100644 6324e0d711ec068444d8cd34b915543eac643443 0	web/CLAUDE.md
$ grep -n '@' web/CLAUDE.md
1:@AGENTS.md

To confirm what Claude Code loaded, the docs suggest running /context in your next session and checking that CLAUDE.md appears under Memory files. To see the files other repositories use, every CLAUDE.md the registry has collected is on the CLAUDE.md page and every AGENTS.md on the AGENTS.md page, most starred first.

How we counted

The registry collects agent markdown from public GitHub repositories and stores every version of each file by the SHA-256 of its content. We took every folder where one repository holds both an AGENTS.md and a CLAUDE.md in the same directory, read each file's latest stored version, and checked its bytes against its hash. 18 more folders were left out because one of the two files had no stored version yet; every file in the folders counted was read and matched its hash. A CLAUDE.md inside .claude/ counts only against an AGENTS.md in that same folder.

Each folder was put in the first group it matched, in this order: identical bytes; a symlink, meaning one file's whole content is a path ending in the other file's name, which is how GitHub serves a symlink's contents; an import, meaning an @AGENTS.md reference in CLAUDE.md (this count does not leave out one written inside a code block); a mention in words, meaning a file under 600 bytes that names the other file, or an AGENTS.md that refers to @CLAUDE.md; and otherwise two separate files, compared by the share of their distinct non-blank lines that appear in both. Two edge cases fall where these rules put them: a CLAUDE.md that imports a different path such as @docs/AGENTS.md counts as a mention in words when it is short and is compared as two separate files when it is longer, and a symlink to an AGENTS.md in another folder counts as a symlink. The registry crawls the public repositories it has found that hold agent files, not all of GitHub, so read the shares as describing those repositories. The full method for the registry's data is in State of agent markdown, September 2026.

Sources

Last checked October 3, 2026.