A CLAUDE.md That Claude Actually Follows

Why long CLAUDE.md files get ignored

Lesson 7 introduced CLAUDE.md. Now let's make it work. The most common failure isn't a missing instruction. It's a file so long and generic that the important lines drown. Every line competes for attention, on every request.

The test for every line

Keep a line only if all three are true:

1. Claude can't easily discover it by reading the repo (or would get it wrong).
2. It matters in most sessions, not just one rare task.
3. It's specific enough to act on. "Write clean code" fails. "Money is integer cents; never floats" passes.

Good candidates: build and test commands, misleading spots in the code, decisions made outside the repo, and anything you've had to correct twice.

Path-scoped rules: guidance that loads only where it applies

For instructions about one part of the codebase, use .claude/rules/. Each .md file there loads every session, or, with paths frontmatter, only when Claude touches matching files:

---
paths:
  - "src/api/**/*.ts"
---
# API rules
- Every handler validates input with the zod schema in `src/api/schemas/`.
- Return errors as `{ error: { code, message } }`, never bare strings.

Your React rules don't need to load while Claude fixes a SQL migration, and with path scoping they won't.

When emphasis means "make it a hook"

If you catch yourself adding IMPORTANT, ALL CAPS or "NEVER EVER" to a line, that line is telling you something: it needs enforcement, not a sterner request. Convert it to a hook (Unit 7) or a permission deny rule (Lesson 15).

Audit and trim

• /context all shows exactly which memory files loaded.
• /doctor flags oversized instruction files and suggests trims, especially content Claude could derive from the code.
• /memory opens every memory file for editing.

A healthy project CLAUDE.md is usually well under 200 lines. Many great ones are under 50.

# Acme Web

## Commands
- Dev: `pnpm dev` · Test one file: `pnpm test -- <path>` · Types: `pnpm tsc --noEmit`

## Must-knows
- Feature flags live in `flags.ts`; never hardcode `if (env === "prod")`.
- `packages/ui` is published to npm. Changes need a changeset (`pnpm changeset`).
- E2E tests need `pnpm db:seed` first.

## Done means
- Typecheck clean, affected tests pass, and you've said what you verified.

Check your understanding