D3 · Claude Code › Cluster 1 · Memory & CLAUDE.md

1.4 · Writing an Effective CLAUDE.md

Concise, imperative, structured

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.

LeverDoWhy
SizeTarget under 200 lines per file Loads in full every session; longer = more tokens, lower adherence
StructureMarkdown headers + bullets, grouped by topic Claude scans structure like a reader; sections beat dense prose
SpecificityConcrete, verifiable instructions "Use 2-space indent" is checkable; "format nicely" isn't
Specificity examples straight from the docs:
• "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.

⚠️ Not everything belongs in CLAUDE.md. If an entry is a multi-step procedure or only matters for one part of the codebase, it doesn't belong in always-loaded memory:
  • 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).
Keeping procedural / narrow content out of CLAUDE.md protects your context budget and adherence.
🔑 Consistency matters: contradictory rules across your CLAUDE.md, nested files, and .claude/rules/ make Claude pick one arbitrarily. Review periodically and delete stale or conflicting lines.

DIAGRAM Where should this instruction go?

flowchart TD I["I keep re-explaining X"] --> Q1{"Needed in EVERY session?"} Q1 -->|"no — invoke on demand"| SK["🔵 Skill"] Q1 -->|"yes"| Q2{"Only for certain files/paths?"} Q2 -->|"yes"| RU["🔵 Path-scoped rule
.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

Trap: "Bigger CLAUDE.md = better instructed Claude." → The opposite. Files over ~200 lines cost more context and reduce adherence. Move narrow/procedural content out.
Trap: "Put multi-step procedures in CLAUDE.md." → Multi-step workflows belong in a skill (on-demand); path-specific guidance belongs in a path-scoped rule.
Trap: "Vague guidance is fine, Claude will figure it out." → Write concrete, verifiable rules. "Use 2-space indentation" beats "format code properly."
Trap: "Splitting into @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.