Key Takeaways
- Cut your CLAUDE.md to under 100 lines.
- The 67-line version outperformed the 312-line one because Claude ignores irrelevant rules.
- Only keep rules that prevent repeated mistakes.
The Technique: Delete, Don't Add
Everyone says your CLAUDE.md should encode every rule you want Claude Code to follow. That's wrong.
The best CLAUDE.md is the shortest one that gets the agent to your bar. Rules you wrote and never enforced become noise that pushes the real instructions out of the cache window.
The proof: one developer's file went from 312 lines (barely worked) to 142 lines (worked better) to 67 lines (the version Claude actually follows).
Why It Works: CLAUDE.md Is Context, Not Commands
Claude Code injects your CLAUDE.md as a user message into the conversation. It attaches a system reminder saying roughly: "This context may or may not be relevant to your current task. Only reference it when actually relevant."
Claude decides which rules apply. The longer your file and the more irrelevant content it contains, the higher the probability that useful rules get skipped.
A single bad line cascades like dominoes:
One wrong instruction
-> Every research step follows the wrong lead
-> Plans built on bad research drift further
-> Code written from drifted plans breaks in production
The reverse holds too. One correct line saves time across every session.
How To Apply It: The 3-Rewrite Method
Rewrite 1: Cut everything Claude can infer from code.
Delete: "This project uses TypeScript" (you have tsconfig.json). Delete: "Python uses snake_case" (standard convention). Delete: "Please write high-quality code" (unverifiable, changes nothing).
Rewrite 2: Cut everything you've never enforced.
If you wrote a rule and Claude ignored it for 3 weeks, the rule is noise. Delete it.
Rewrite 3: Cut everything that isn't about repeated mistakes.
Hacker News comment from Boris on the Claude Code team: "If there is anything Claude tends to repeatedly get wrong, not understand, or spend lots of tokens on, put it in your CLAUDE.md. I add to my team's CLAUDE.md multiple times a week."
The file is supposed to be small enough that you can edit it mid-task.
The 6 Rules That Survived
The final 67-line file contained only six rules:
- Build commands Claude cannot guess from code (e.g.,
pnpm test:e2e --filter=@app/web) - Code style deviations from conventions (e.g., your team bans default exports)
- Test runner and framework details Claude can't infer
- Branch naming conventions and PR habits
- Why you made an architecture decision (not just "use X" but "use X because Y")
- Counter-intuitive gotchas and dev environment quirks
The Four-Layer Scope System
Your CLAUDE.md isn't one file. It's four layers that stack (later layers don't override earlier ones):
/Library/Application Support/ClaudeCode/CLAUDE.md
Entire organization
User instructions
~/.claude/CLAUDE.md
You, across all projects
Project instructions
./CLAUDE.md or ./.claude/CLAUDE.md
Team-shared, in Git
Local instructions
./CLAUDE.local.md
You, current project, not in Git
Pro tip: For domain-specific rules, use .claude/rules/ with paths: constraints. They only load when Claude touches matching files. This solved the classic problem of a database spec being ignored during frontend edits.
Anti-Pattern Checklist
Run this audit on your existing CLAUDE.md:
- Is it over 100 lines? Cut it.
- Does it contain "prefer" or "please"? Rewrite or delete.
- Does it state what's already in tsconfig.json, package.json, or README? Delete.
- Does it contain more than 2 all-caps IMPORTANT lines? Reduce to zero.
- Can you edit it mid-task without scrolling? If not, it's too long.
Try It Now
Open your current CLAUDE.md. Delete everything except:
- Build/test commands Claude can't guess
- Style deviations from conventions
- Architecture decisions and the why
- Gotchas that have burned you more than once
If you're at 67 lines, you're done. If you're at 300, you know what to do.
Source: dev.to
[Updated 26 Aug via devto_claudecode]
The guide also draws on teardowns of five real-world files, including Karpathy's 185K-star behavioral principles, Anthropic's internal config, and Dan Abramov's commit message constraints — showing even elite setups follow the same trim-or-ignore pattern. It introduces the router pattern for projects that outgrow a single file, plus six role-specific templates (frontend, backend, solo founder, content creator, data analyst, student) so you can start from a matching base rather than boilerplate. The HumanLayer founder Kyle's domino analogy is credited explicitly [per AI Workflow Pro].
