ailiteracynepal 🇳🇵
Text size

Chapter 02 · Section II · 12 min read

2.2 Memory: CLAUDE.md hierarchy and content

CLAUDE.md is how a project tells Claude Code what it should know before doing anything. Where the files live, what belongs in each, and how the hierarchy composes.

Every non-trivial project has invariants — conventions, sharp edges, hidden gotchas — that a new contributor has to learn. CLAUDE.md is where you write them down so Claude Code reads them at the start of every session in the repo. It is a README.md for the model.

The file hierarchy

Claude Code looks in five places, from broad to narrow:

  1. ~/.claude/CLAUDE.md — user-global. Your personal conventions across every project.
  2. <repo>/CLAUDE.md — repo root. Team defaults for this project.
  3. <repo>/<subdir>/CLAUDE.md — subdirectory-scoped memory. Applies when work is happening inside that subtree.
  4. <cwd>/CLAUDE.md — the current working directory, if different.
  5. Imports — a CLAUDE.md can import others via @path/to/another.md.

All applicable files are loaded into the session’s context on start. Nested files add specificity; they do not override the parent.

What belongs in CLAUDE.md

Good candidates:

  • Directory map. “The frontend lives in apps/web. The design system lives in packages/ui. Do not touch legacy/.”
  • Conventions. “We use tabs. Tests use vitest. HTTP handlers throw, never return errors.”
  • Common commands. “Tests: pnpm test. Type check: pnpm typecheck.”
  • Sharp edges. “The auth token in .env.example is a real dev-only token; do not swap it for a placeholder.”
  • Non-obvious file relationships. “Every route in src/pages has a matching entry in src/nav.ts.”

Bad candidates:

  • Things a README.md already says. Reference it instead: @README.md.
  • Long prose. CLAUDE.md should be a checklist, not an essay.
  • Anything that changes weekly. It will rot; contributors will not update it.

Imports and composition

# Project conventions

Frontend patterns: @packages/ui/CLAUDE.md
API patterns: @apps/api/CLAUDE.md

## Sharp edges

- `apps/legacy` is frozen; do not modify.
- The webhook secret in `.env.example` is intentional.

Imports are resolved relative to the file that mentions them. Circular imports are ignored. Depth is bounded to avoid infinite loops.

Editing memory from a session

The /init command bootstraps a CLAUDE.md from the current repo. The /memory command opens the resolved memory in an editor for quick edits.

Check your understanding

Quick check

—

Which of the following is the highest-leverage thing to put in a project's CLAUDE.md?