CLAUDE.md (Memory)

The canonical "how to work in this codebase" doc. Claude reads it automatically at session start. Hierarchical: project, parent dirs, and ~/.claude/CLAUDE.md all get merged.

Hierarchy

In order of read, with later overriding/adding:

~/.claude/CLAUDE.md — your personal global (style preferences, tools you have, identity).
<repo>/.claude/CLAUDE.md or <repo>/CLAUDE.md — project-shared (committed).
<repo>/.claude/CLAUDE.local.md — project-local (gitignored, per-user).
Subdirectory CLAUDE.md — scoped to that subtree.

What to put in it

Project orientation. What this repo is, where things live.
Local conventions. Naming, file layout, what NOT to do.
How to run / test. Exact commands (pnpm test, make lint).
Tools / scripts available. Custom CLIs, makefile targets.
Known pitfalls. "Don't edit vendor/; regenerate with make vendor."
Code-style preferences. When automated tooling can't enforce them.

What NOT to put in it

Architecture overview that already lives in the code or in docs/. Better to link.
Anything that changes weekly — keep CLAUDE.md stable.
Long prose. Bullet points and command examples beat paragraphs.

Length

Keep it tight. A few hundred lines tops at the project level. Long CLAUDE.md → dilution (see system-prompts). Claude weights everything roughly equally; bury a rule and it's missed.

Updating from a session

/memory add (or just ask Claude) saves a fact to CLAUDE.md. Use sparingly. Prefer manually curated.

Example skeleton

# project-name

## What this is
One paragraph.

## How to run
- `pnpm install` then `pnpm dev`
- Tests: `pnpm test:unit`

## Conventions
- TypeScript strict; no `any`
- Imports sorted by tool, not manually
- Commit messages: `verb: subject` (no Conventional Commits)

## Do NOT
- Edit files under `generated/`
- Use `npm` — use `pnpm`

CCA-F angle

Hierarchical CLAUDE.md is a frequent topic: "Where should a team-wide rule live vs a personal preference vs a directory-scoped exception?" Maps cleanly onto the 4 locations above.