What's in 1,431 CLAUDE.md and AGENTS.md Files: A Study of 3,000 Popular GitHub Repos

Agent instruction files went from rare to normal in about a year. We wanted to know what the files in real projects look like, so we measured them: every root CLAUDE.md, .claude/CLAUDE.md and AGENTS.md in the 3,000 most-starred public GitHub repos that were active in the last two months.

The short version: one in three popular repos now has an agent file, AGENTS.md has overtaken CLAUDE.md, and most files describe how the project works without saying what the agent must never do.

The full dataset is a CSV you can download, one row per file. It is also on GitHub at GDM-Digital-Media-Group/claude-md-study, with a column guide, under CC BY 4.0.

How we measured

• Sample: the 3,000 most-starred public repos on GitHub that are not forks, not archived, and had a push on or after September 1, 2026. Every repo in the sample has at least 3,553 stars.
• Files: CLAUDE.md, .claude/CLAUDE.md and AGENTS.md at the repo root. Files in subfolders were not counted.
• Checks: the code checks from the FixMyPrompt CLAUDE.md checker: line count, an estimated token count (about 4 characters per token), text pasted in by tools, and whether the file mentions six guardrail topics. No AI model read or graded any file, so anyone can rerun this and get the same numbers.
• What we kept: metrics and repo names only. No file text is stored or published.

The guardrail check is a keyword match. It tells you whether a file mentions a topic at all, such as .env or git push --force, not whether the rule it writes is a good one. Read those numbers as "never mentions", which is how we report them.

One in three popular repos has an agent file

Of the 3,000 repos, 1,000 (33%) have at least one of the three files at the root. Between them they hold 1,431 files.

AGENTS.md is in 857 repos and CLAUDE.md in 573. Many projects that use Claude Code now treat AGENTS.md as the main file and keep CLAUDE.md only so Claude Code finds it.

How projects with both files handle it

430 repos have both files. They split three ways:

The 132 repos in the last group keep two sets of instructions for the same codebase. Each time one changes, the other has to change too, or the agents get different rules.

The pointer files are worth a closer look. We read all 149 CLAUDE.md files that were 5 lines or shorter:

• 125 use an @ import, usually @AGENTS.md. Claude Code loads the imported file into the session, so this works.
• 19 only link to AGENTS.md in plain Markdown, such as See [AGENTS.md](./AGENTS.md). Claude Code does not follow Markdown links on its own. Unless Claude decides to open the file, a session in those repos starts with one line of instructions.
• 5 are something else. Two of those tell agents not to write code for the project at all.

If your CLAUDE.md points somewhere else, use @AGENTS.md on its own line.

How long the files are

Leaving out the 163 pointer files, the 1,268 remaining files look like this:

Anthropic's guidance for Claude Code is to keep each CLAUDE.md under 200 lines, because a longer file costs more context and gets followed less reliably. 28% of files are over 200 lines, and 5.8% are over 500. One file in seven (14.5%) is over 5,000 estimated tokens, all of it read at the start of every session.

Text pasted in by tools turned out to be rare in this sample: only 5 files, all with the block that next dev adds.

The guardrails most files never mention

A good agent file tells the agent what the project is and what it must not touch. Most files in the sample do the first part well. Here is how often they never mention each guardrail topic:

CLAUDE.md files alone are a little worse on secrets: 71.5% never mention them, against 65.2% for AGENTS.md.

Only 2.9% of files mention all of the guardrail topics that apply to the project. The median file misses three. One in four (23.3%) misses five or more.

We also checked database and migration rules, but only for projects whose package.json names a database library. That was 34 files, too few to report a percentage.

The test command is the one most projects include, which makes sense: it is the thing an agent needs to do its job. The rules that protect you from the agent, like never pushing with --force or never reading .env, are the ones left out. Those are also the rules you only miss after something has gone wrong.

Files that cover everything and stay short

Eight files in five repos mention every guardrail topic that applies and stay under 200 lines (three of the repos keep identical CLAUDE.md and AGENTS.md copies):

• deepseek-ai/deepseek-harness, 190 lines
• ToolJet/ToolJet, 199 lines
• redis/RedisInsight, 178 lines
• rorkai/App-Store-Connect-CLI, 155 lines
• francescopace/espectre, 68 lines

They are worth reading if you are writing your own. The shortest is 68 lines, which shows the guardrails do not need much room.

Limits of this study

• Popular repos only. These are projects with thousands of stars and active maintainers. Personal and company repos may look different, and this study says nothing about them.
• Root files only. Subfolder CLAUDE.md files and .claude/rules/ were not counted.
• Keyword checks. A file can mention .env without a useful rule about it, and a file can protect secrets in words our patterns miss.
• Estimated tokens. About 4 characters per token, not an exact tokenizer count.

Check your own file

Paste your CLAUDE.md or AGENTS.md into the free CLAUDE.md checker. It runs the same checks used here, plus a model pass for rules that contradict each other or are too vague to follow, and shows what the file costs every session.

The data for this post is in the CSV. If you write about it, a link back to this page is all we ask.