CLAUDE.md
Also: claude.md file, project memory file, Claude Code memory
CLAUDE.md is a Markdown file you add to your project root that Claude Code reads automatically at the start of every session. Its contents are appended to your prompt — so whatever is in there, Claude already knows before you type a single thing. Think of it as an onboarding doc for your codebase: your tech stack, your dev commands, your code conventions, and any corrections you've had to make more than once. There are two levels: project-level (root of your project, checked into version control so your whole team benefits) and user-level (your personal config folder, applies across all projects, for preferences that are yours alone). A few practical things most people miss: (1) Don't start with one. Use Claude Code for a while first and notice where you keep course-correcting. When you know what to include, run /init and Claude will generate one from your session history. Keeps it focused instead of bloated. (2) If you catch yourself correcting Claude repeatedly — say, "use server actions, not API routes" — tell Claude to save that rule to CLAUDE.md. It won't rediscover it the next session. (3) CLAUDE.md is for instructions. Hooks are for enforcement. If it needs to happen every time without fail, put it in a hook — not here. Things in CLAUDE.md usually happen. Things in hooks always happen.
Related concepts
Where CLAUDE.md shows up
5 articlesMost teams let one developer set up the .claude folder and never discuss it again. These are the decisions you should make together — and what breaks when you skip them.
CLAUDE.md tells Claude what you want. Hooks make certain behaviors guaranteed. Most teams only use one. Here is how to know which one you actually need.
Everyone says to set up CLAUDE.md. Nobody shows you what to write. Here are four real starting templates — for a solo project, a team backend, an agency client repo, and an ops/admin setup — with annotations explaining what each section does.
The setup you build for yourself and the setup you build for a client are two different things. One optimizes for your preferences. The other has to survive your departure.
Most teams set up CLAUDE.md once and never touch it again. Three months later, Claude is ignoring parts of it, following instructions that no longer apply, and producing inconsistent output for reasons nobody can identify.