5 CLAUDE.md Patterns That Make AI Actually Follow Your Rules

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:

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 for more.