Have you ever set up a CLAUDE.md file, dropped in 200 lines of rules, and then watched the AI completely ignore half of them anyway?
You are not alone. The irony of writing instructions for AI coding assistants is that the same productivity trap applies to you: more rules ≠ better results.
Here are five patterns that actually work, learned from managing production CLAUDE.md setups across a dozen project starters.
1. The 800-token rule
The biggest CLAUDE.md mistake is treating it like documentation. It is not documentation. It is a system prompt prefix — and system prompts have a working memory budget.
A rough heuristic: keep your primary CLAUDE.md under 800 tokens (~600 words). Beyond that, context compression pushes older rules out when long files are open.
What to cut:
- Rationale paragraphs ("we do this because...")
- Historical context ("we used to use X but now...")
- Anything that is obvious from the codebase itself
The rule goes in CLAUDE.md. The rationale goes in a comment in the relevant file, or nowhere.
2. Use glob-scoped rules, not one giant file
Claude Code supports scoped CLAUDE.md files — rules in src/api/CLAUDE.md apply only when files under src/api/ are open. Use this.
A frontend rule about "never use inline styles" has no business loading when the AI is working in your Express routes. A backend rule about "always use parameterized queries" does not need to be in context when fixing a CSS animation.
Practical layout:
CLAUDE.md # project-wide: stack, deploy process, critical invariants
src/api/CLAUDE.md # API-specific: auth patterns, error formats, rate limiting
src/web/CLAUDE.md # Frontend-specific: component conventions, state patterns
scripts/CLAUDE.md # Automation: env var handling, idempotency requirements
Each file stays under 300 tokens. Total loaded at any time: ~600 tokens. Still under budget.
3. One concern per rule
Compound rules fail silently. When you write:
"Functions should be small, pure, and well-named, with explicit return types and no side effects unless they are in service files."
...the AI picks the parts it agrees with and ignores the rest. This is not a model quality problem — it is a parsing problem. Compound sentences create ambiguity about which clause is the constraint and which is the suggestion.
Split every compound rule into atomic statements:
## Functions
- Max 30 lines. Extract helpers if exceeded.
- Explicit return types on all exported functions.
- No side effects except in `*Service.ts` and `*Repository.ts` files.
Three lines, three enforceable constraints, zero ambiguity.
4. Negative rules outperform positive rules
"Use Zod for all schema validation" is a positive rule. It tells the AI what to do, but not how strongly you mean it.
"Never use any types. Never use untyped JSON.parse() without a Zod schema." — these are negative rules. They draw a hard line.
In practice, AI assistants weight prohibitions more heavily than recommendations. This is because prohibitions reduce the valid solution space (easier to enforce) while recommendations just add a preference (easier to deprioritize under other pressures).
Reframe your positive rules as negative rules where you can:
| Positive | Negative |
|---|---|
| Use environment variables for all config | Never hardcode URLs or credentials |
| Write tests for all public functions | Never ship a new exported function without a test file |
| Use the existing logger | Never call console.log directly in production code |
The negative framing also makes violations easy to grep for.
5. Pair CLAUDE.md with a production-configured starter
The best CLAUDE.md is one that describes a codebase that already follows its own rules. When the starter project has ESLint configured, TypeScript strict mode on, and the folder structure already in place — the CLAUDE.md rules are reinforced by the code itself.
This is why project starters are worth spending time on. If your starter has any types everywhere and no linting, your CLAUDE.md rule against any is fighting the existing codebase instead of aligning with it.
We built the Vibe Coder Kit specifically for this: 12 production-configured starters (Next.js SaaS, Express + JWT, Node CLI, Chrome Extension, Discord Bot, FastAPI, and more) where the CLAUDE.md rules match what the code already does. Zero setup, immediate AI alignment.
The one-line takeaway
CLAUDE.md files fail the same way most documentation fails: they get long, stale, and comprehensive when they should be short, current, and opinionated.
Short. Scoped. Atomic. Negative where possible. Backed by a codebase that already follows the rules.
That is the setup that makes vibe coding actually work.
BLN Craft builds developer tools for AI-native workflows. Follow us at blncraft.com for more.