What is CLAUDE.md?

What is a CLAUDE.md?

CLAUDE.md is a plain Markdown file that Claude Code reads automatically at the start of every session. Place it at the root of your project and it acts as a permanent briefing — loaded before Claude Code touches a single line of code.

The right mental model: it’s the message you’d give a new senior engineer on their first day. The tech stack, the exact commands to run, the conventions your team follows, and the rules that aren’t obvious from the code. Not a tutorial. Not a README. Operational context.

Without CLAUDE.md, Claude Code starts each session with no knowledge of your project. It may make assumptions that conflict with your setup, ask questions you’ve answered before, or repeat mistakes you’ve already corrected. CLAUDE.md eliminates that friction permanently.

Every session, Claude Code loads the file into its context. The content counts toward your token usage — one reason to keep it concise and relevant.

How to create a CLAUDE.md

There are two starting points depending on where you are with your project.

New project: create CLAUDE.md at the root manually and fill it in from scratch. Even a ten-line file that lists your stack and your build commands is a meaningful starting point.

Existing project: use the /init command inside a Claude Code session. Claude Code scans the repository, infers what it can, and generates a starter file for you to review and refine. This is the recommended path — it ensures the file reflects reality rather than intentions.

> /init

Claude Code will write a first draft of CLAUDE.md based on what it finds. Review it, trim anything inaccurate, and add the conventions it could not infer.

How CLAUDE.md files are loaded

There is not just one CLAUDE.md. Claude Code discovers and concatenates multiple files every session — understanding how they load is what lets you use them effectively.

Discovery — upward traversal. When you launch Claude Code in a directory, it walks up the directory tree and loads every CLAUDE.md and CLAUDE.local.md it finds along the way. If you are in ~/projects/churn/src/features/, Claude loads instructions from that directory, then src/, then churn/, then projects/. You get inherited context automatically.

Subdirectory files load lazily. Files in directories below your working directory are not loaded at session start. They are loaded on-demand, the first time Claude reads a file in that subdirectory. This keeps the initial context lean on large repos.

Concatenation, not overriding. All discovered files are appended together in load order — none replaces another. Within a single directory, CLAUDE.local.md is appended after CLAUDE.md, so your personal notes land last at that level and take effect when instructions conflict.

The five sources, in load order:

direction: right

anc: "Ancestor dirs\n(CLAUDE.md each)"
global: "~/.claude/CLAUDE.md\n(global)"
proj: "./CLAUDE.md\n(project)"
local: "./CLAUDE.local.md\n(local)"
ctx: "Session context\n(concatenated)"
sub: "Subdirectory CLAUDE.md\n(lazy — on demand)"

global -> ctx: "1 loaded at start"
anc -> ctx: "2 loaded at start"
proj -> ctx: "3 loaded at start"
local -> ctx: "4 loaded at start"
sub -> ctx: "5 on first file access"

Most teams start with a single project-level CLAUDE.md. Add the others when a real need appears — not speculatively.

Importing files with @

CLAUDE.md files can pull in other files using the @path/to/file syntax. The imported content is expanded inline before Claude reads the file — useful for splitting a large CLAUDE.md into focused pieces, or reusing shared rules across projects.

# CLAUDE.md — Churn Model

See @README.md for project overview.
See @package.json for available scripts.

## Git workflow
@docs/git-conventions.md

## Conventions
- Type hints on all public functions

A few rules to know:

• Paths are relative to the file containing the import, not the working directory.
• Imports can chain — an imported file can import others, up to 5 hops deep.
• The first time Claude loads a file from outside the project, it shows an approval dialog listing the files to be imported.

Template

Here is a realistic minimal template for a Python ML project. Inner commands are indented to avoid nested code fence issues when the outer block is rendered.

# CLAUDE.md — Customer Churn Model

## Project
Python 3.11 churn prediction pipeline. Stack: scikit-learn, pandas, FastAPI.
Training data lives in data/raw/ (not committed to git).

## Commands

pip install -e ".[dev]"          # install with dev dependencies
pytest tests/ -v                 # run tests
ruff check src/                  # lint
python src/train.py --config configs/default.yaml  # train

## Conventions
- Type hints on all public functions
- Docstrings in English, numpy format
- Models versioned under models/v{major}/
- Never hardcode secrets — load from .env via python-dotenv
- IMPORTANT: do not modify data/raw/ — treat it as read-only

## Notes for Claude
- Dataset is confidential — never reproduce real rows in examples or comments
- Prefer sklearn Pipeline over manual feature transforms
- The feature engineering logic in src/features/ is intentionally verbose — do not refactor it unless explicitly asked

Sections: Project sets the stage, Commands gives Claude the exact strings it needs to run things, Conventions captures team rules, and Notes for Claude is where you put operational constraints that are not apparent from reading the code.

Dos and don’ts

What makes a CLAUDE.md effective

Boris Cherny (the creator of Claude Code at Anthropic) has distilled what separates useful CLAUDE.md files from ones that get ignored or become outdated:

Write what Claude cannot infer from the code. Claude Code can read your files. It does not need a description of your directory structure or a tour of your modules. What it cannot read is intent: why a decision was made, what constraint a convention exists to enforce, what failure mode a rule is protecting against. Write the why.

Keep it short and actionable. A focused 20-line file outperforms a 500-line document. CLAUDE.md is loaded on every session, which means verbosity has a real cost in tokens and in the attention Claude Code gives to any single instruction.

Use it for operational instructions, not documentation. CLAUDE.md is not a README. It tells Claude Code how to behave. It is not the place to explain the business problem or onboard a human reader.

Update it when something goes wrong. If Claude Code repeats the same mistake twice, that is a signal: add a “do not” rule. CLAUDE.md improves through iteration. Do not try to write the perfect file up front — write a good-enough file and add rules as you discover what Claude Code needs to know.

The IMPORTANT: prefix is worth knowing. When you prepend a rule with IMPORTANT:, Claude Code treats it as higher priority. Use it sparingly, for the rules where getting it wrong has real consequences.

Use HTML comments for maintainer notes. Block-level HTML comments (<!-- like this -->) are stripped from CLAUDE.md before Claude reads it. They cost zero tokens and are invisible to the model — useful for notes to yourself about why a rule exists, or reminders to update a section.

<!-- Last updated 2026-03: added after repeated sklearn mistake — revisit when model changes -->
- Prefer sklearn Pipeline over manual feature transforms