skip to content

CLAUDE.md & Rules

CLAUDE.md at managed, user, project and local scope, loaded root-down with @ imports, .claude/rules and an AGENTS.md fallback, plus auto memory. Asked because they are context, not enforced config.

part ofClaude Coderead it →
on this pageshow

explore

questions

6

What belongs in a Claude Code project CLAUDE.md, and why can't it guarantee Claude follows an instruction?

level: juniorimportance: must knowfreq 38%

answer

  1. what you would otherwise re-explain
  2. commands, conventions, layout, always-do rules
  3. concrete enough to verify
  4. user message after the system prompt
  5. context, not enforced configuration

basics

~20 s

A 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

for a junior

Know what goes in a project CLAUDE.md, where it sits, that /init drafts one, and that it is read every session.

for a middle

Explain why concrete, short instructions are followed more reliably, and how /context shows whether a file loaded.

for a senior

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.

for a principal

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
open as a page

Where can Claude Code's CLAUDE.md files live, at managed, user, project and local scope, and who shares each one?

level: middleimportance: must knowfreq 24%

basics

~10 s

Managed policy CLAUDE.md applies to every user on the machine, ~/.claude/CLAUDE.md to you in every project, ./CLAUDE.md or ./.claude/CLAUDE.md to the team through git, and a gitignored ./CLAUDE.local.md to you in one project.

open as a page

What does Claude Code's auto memory save, where is it stored, how much loads each session, and how do you turn it off?

level: middleimportance: should knowfreq 16%

basics

~20 s

Auto memory is notes Claude writes about your preferences, corrections and project context, kept per repository in ~/.claude/projects/<project>/memory/. Each session loads the first 200 lines or 25KB of MEMORY.md; switch it off with /memory or autoMemoryEnabled.

open as a page

How does a Claude Code .claude/rules file with paths: frontmatter differ from an unscoped rule, and when does it load?

level: middleimportance: should knowfreq 13%

basics

~20 s

A rule without paths loads every session like .claude/CLAUDE.md; one with a paths glob loads only when Claude works on a matching file, at 2.1.286 by reading it. paths is the only field read, and bad YAML makes the rule unscoped.

open as a page

In a monorepo, Claude Code launched at the root ignores the conventions in packages/billing/CLAUDE.md — how do CLAUDE.md files load, and what do you change?

level: seniorimportance: should knowfreq 14%

basics

~20 s

Claude Code loads CLAUDE.md from the launch directory and its ancestors at startup, but a subdirectory's file only when Claude reads a file there; all are concatenated root-down, never overriding. Launch from the package or use a path-scoped rule.

open as a page

A repository's AGENTS.md stopped reaching Claude Code after a developer added a CLAUDE.local.md — why, and how do you fix it?

level: seniorimportance: nice to knowfreq 7%

basics

~10 s

Since 2.1.277 Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above, and CLAUDE.local.md counts. Set Project instructions to claude-md-and-agents-md, or import @AGENTS.md.

open as a page