Watercolor squares painted from the themes chart below: a hill of colour that rises to 13 rules a file in late 2025 and settles to 9. Blue bands, the coding advice people cut, thin out; red and orange bands, the boundaries they kept, hold; faint squares above the hill are the rules that were deleted.

I read 5,786 CLAUDE.md files to see if Boris Cherny was right

Fred Chang · October 10, 2026

Our own CLAUDE.md grew to 994 lines.

Boris Cherny, who built Claude Code, would delete it. On Y Combinator's Light Cone podcast he said to start over and add a line back only when the model goes off track: "What you're probably gonna find is with every model, you have to add less and less." His team's shared file is "pretty short," about a couple thousand tokens, and gains a line when a teammate's PR makes a mistake the file could have prevented. At YC Startup School he described re-testing the same way: his team deleted Claude Code's system prompt and brought it back line by line, cutting over 80% of it for Opus 5. His advice: "every six months, delete your CLAUDE.md, delete your skills, delete your hooks," and add something back "only when you see it repeatedly stumble on the same thing."

So what did Boris keep? The team file he described is in Anthropic's private code. The one in the public anthropics/claude-code repo, which holds Claude Code's issues and plugins, is 40 lines. Every line is a boundary: the runner, network allow list and permission mode that any workflow calling Claude must keep. A CI check fails a workflow that breaks one.

What does everyone else keep as models improve? I read 5,786 CLAUDE.md and AGENTS.md files from GitHub to find out.

TLDR: new files got a third shorter. People cut rules about how to write code and kept rules about what the agent must not touch.

What people cut from CLAUDE.md files, and what they kept

Stacked chart of average rules per new CLAUDE.md or AGENTS.md file by quarter, Q2 2025 to Q3 2026, in 12 themes. The total falls from 13 to 9 after Q4 2025. Code idioms and types fall from 18.1% to 10.3% of a file and tests from 9.1% to 5.8%, while rules about what not to touch rise from 12.5% to 17.3% and main branch and secrets from 3.5% to 7.2%. — Every rule in every new file, by theme. Red themes grew as a share of a new file, blue ones shrank, grey ones stayed within 15%.

Every rule in every new file, by theme. Red themes grew as a share of a new file, blue ones shrank, grey ones stayed within 15%.

Coding advice (style, tests, checks before done) fell by about half per file. Rules about what not to touch held at 1.6 per file, and rules about the main branch and secrets grew. A model can learn your style from your code; it can't learn which files are generated or where the secrets live.

Does a CLAUDE.md file actually help?

At ETH Zurich, Thibaud Gloaguen and colleagues ran coding agents on real repository tasks with and without a context file, across several models and agents. The file "does not generally improve task success rates" and raised the cost by over 20% on average; its length made no clear difference. What helped was instructions for "non-standard coding practices," the conventions an agent can't get from your README. Repository overviews didn't help.

CLAUDE.md vs AGENTS.md: which should you use?

In repos with 1,000+ stars, 87% of new files are now AGENTS.md.

Line chart of AGENTS.md's share of new files per quarter. In repos with 1,000+ stars it rises from 46% to 87%. In a random sample of active repos it stays between 30% and 46% until Q2 2026 and reaches 56% in Q3 2026. — AGENTS.md's share of new files. The rest are CLAUDE.md.

AGENTS.md's share of new files. The rest are CLAUDE.md.

Make AGENTS.md your default. Codex, Gemini CLI, Jules, GitHub Copilot and Cursor read it, and Claude Code reads it when there is no CLAUDE.md (2.1.277 and later).

What's the most copied CLAUDE.md rule?

"No abstractions for single-use code," from forrestchang/andrej-karpathy-skills, a CLAUDE.md written from Andrej Karpathy's notes on LLMs coding badly.

What should go in your CLAUDE.md?

Cut:

Style advice and repository overviews. The agent reads both from your code.

Keep:

Boundaries: generated files, protected branches, secrets, public APIs.
Conventions that differ from the defaults.

Enforce:

Any rule that must never be broken, with a hook or a permission setting. The model reads the file; nothing makes it obey. Boris's team pairs its public file with exactly that kind of check.

Anthropic says the same: "Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens." Their best practices add that if Claude already does something right without the instruction, "delete it or convert it to a hook."

To check yours, run /doctor prompt-audit (Claude Code 2.1.283 and later). It flags instructions written for older models, references to files or commands that no longer exist, and contradictions, and changes nothing until you approve its edits.

Run this analysis yourself with agent skills

I ran it with four skills we published. They work in any agent that reads skills:

We turn anything we do twice into a skill and update it as models improve.

All 5,786 files are in our public catalog of CLAUDE.md examples and AGENTS.md examples. That catalog is the public half of agentleFS. The private half holds your team's own CLAUDE.md, AGENTS.md, skills and docs, shared with your agents under your permissions. Connect an agent, and it can search both.

Appendix: how I did it

2,471 CLAUDE.md and AGENTS.md files at the root of public GitHub repos with 1,000+ stars, from our public catalog. The catalog keeps files over 1,500 bytes under licences that allow sharing.
3,315 more from 30,000 repos picked at random from the 6 million with recent activity, at any number of stars and any size. This sample checks the first one.
Each file as it looked 30 days after it was created, so I'm measuring how people start a file, not how it grew. 4,606 of the 5,786 files had at least one rule.

A rule is any line that tells the agent to do or not do something. There were 96,576 of them. I grouped them by meaning into 40 kinds, then by hand into 12 themes.