The CLAUDE.md Phenomenon
Walk through any Claude Opus 4.7 repository and you have roughly a 1-in-5 chance of finding a file called CLAUDE.md. Across 9,281 Opus 4.7 repos:
- 1,324 repos (18.2%) contain CLAUDE.md
- 466 repos (5%) contain AGENTS.md
- 371 repos (4%) contain both
For comparison, in the ~280,000-repo community corpus, CLAUDE.md shows up in well under 1%. This is a uniquely Opus-era file.
What is CLAUDE.md?
CLAUDE.md is the self-documentation that Claude writes for Claude. It’s a project-local prompt file that encodes:
- Architecture decisions
- Build and test commands
- Coding conventions the agent should follow
- TODO lists and known issues
- Style guides specific to this codebase
When Claude Code opens a repo, it reads CLAUDE.md first. The agent literally prompts itself with this file. Over time, it becomes a shared mental model between the human maintainer and the AI collaborator.
AGENTS.md — the multi-agent sibling
AGENTS.md is similar but written for coordinating multiple AI agents working in the same repo. The 371 repos with both CLAUDE.md and AGENTS.md are essentially Opus 4.7’s multi-agent exemplars.
Why it matters
Three reasons this file is important for anyone building AI-coder products:
1. It’s a filter for “serious” Opus 4.7 projects
Repos with CLAUDE.md are, on average, higher-quality. They also have README.md (7,905 of 9,281 repos do), LICENSE (1,370), and a cleaner folder structure.
2. It’s a new API surface
CLAUDE.md is the de-facto standard for giving an agent persistent memory per project. No other AI coder has adopted an equivalent file at comparable scale.
3. It’s training data for the meta-task
Fine-tuning a model on “what CLAUDE.md files look like” teaches the model to generate instructions for itself — a higher-order capability.
File frequency in Opus 4.7 repos
| File | Appears in | % of repos |
|---|---|---|
| README.md | 7,905 | 85% |
| .gitignore | 4,997 | 54% |
| package.json | 3,601 | 39% |
| tsconfig.json | 2,529 | 27% |
| CLAUDE.md | 1,665 | 18% |
| LICENSE | 1,370 | 15% |
| .env.example | 1,076 | 12% |
| Dockerfile | 867 | 9% |
| AGENTS.md | 813 | 9% |
| Cargo.toml | 760 | 8% |
| requirements.txt | 740 | 8% |
| pyproject.toml | 651 | 7% |
| vite.config.ts | 526 | 6% |
| docker-compose.yml | 495 | 5% |
| next.config.ts | 408 | 4% |
| TODO.md | 97 | 1% |
The gap between “CLAUDE.md exists” (18%) and “TODO.md exists” (1%) is telling: Opus 4.7 prefers a single, structured self-prompt file over a loose task list.
What’s inside CLAUDE.md
Reading through a sample of CLAUDE.md files, the most common sections are:
- Project overview — 2–5 sentences on what the repo does
- Tech stack — list of frameworks used
- Commands — dev server, test, build, lint
- Conventions — how to name things, where to put new files
- Testing — how tests are organized and run
- Deployment — if applicable
It’s prose, not JSON — but it’s structured prose that the agent reliably respects.
Practical takeaway
If you’re generating new projects with an AI coder and want them to look like “real Opus 4.7 work,” write a CLAUDE.md on day one. It costs 15 minutes. It will compound across every future session.