# 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. CLAUDE.md is read automatically every session. Write it once, benefit from it indefinitely. You will never need to re-explain your project at the start of a conversation. ## 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. ```bash title="Inside a Claude Code session" > /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:** | Source | Path | Scope | Committed? | |--------|------|-------|-----------| | Managed | set by organization | All machines | N/A | | Global | `~/.claude/CLAUDE.md` | Your machine | No | | Project | `./CLAUDE.md` | Current repo | Yes | | Local | `./CLAUDE.local.md` | Your machine only | No — gitignore it | | Path rules | `.claude/rules/*.md` | On-demand, by glob | Yes | ```d2 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. ```markdown title="CLAUDE.md" # 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. Use `@` imports to keep your project-level `CLAUDE.md` short while keeping detailed rules (deployment steps, dataset conventions) in their own files that only get included when referenced. ## 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. ```markdown title="CLAUDE.md" # 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. Never put secrets, passwords, or API keys in CLAUDE.md. This file is committed to git and visible to anyone with access to the repository. ## Dos and don'ts | Do | Don't | |----|-------| | List exact install, build, test, and lint commands | Describe file structure — Claude can read the repo | | Write team conventions Claude cannot guess from the code | Write general programming advice | | Add "never do X" rules for known failure modes | Repeat information already in the README | | Keep it under 100 lines | Let it grow unbounded | | Commit `CLAUDE.md` to git | Commit `CLAUDE.local.md` — add it to `.gitignore` | | Use `IMPORTANT:` to flag critical rules | Include secrets or API keys | ## 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 (``) 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. ```markdown - Prefer sklearn Pipeline over manual feature transforms ``` Boris Cherny (the creator of Claude Code at Anthropic) shares 72 practical tips on how he uses Claude Code day-to-day, including his team's CLAUDE.md methodology, at [howborisusesclaudecode.com](https://howborisusesclaudecode.com/).