CLAUDE.md and Project Memory
Project-level instructions the agent loads automatically. The single highest-leverage file in your repo when you work this way.
Every time you launch Claude Code in a directory that has a CLAUDE.md, the file is injected into the agent's context. It's how you teach the agent your conventions, your stack, and your taste — once, durably.
Good CLAUDE.md files are short and specific: things the agent could not figure out by reading the code. Bad CLAUDE.md files restate what's obvious from package.json. The /init slash command writes a starter file you then prune.
Run /init in a real project
From inside a project with code, type /init. The agent reads your repo and proposes a CLAUDE.md.
/initVerifyA CLAUDE.md appears at your project root with sections like 'Stack' and 'Conventions'.Trim aggressively
Open the generated file. Delete anything obvious from package.json (frameworks, scripts). Keep only: hidden conventions, deploy quirks, and rules you've corrected the agent on before.
# Project notes ## Stack quirks - We use pnpm workspaces; never run `npm install`. - The mobile package depends on a private registry — set NPM_TOKEN before installing. ## House style - Tests live next to source as `*.test.ts`, not in `__tests__`. - Prefer named exports; default exports only for Next.js page files. - No console.log in committed code; use the logger in lib/log.ts.VerifyYour CLAUDE.md is under ~30 lines and every line says something the agent could not infer.Test that it took
Quit and relaunch claude in the same directory. Ask a question whose answer requires the file.
What package manager does this repo use, and why?VerifyThe agent answers "pnpm — npm install would corrupt the workspaces" without reading any other file.Add a personal layer
Create ~/.claude/CLAUDE.md for cross-project preferences (your tone, your default test framework). It loads on every project, layered under the project file.
# My preferences - Keep responses terse; no end-of-turn summaries. - Default to TypeScript when language is ambiguous. - When suggesting libraries, prefer the smallest dependency that works.VerifyThese rules now apply in every Claude Code session you open.