Writing Rules That Actually Stick

You wrote a CLAUDE.md. Added rules. Claude Code ignores them. You add more rules. Ignored again. So you throw "IMPORTANT" in all caps at the top and hope for the best.

The problem is almost never that Claude Code is being stubborn. Your rules are vague. Or buried. Or fighting each other. Writing rules that actually change behavior is a craft, and most people are bad at it because they write rules that sound good instead of rules that work.

The One Principle

A good rule removes ambiguity. That is it. Claude Code won't figure out what you mean by "format code properly." That phrase means something different to every developer alive. "Use 2-space indentation in all TypeScript files" leaves nothing to interpret.

A rule should be specific enough that two different developers would follow it the same way. If they wouldn't, rewrite it.

# Bad: sounds reasonable, does nothing
- Format code properly
- Test your changes
- Keep files organized
 
# Good: boring, obvious, actually works
- Use 2-space indentation in TypeScript files
- Run npm test before committing any changes
- API handlers live in src/api/handlers/

The bad versions feel like good advice. They're decoration. The good versions are boring. Boring is the goal. Boring rules get followed. Clever rules get misinterpreted.

Emphasis markers help too. Adding "IMPORTANT" or "YOU MUST" to critical rules genuinely improves adherence. Not yelling. Signaling priority.

# Without emphasis
- Do not modify files in the vendor/ directory
 
# With emphasis
- IMPORTANT: Never modify files in the vendor/ directory. These are auto-generated.

Structure Over Prose

A CLAUDE.md isn't a diary entry. It is closer to a config file that happens to be written in English. Dense paragraphs make rules harder to extract. Claude Code has to parse this stuff, and walls of text actively hurt.

Keep it under 200 lines. Not arbitrary. Longer files eat context, and rules near the bottom of a 400-line file get less attention. Claude Code isn't ignoring your rules on purpose. They're just drowning in noise.

## Build Commands
- Run `npm run build` to verify changes (never use dev server)
- Run `npm test` before every commit
 
## Code Style
- Use 2-space indentation
- Prefer named exports over default exports
- IMPORTANT: All React components must be server components unless they need interactivity
 
## Architecture
- API routes go in src/api/
- Shared types go in src/types/
- Database queries go in src/db/

Each section has a clear purpose. Each rule is a single bullet. No paragraphs. No storytelling. Just instructions.

Include: Bash commands Claude Code can't guess, code style that differs from defaults, testing instructions, architectural decisions, dev environment quirks, project-specific gotchas.

Skip: Things Claude Code can figure out by reading your code, standard conventions it already knows, detailed API docs (link instead), frequently changing info, long explanations of why a rule exists. If you need the "why," keep it to a short parenthetical.

Try It

Open your CLAUDE.md. Pick three of your vaguest rules. Rewrite each so a brand new developer could follow them on day one without asking a single question.

Example. You have this:

- Follow our testing conventions

Replace it with:

- Write tests in __tests__/ next to the source file
- Use describe/it blocks, not test()
- Run `npm test -- --coverage` before opening a PR
- IMPORTANT: Never mock database calls in integration tests

Four specific rules replaced one vague one. Each one you can actually check.

The Five Ways People Screw This Up

Conflicting rules across files. Project CLAUDE.md says "use tabs." Home directory CLAUDE.md says "use spaces." Claude Code picks one at random. Audit all your CLAUDE.md files for conflicts. This one bites people constantly.

Too many rules to find anything. Claude Code keeps doing something you explicitly banned? File is probably too long and the rule is buried on line 347. Prune aggressively.

Never updating. Your project changed six months ago but your CLAUDE.md still references the old test runner. Treat it like code. When Claude does something wrong, check the rules first. When it asks a question your CLAUDE.md should answer, the phrasing is ambiguous. Review regularly.

Including the obvious. You don't need to explain what git is. You don't need a file-by-file breakdown of your codebase. Claude Code can read your code. Save rule budget for things it genuinely can't infer.

Burying the instruction under philosophy. Three paragraphs about your company's engineering values, then the actual rule on line 180. That rule is dead on arrival. Instruction first. Minimal context after.

Think of your CLAUDE.md as a constitution. Tight. Clear. Current. Your per-message prompts are the flexible part. The CLAUDE.md is the foundation.

Bottom Line

• Specificity over cleverness. Always. "Use 2-space indentation" destroys "format code properly."
• 200 lines max. Prune often. Link out to external docs.
• Headers, bullets, emphasis markers. Not paragraphs.
• When Claude misbehaves, your CLAUDE.md is the first suspect. Ambiguous rules and cross-file conflicts cause most problems.
• Only include what Claude can't figure out on its own.