CONCEPT Adherence is a writing problem
Because CLAUDE.md is context, not enforcement (1.1), how reliably Claude follows it depends on how you write it. The docs name three levers: size, structure, and specificity. Get these right and adherence climbs; get them wrong and Claude picks arbitrarily among vague or conflicting rules.
| Lever | Do | Why |
|---|---|---|
| Size | Target under 200 lines per file | Loads in full every session; longer = more tokens, lower adherence |
| Structure | Markdown headers + bullets, grouped by topic | Claude scans structure like a reader; sections beat dense prose |
| Specificity | Concrete, verifiable instructions | "Use 2-space indent" is checkable; "format nicely" isn't |
• "Use 2-space indentation" > "Format code properly"
• "Run
npm test before committing" > "Test your changes"• "API handlers live in
src/api/handlers/" > "Keep files organized"CONCEPT What belongs — and what doesn't
CLAUDE.md is for the facts Claude should hold in every session. Add to it when you find yourself re-explaining something: Claude repeats a mistake, a review catches something Claude should have known, you retype the same correction, or a new teammate would need the same context.
- Path-specific? → a path-scoped rule in
.claude/rules/(loads only when Claude touches matching files). - A repeatable workflow you invoke on demand? → a skill (loads only when relevant).
.claude/rules/ make Claude pick one arbitrarily. Review periodically and delete stale or
conflicting lines.DIAGRAM Where should this instruction go?
.claude/rules/"] Q2 -->|"no — global fact"| Q3{"Concrete & verifiable?"} Q3 -->|"no"| RW["✏️ Rewrite it specifically"] Q3 -->|"yes"| CM["🟢 Add to CLAUDE.md
(< 200 lines, headers + bullets)"] RW --> CM classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef alt fill:#e2e3f3,stroke:#6c63ff,color:#2a2a6a; class CM ok; class SK alt; class RU alt;
CODE A well-structured CLAUDE.md
Short, grouped by headers, every line concrete and imperative.
# CLAUDE.md — keep under ~200 lines ## Commands - Build: `npm run build` - Test: `npm test` — run before every commit - Lint: `npm run lint -- --fix` ## Code style - 2-space indentation, no tabs - Prefer named exports; no default exports - Errors use the `AppError` class in `src/errors.ts` ## Architecture - API handlers: `src/api/handlers/` - DB access only through `src/db/repo.ts` (never raw SQL in handlers) # Multi-step release steps? → a skill. # Rules only for src/api/**? → .claude/rules/api.md with `paths:` frontmatter.
TRADE-OFFS Cram everything in vs. right-size the memory
✅ Lean, specific CLAUDE.md
- Loads fast, cheap on tokens every turn
- High adherence — nothing vague to misread
- Procedures & path rules live where they load lazily
⚠️ Kitchen-sink CLAUDE.md
- Big file → more context cost every session
- Vague/duplicated lines → arbitrary behavior
- Buries the rules that actually matter
EXAM TRAPS
@imports shrinks a too-big CLAUDE.md's context." →
Imports still load at launch. To trim context, use path-scoped rules or delete content — not imports.PRACTICE
Q1 · Name the three levers that drive CLAUDE.md adherence.
Size (target < 200 lines), structure (Markdown headers + bullets), and specificity (concrete, verifiable instructions). They matter because CLAUDE.md is context, not enforced config.
Q2 · A 12-step deployment runbook keeps coming up. Does it go in CLAUDE.md?
No. A multi-step procedure invoked on demand belongs in a skill, which loads only when relevant — keeping it out of every-session context.
Q3 · Rewrite "keep the code clean" so Claude can actually follow it.
Make it concrete and verifiable, e.g. "Use 2-space indentation, named exports only, and run
npm run lint -- --fix before committing." Specific rules can be checked; vague ones get ignored.