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
6 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.
Two Claude Code releases 36 hours apart changed defaults on repos and sessions you already run. v2.1.277 (September 18) reads AGENTS.md when a project has no CLAUDE.md. v2.1.278 (September 19) moves auto mode's safety checks onto the server for Enterprise and API accounts and stops charging for them — unless a gateway in the path breaks it. Here is what loads when, and what to check.