What open-source products tell their coding agents: AGENTS.md and CLAUDE.md, by the numbers
Half of the actively developed open-source products we track now keep instruction files for coding agents. Which files, how long, what goes in them, and how they talk to the agent — from 1,414 repos.
Share of 1,414 open-source products' repos pushed to in the last 180 days. A repo can keep several.
A coding agent starts every session knowing nothing about your project. Instruction files fix that: a Markdown file at the root of the repo — AGENTS.md, an open format many agents read, or CLAUDE.md for Claude Code — that says how to build it, test it and change it. We read the ones in the repos of 2,097 open-source products we track, and counted what they hold. The sample is the 1,414 repos someone pushed to in the last 180 days.
Half keep one, and newer projects more
727 of the 1,414 — 51% — keep at least one instruction file. Newer projects lead: 72% of repos created in 2026, against 37% of those created in 2019 or earlier.
Of 1,414 repos pushed to in the last 180 days.
Bigger projects keep them more often: 68% of repos with over 10,000 stars, 46% of those with 100 to 1,000. By language, Rust (70%), Go (62%), TypeScript (60%) lead; Vue (23%) and Jupyter Notebook (22%) trail.
AGENTS.md is winning the name
AGENTS.md is in 38% of the repos, CLAUDE.md in 30%; Copilot's and Cursor's own rule files in 8% and 8%. The two leaders aren't rivals so much as one file under two names: of the 320 repos with both, 170 have a CLAUDE.md that only points to AGENTS.md — a symlink, or a single line importing it. Write the instructions once, in AGENTS.md, and point the other names at it.
What goes in them
The median file is 909 words — about 4 minutes of reading — and half run between 425 and 1,665. What they spend it on is practical:
Share of 641 AGENTS.md or CLAUDE.md files with a section on it (one that only points to the other left out). Counted from headings and commands.
The commands come first because they're what an agent can't guess: pnpm, npm, uv, bun are the package managers they name most, and pytest, Vitest, Playwright, ESLint the test and lint tools. 68% point on to other documents rather than repeating them — a contributing guide, an architecture note, a folder's own AGENTS.md.
How they talk to the agent
80% of the files tell the agent what not to do — “never”, “do not”. 24% raise their voice in capitals (IMPORTANT, MUST, NEVER). And 20% draw a line on initiative: ask before doing something, or don't do it unless asked.
Beyond one file: the .claude folder
22% of the repos also commit a .claude folder, and what's in it has moved past settings. Most hold skills — reusable instructions Claude loads when a task calls for them:
Share of the 316 repos with a .claude folder.
What they name, and what they don't
The tools in these files are the ones an agent runs: languages, package managers, test runners, linters. The services the product runs on hardly appear — Cloudflare in 5%, Vercel in 5%, Sentry in 4%, Supabase in 3%, Stripe in 2% of files. Instruction files are about how to work in the code, not what it's deployed to. What they say about each tool, from Playwright to pnpm, is in How AGENTS.md files talk about your tools.
Writing your own
Roughly in order of how many of these files cover each:
- Commands first. How to install, run, test and lint — with the exact package manager.
- How to check a change. Which tests to run, and what “done” means.
- A map, not a copy. The project's structure in a few lines, and links to the documents that explain more.
- Conventions the code can't show. Naming, style, commit and pull request rules.
- Where the agent should stop. What not to touch, and when to ask first.
Keep it to the length most projects settle on — around 900 words — in AGENTS.md, with CLAUDE.md pointing to it. Plan your stack starts one for you: these sections, your picks, and the package manager and test tools projects built like yours name most.
How we counted
For each repo, GitHub's API gave us the root files, the instruction files above and the folders some agents read rules from (.cursor/rules, .claude, .github/instructions, .clinerules, .kiro/steering). Topics come from a file's headings, with commands also counted when they appear only in code blocks; we checked samples of each by hand. These are open-source projects; private products' repos may differ. The files are their authors' writing, often under no licence, so this page publishes counts only. Counted on 2026-10-12.