I've tested dozens of Claude Code configurations.
The only thing that really changed my output: a 60-line file called CLAUDE.md.
Keep this bookmarked 🔖
Here is exactly how it works, why most people miss it completely, and the full template you can copy today:
What no one tells you about Claude Code
Before your first prompt. Before a single line of code. Before anything happens in your session.
Claude reads one file. Just one.
CLAUDE.md.
And it treats it as the absolute truth for the entire session. Not as a suggestion. Not as context among others. As the definitive brief that frames every decision it will make.
That's why this file is the most underrated variable in the entire Claude Code stack.
Most people don't have one at all. And those who do have made one of two mistakes: either the file is empty of substance, or it's 300 lines of "be an experienced senior engineer who thinks step by step."
Both are useless. For different reasons.
Why most CLAUDE.md files don't work: the 3 real reasons
Reason 1: Too long
Claude can reliably follow about 150 to 200 instructions per session. This is a structural constraint, not a matter of goodwill.
Problem: Claude Code's internal system prompt already contains about 50 instructions. That means your CLAUDE.md actually has 100 to 150 instruction slots before Claude starts dropping them.
If your file is 200 lines long, Claude isn't ignoring your rules on purpose. It forgets them mechanically. You don't have a compliance problem. You have an attention budget problem.
Reason 2: Bad content
The majority of CLAUDE.md files are filled with things Claude can deduce on its own or that don't change its behavior in a measurable way.
"Act like a senior engineer." → Claude already knows what that means and it doesn't anchor any specific behavior. "Think step by step." → That's in its training. You're wasting a line. "Write clean and maintainable code." → No concrete criteria. Claude doesn't know what "clean" means in your specific context.
Every line that doesn't prevent a specific, concrete error is a line stolen from instructions that actually matter. The test is simple: if you delete this line, will Claude get something specific wrong? If the answer is no, the line shouldn't be there.
Reason 3: Zero hierarchy
Most people ignore that there are three levels of instructions in Claude Code, and they shove everything in the same place.
~/.claude/CLAUDE.md → Global (applies to all your projects)
.claude/CLAUDE.md → Project (shared with the team, in git)
./CLAUDE.local.md → Local (personal overrides, gitignored)
The global level is for rules you would repeat in every project. The project level is for context specific to your stack and team. The local level is for your personal preferences that don't need to be shared.
Using the three levels correctly is what keeps each file short, focused, and truly effective. Putting everything in one file is like building a funnel to drown your important rules under noise.
The 5 sections that make up an effective CLAUDE.md
After scouring dozens of CLAUDE.md files in production—open-source projects, official Anthropic docs, community best practice repositories—here are the 5 sections all effective files have in common:
Section 1: Critical commands
Claude starts every session without knowing how to build your project, run your tests, or fix lint errors. It will guess. And its guesses will cost you turns.
Tell it exactly what to type:
Commands
- Build:
npm run build - Dev:
npm run dev - Test single file:
npm test -- path/to/file - Full test:
npm test - Lint + fix:
npm run lint:fix - Type check:
npx tsc --noEmit
Short. Precise. Directly usable.
Without this section, Claude will try npm test when your project runs on pnpm vitest. It will spend three turns debugging a command issue that was never going to work. Three turns you could have used on real work.
Section 2: Architecture map
Claude starts every session with zero knowledge of your codebase. Zero. It doesn't know where your business logic lives. It doesn't know if your components are supposed to be stateless. It doesn't know that your API routes shouldn't contain business logic.
Give it a map:
Architecture
- src/lib/services/ → all business logic
- src/components/ → stateless UI components only
- src/lib/store/ → global state (Zustand)
- src/app/api/ → API routes, no business logic here
- DB access only via Server Actions or API routes
Not an exhaustive listing of your tree structure. Just enough so Claude knows where things live and, more importantly, where they should NOT go.
This distinction... where it goes vs. where it doesn't... is what prevents the most frequent architectural errors.
Section 3: Hard rules
This is the most important section of the entire file. Without exception.
Every rule here must answer a single question: "If I delete this line, will Claude make a concrete error?"
If yes → the rule stays. If no → it has no business being there.
Example of high-value rules:
Rules
- NEVER commit .env files or secrets
- All async calls must be wrapped in a try/catch
- Functional components only, zero class components
- Mandatory commit prefixes: feat:, fix:, docs:, refactor:
- Every PR must pass
npm run verifybefore merge - Static export only, no SSR (deployed on S3)
- IMPORTANT: run type check after every code modification
Two things to note about this list.
First, negative rules are as important as positive rules. "Never commit .env files" is a rule that only seems obvious until the day Claude does it. Put it in.
Second, emphasis markers like IMPORTANT or YOU MUST actually work.
This isn't anecdotal. Anthropic confirms it in their own documentation: adding IMPORTANT or YOU MUST before a rule measurably improves Claude's adherence to that rule.
Use them sparingly: reserve them for rules that have the most serious consequences if ignored.
Stay under 15 rules in this section. Beyond that, you dilute attention on the ones that matter.
Section 4: Workflow preferences
You've experienced this. You ask Claude to fix one line. It rewrites three files, renames your functions, and refactors a class that had nothing to do with your request.
This section prevents that:
Workflow
- Ask clarifying questions before starting complex tasks
- Make minimal changes, do not refactor unrelated code
- Run tests after every change, fix failures before continuing
- Create separate commits per logical change, not one giant commit
- In case of uncertainty between two approaches, explain both and let me choose
Every line here answers a concrete pain point. The 47-file giant commit. The unrequested complete rewrite. The architectural decision Claude makes alone when it should have asked you.
Section 5: What NOT to put in your CLAUDE.md
This section is as important as the others. Maybe more.
Do NOT include:
- Personality instructions ("be a senior engineer")
- Formatting rules that your linter already handles
- @ imports that pull entire docs into every session
- Duplicate rules (if global says "run tests", the project doesn't repeat it)
- Anything Claude learns on its own via auto-memory
This last point is widely underestimated.
Claude maintains its own notes in ~/.claude/projects/<project>/memory/. Run /memory in your session to see what it has already learned about your project. After a few sessions, you'll often realize Claude has already captured information you were going to write by hand in your CLAUDE.md.
Don't waste your limited instructions on things Claude has remembered on its own.
The complete template under 60 lines, ready to use
Delete sections that don't apply to your project. The goal isn't to fill everything. The goal is to keep only what changes Claude's behavior in a measurable way.
The lines that had the most impact on my output: concrete results
After testing dozens of configurations, here are the five lines that made the most visible difference:
IMPORTANT: run type check after every code modification → Prevents Claude from delivering code with broken types that it doesn't detect without being explicitly prompted to check.
Make minimal changes, do not refactor unrelated code → Prevents the complete and unrequested rewrite of entire files.
Create separate commits per logical change, not one giant commit → Prevents the unreadable monster commit of 47 mixed files.
In case of uncertainty between two approaches, explain both and let me choose → Prevents Claude from making architectural decisions alone that should have belonged to you.
Static export only, no SSR → Prevents Claude from adding server code in a project deployed statically on S3.
What these five lines have in common: each prevents a specific, frequent, and costly error in debug time.
This is the ultimate test for every line of your CLAUDE.md.
The fundamental error and why it is so widespread
People treat their CLAUDE.md like a wish list or a personality prompt.
"Be senior." "Be thorough." "Think like an expert."
This isn't a brief. It's magical thinking.
Your CLAUDE.md should be a technical document, not a motivational speech. Stack, commands, architecture, concrete rules, workflow. Everything else is noise that competes with the instructions that actually matter.
Keep the file under 80 lines. Revise it every time Claude makes an error you could have prevented.
And above all: understand what this file becomes over time.
A good CLAUDE.md in the first month saves you time on every session. By the third month, it has captured your conventions and stack precisely enough that Claude works almost like a team member.
By the sixth month, it contains every error Claude has ever made on this project and prevents them all automatically.
The file capitalizes. It improves with every correction. It progressively becomes the best onboarding brief you've ever written.
Not for Claude. For you.
