A great CLAUDE.md is not the longest one. It is the one where every line changes what Claude does. The whole skill is knowing what belongs in it β and, just as importantly, what does not.
The sections that earn their place
Start with a one or two line project description and your stack, with version numbers. Claude infers a lot from your code, but it will not guess that you are on Next.js 15 instead of 14, or which ORM you chose.
Then a directory map β not every file, just the top-level layout with a note on what each part holds. After that: the build and test commands, the conventions a formatter does not enforce, and critically, the things not to touch.
# Project: Acme Dashboard
Next.js 15 (App Router), TypeScript, Drizzle ORM, Vitest.
## Structure
src/app/ # routes and pages
src/lib/ # shared utilities, db client
db/migrations/ # generated - never hand-edit
## Commands
Build: npm run build
Test: npm run test
## Conventions
- API routes return { data, error } - never throw to client
- Server components by default
## Do not touch
- db/migrations/ is generated. Never edit by hand.
Every line in that file would cause a mistake if removed. That is the bar.
What to leave out
This is where most files go wrong. Two kinds of content waste your budget:
Personality instructions. "Act as a senior engineer," "think step by step," "be thorough." These feel productive but change nothing β Claude already does them. General advice that does not prevent a specific mistake is pure noise.
Rules a tool already enforces. If you have a formatter or linter, do not restate what it enforces. Wire it into a hook instead, and keep CLAUDE.md for what tools cannot enforce.
The one-line test
For every line, ask: "If I remove this, will Claude make a mistake?" If yes, keep it. If no, delete it.
This single question, applied ruthlessly, is the difference between a file Claude follows and one it ignores. A bloated file buries the rules that matter in noise, so Claude cannot tell which line is the important one. Pruning is not tidying β it is what makes the file work.
Why brevity is performance
CLAUDE.md loads into Claude's context every session, and performance degrades as context fills. A leaner file is not just easier to read β it makes Claude more reliable, because the rules that matter are not competing with filler for attention. Short is not a style choice here. It is a performance requirement.
Free starter: The format, a complete annotated example, and the one-line test are all on a free cheat sheet: CLAUDE.md Quick-Start Cheat Sheet
Go deeper: The full guide covers the entire configuration stack β hooks, subagents, commands, skills and plugins β with real-world walkthroughs and a 30-day plan: CLAUDE.md: The Complete Claude Code Configuration Guide
What is the one rule in your CLAUDE.md that has saved you the most? Share it in the comments.
United States
NORTH AMERICA
Related News
Why Every Developer Needs a Strong Test Suite (Even If You Hate Writing Tests)
23h ago
SOLSTICE SIDEBAR - AI INCIDENT DESK
1d ago
The CFO's AI Playbook: 5 Finance Automations Every Indian Business Should Run in 2026
1d ago
Passkeys in 2026: A Practical Engineering Guide to Passwordless Auth
1d ago
AWS S3 Basics for Beginners
23h ago