A good CLAUDE.md is short. A great one is boring. If yours is longer than 500 lines or reads like a mission statement, it's hurting you, not helping.
Here's the structure I've landed on after 3 months of daily Claude Code use.
Anything that applies to MULTIPLE projects belongs in ~/.claude/skills/ as a skill. Anything that's true of THIS project specifically — stack, deploy target, unique conventions, gotchas — belongs in CLAUDE.md.
Once you separate those two, CLAUDE.md gets small fast.
A paragraph. What the product does, who it's for, current state. Not a mission statement. Not "we believe." Just: "X is a Y for Z, currently in beta, 200 paying users, stack is Next.js 16 + Supabase."
- Runtime version
- Package manager (npm vs pnpm vs bun)
- Database
- Deploy platform
- Auth provider
- Payment provider (if any)
- Anything that determines how commands run
- Naming conventions (e.g., "files use kebab-case except React components which use PascalCase")
- Testing framework + how to run
- Lint/format command
- Commit message style if enforced
- Branch naming if enforced
- Env var location (.env.local? .env.development?)
The section that earns CLAUDE.md its keep. A numbered list of 5-15 specific traps:
- "The Stripe webhook endpoint needs raw body — do not use express.json() middleware on /api/webhooks/stripe"
- "Supabase row-level security is on — queries from the server must use the service-role key"
- "The prod database has a
feature_flagstable; do not rely on env vars for flags" - etc.
This is where 80% of real value is. It saves Claude from making the mistakes you made before.
- Paths that are frozen (legacy, third-party, generated)
- Files Claude should never edit (secrets, credentials, generated types)
- Patterns Claude should refuse (don't touch
migrations/*except to add new timestamped files)
- "Review my PR" instructions → skill file
~/.claude/skills/pr-review-comprehensive/SKILL.md - "Check test coverage" instructions → skill file
~/.claude/skills/test-gaps/SKILL.md - "Write a changelog" instructions → skill file
~/.claude/skills/changelog-bot/SKILL.md - "Generate release notes" → skill file
~/.claude/skills/launch-post-release/SKILL.md - Aspirational language ("we value excellence", "customer-first", "world-class")
- Corporate-speak (leverage, synergy, revolutionize, game-changing, seamless)
- Marketing copy of any kind
Skills enforce scope and output shape; CLAUDE.md doesn't. If you write the PR-review procedure in CLAUDE.md, Claude re-interprets it fresh every session and drifts. If you write it as a skill, it runs the same way every time.
You can run your CLAUDE.md through a free tool that flags length, corporate-speak, and recurring-instruction patterns that should be skills:
septimlabs.vercel.app/tools/claude-md-analyzer
Pure client-side. Nothing uploaded. Run your 2000-line CLAUDE.md through it and see what it flags.
If you want 25 pre-written skills that cover the recurring instructions you'd extract (PR review, test gaps, migration safety, security triage, refactor, changelog, postmortem, launch copy, etc.), the full pack is $29 lifetime at septimlabs.vercel.app/drills. Private GitHub repo, free updates forever.
3 free samples: github.com/septimlabs-code/septim-drills-samples.
Tonight only: Drills + Vault (encrypted dev-secret vault) for $39 bundled (save $19 vs $58 separate) — septimlabs.vercel.app/tonight. Expires midnight ET.
- CLAUDE.md = project-specific context. Short.
- Skills = reusable instructions. Go in
~/.claude/skills/. - Remove aspirational language. Claude can't act on it.
- The gotchas section is where CLAUDE.md earns its keep.
- Run the free analyzer on what you have right now.
Septim Labs — free tools + paid packs for Claude Code. April 20, 2026.