CLAUDE.md is the file Claude reads at the start of every session. Write one so Claude knows your commands, conventions, and guardrails without being told each time.
Why: CLAUDE.md is loaded automatically into every session, so anything in it is knowledge Claude always has. When: run /init in a new project — it inspects the codebase and drafts one for you. Where: it lands at the repo root; edit it from there.
/init # scans the project and writes a starter CLAUDE.md
# Later, edit memory at any time:
/memory # open CLAUDE.md (and other memory files) in your editorWhy: the best CLAUDE.md is short and high-signal — the commands, conventions, and "never do this" rules that save you repeating yourself. When: add a rule the moment you catch yourself correcting Claude twice. Where: keep it scannable; a wall of text dilutes the important lines.
# Project: Billing API
## Commands
- Build: pnpm build
- Test: pnpm test (NEVER use npm — this repo is pnpm only)
- Lint: pnpm lint --fix
## Conventions
- TypeScript strict mode; no `any`.
- Money is stored in integer cents, never floats.
## Don't
- Don't edit files under `generated/` — they are built.
- Don't commit `.env` or anything with secrets.Why: memory cascades from several locations, so you can set personal rules, shared project rules, and folder-specific rules. When: put team conventions in the project file (committed to git) and personal preferences in the user file. Where: subdirectory CLAUDE.md files load only when Claude works in that folder.
./CLAUDE.md — Project memory, committed to git and shared with your team. The main one.~/.claude/CLAUDE.md — Personal memory across all your projects (your own preferences).sub/dir/CLAUDE.md — Loaded only when Claude works inside that subdirectory — for area-specific rules.Precedence (all are merged; more specific wins):
~/.claude/CLAUDE.md (you, everywhere)
./CLAUDE.md (this project, whole team)
./packages/api/CLAUDE.md (only when working in packages/api)Why: instead of one giant file, import focused docs so memory stays organized and reusable. When: pull in a style guide or architecture note with @. Where: imports work in any CLAUDE.md and are resolved relative to it.
# Project memory
See @docs/architecture.md for the system overview.
Follow the conventions in @docs/code-style.md.
Personal overrides: @~/.claude/my-preferences.md