What belongs in a Claude Code project CLAUDE.md, and why can't it guarantee Claude follows an instruction?
answer
- what you would otherwise re-explain
- commands, conventions, layout, always-do rules
- concrete enough to verify
- user message after the system prompt
- context, not enforced configuration
basics
~20 sA project CLAUDE.md holds facts Claude needs every session: build and test commands, conventions, layout and team rules. Claude reads it as context, not enforced configuration, so a rule that must hold belongs in permissions or a hook.
solid answer
~40 s`./CLAUDE.md` (or `./.claude/CLAUDE.md`) is where you write down what you would otherwise re-explain each session: build and test commands, style and naming conventions, where code lives, and "always do X" rules. `/init` drafts one from the codebase, and suggests improvements rather than overwriting when one exists. Keep it concrete ("run `npm test` before committing", not "test your changes") and short, under about 200 lines; move procedures into skills and area-specific conventions into path-scoped rules. The limit is mechanical: Claude Code delivers CLAUDE.md as a user message after the system prompt, so the model reads it and tries to follow it, with no guarantee, especially for vague or conflicting lines. Anything that must hold whatever the model decides, such as never touching `.env`, belongs in a `permissions.deny` rule or a `PreToolUse` hook.
go deeper
Know what goes in a project CLAUDE.md, where it sits, that /init drafts one, and that it is read every session.
Explain why concrete, short instructions are followed more reliably, and how /context shows whether a file loaded.
Show you know CLAUDE.md is delivered as context the model may not follow, and name the layers that enforce: permission rules, hooks, managed settings.
Frame the team trade-off: what is worth a line every session against what belongs in skills, rules or enforced settings, and who reviews the file.
## What a project CLAUDE.md is Every Claude Code session starts with a fresh context window: nothing from yesterday's conversation carries over on its own. A **CLAUDE.md** file is the way you carry knowledge across that gap. It is a plain Markdown file that Claude Code reads at the start of every session and places in the model's context, so each conversation starts already knowing the facts you wrote down. The **project** CLAUDE.md lives at `./CLAUDE.md` or `./.claude/CLAUDE.md` in the repository and is committed, so the whole team shares it. Other scopes exist (an organization-managed file, your personal `~/.claude/CLAUDE.md`, an uncommitted `CLAUDE.local.md`), but the project file is where most teams start. ## What belongs in it The docs' rule of thumb is to write down **what you would otherwise re-explain**. Add a line when Claude makes the same mistake a second time, when code review catches something Claude should have known about the codebase, or when you type the same correction you typed last session. Good content: - **Build, test and lint commands**: the exact invocations, such as `npm test` or `make lint`. - **Conventions that differ from defaults**: naming, indentation, error-handling patterns. - **Project layout**: where API handlers, migrations or fixtures live. - **"Always do X" rules**: run the tests before committing, use the shared logger. - **Architectural decisions** a new teammate would need in order to be productive. What does *not* belong: multi-step procedures (a **skill** loads those on demand), conventions that matter for only one part of the tree (a **path-scoped rule** under `.claude/rules/` loads only when Claude works with matching files), and anything Claude can derive by reading the code, such as a directory listing. Instructions work best when they are **concrete enough to verify**: | Vague | Concrete | | --- | --- | | "Format code properly" | "Use 2-space indentation" | | "Test your changes" | "Run `npm test` before committing" | | "Keep files organized" | "API handlers live in `src/api/handlers/`" | Keep each file short (the docs target **under 200 lines**), grouped under headings and bullets, and free of contradictions: if two instructions conflict, Claude may pick either one. ## Getting a first version: /init and /memory `/init` analyzes the codebase and generates a starter CLAUDE.md with the build commands, test instructions and conventions it discovers. If a CLAUDE.md already exists, `/init` **suggests improvements instead of overwriting it**. Setting the environment variable `CLAUDE_CODE_NEW_INIT=1` switches `/init` to an interactive flow that asks which artifacts to set up and presents a proposal before writing anything. After that, `/memory` lists the CLAUDE.md files for your user and project scopes and opens any of them in your editor, so you can refine the draft with what Claude could not discover on its own. ## Why it is guidance, not enforcement The docs say it plainly: Claude **treats CLAUDE.md as context, not enforced configuration**. Mechanically, Claude Code delivers the content as a **user message after the system prompt**, not as part of the system prompt. The model reads it and tries to follow it, but strict compliance is not guaranteed, least of all for vague or conflicting instructions, a bloated file, or a line that competes with guidance Claude Code adds on its own. So a line like "never edit `.env`" or "never push to main" is a request, not a control. For something that must hold regardless of what the model decides, use the layers the client enforces: - a **`permissions.deny`** rule in a settings file, which refuses the tool call; - a **`PreToolUse` hook**, a script that runs before a tool call and can block it; - for an organization, those same controls delivered through **managed settings**. A managed CLAUDE.md deployed by IT is still guidance; the docs pair it with managed settings precisely because only the settings enforce. If an instruction must run at a fixed point, before every commit or after each edit, write it as a hook rather than a sentence. ## Checking that it loaded When Claude seems to ignore a CLAUDE.md, work through this: 1. Run `/context` and look under **Memory files**. A file that is not listed is a file Claude cannot see. 2. Confirm the file sits somewhere that loads for this session, such as the working directory or a directory above it. 3. Make the instruction more specific, and remove contradicting lines in other instruction files. 4. If it must always hold, move it out of CLAUDE.md into a permission rule or a hook.
- Where should a multi-step release procedure go instead of the project CLAUDE.md, and why?Into a skill. CLAUDE.md loads into every session, so a long procedure costs context even when nobody is releasing and dilutes the always-relevant rules. A skill's body loads only when it is invoked or Claude judges it relevant, which keeps CLAUDE.md to short facts that apply to every task.
- How do you confirm that a CLAUDE.md file actually loaded into a Claude Code session?Run `/context` and check the list under **Memory files**; if the file is missing there, Claude cannot see it. Then check that it sits in a location that loads for the session, such as the working directory or a directory above it, and use `/memory` to open and edit the file.
CLAUDE.md is the briefing note you hand a contractor on day one: it shapes how they work, but it opens and locks no doors. The building's key cards, which here are permission rules and hooks, decide which rooms they can actually enter.
- CLAUDE.md rules are enforced like permission rules
- CLAUDE.md is part of the system prompt, so Claude always obeys it
- A longer, exhaustive CLAUDE.md makes Claude follow it more reliably
- Vague guidance like 'write clean code' is specific enough
- Running /init overwrites the existing CLAUDE.md