CLAUDE.md: What to Put in It, Where It Goes, and What /init Wrote for Us (2026)

CLAUDE.md is where you tell Claude Code what it can't work out from the code: how to run the tests, which folder looks unused but isn't, what "revenue" means at your company. Claude reads it at the start of every session, so a good one saves the same correction every day.

The short answer: CLAUDE.md is a Markdown file of instructions that Claude Code loads into every session: build and test commands, conventions, and gotchas. Several can apply at once and they add up rather than replace each other: your organisation's managed file, your ~/.claude/CLAUDE.md, the project's ./CLAUDE.md or ./.claude/CLAUDE.md, a private ./CLAUDE.local.md, and any CLAUDE.md in parent folders load at launch, while those in subfolders load when Claude works there. Run /init to generate one, keep it under about 200 lines, pull other files in with @path, and use hooks for rules that must never be broken: Claude treats CLAUDE.md as context, not enforcement.

What CLAUDE.md is, and isn't

Claude Code has two kinds of memory. CLAUDE.md files are the ones you write; auto memory is "notes Claude writes itself based on your corrections and preferences". Both are advice: "Claude treats them as context, not enforced configuration." The file reaches Claude as text in the conversation: "CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself."

Anthropic is blunt about the limit: "CLAUDE.md is for guidelines, and Claude is allowed to decide a guideline doesn't apply." So "Never read .env" belongs in a hook or a permission rule; CLAUDE.md is for what you'd tell a new colleague.

Where CLAUDE.md files go

How they combine:

• They stack. "All discovered files are concatenated into context rather than overriding each other." They load from broad to specific, "so a project instruction appears in context after a user instruction", and "Within each directory, CLAUDE.local.md is appended after CLAUDE.md".
• Parent folders load at launch, subfolders when needed. "CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded at launch. Files in subdirectories load on demand": "once Claude reads, writes, or edits another file in that subdirectory." In a monorepo, claudeMdExcludes skips files you don't want.
• Rules can target paths. A file in .claude/rules/ with a paths list in its front matter loads only for matching files; "paths is the only field Claude Code reads from a rule". Rules without it load like .claude/CLAUDE.md.
• Comments are free. "Block-level HTML comments (<!-- maintainer notes -->) in CLAUDE.md files are stripped before the content is injected into Claude's context."

To see what actually loaded, run /context all in a session and look at the list under Memory files, or open /memory, which lists your memory files and turns auto memory on or off.

What to put in it

Anthropic's test is that the file "only holds what Claude couldn't work out from the code itself":

• How to confirm work: "the exact test, typecheck, and lint commands, and how to run a single test file"
• Places where the code is misleading, such as "a directory that looks unused but isn't"
• Decisions that aren't in the repo, like how deploys work
• "Anything you've had to correct twice already"

Leave out what Claude can read: the folder structure, what each file does, the language's standard style. Every line costs attention on every task.

An example for a data project

# Analytics repo
 
dbt project for the warehouse, plus Python notebooks in notebooks/. Reports use UTC.
 
## Commands
- Build one model and its tests: dbt build --select <model>+
- Lint SQL: sqlfluff lint models/
- Run Python tests: pytest -q
 
## Conventions
- New models go in models/marts/<domain>/ as fct_ or dim_; staging models only rename and cast.
- Filter timestamps with half-open ranges (>= start and < end), never BETWEEN.
- Exclude test accounts: where not customers.is_test.
- Revenue means paid orders net of refunds; aggregate refunds per order before joining.
 
## Gotchas
- raw.events is append-only and huge: always filter on event_date.
- The prod warehouse login is read-only. Never write DDL; put proposed changes in migrations/ for review.
 
## More
- Metric definitions: @docs/metrics.md

Two notes on it. The @docs/metrics.md line imports that file, so its contents load too. And the read-only line is a reminder, not a guard: the real protection is a read-only database login and a hook that blocks DROP.

How long it should be

"target under 200 lines per CLAUDE.md file". The hard limit is far higher, "Claude Code skips a file over 4 MiB and loads none of it", but a long file loses lines: if Claude keeps ignoring one, Anthropic says "adding IMPORTANT probably won't fix it". Move specialised instructions into skills, which load only when needed, and rules that can't have exceptions into hooks. /doctor prompt-audit (v2.1.283 and later) reviews your instruction files for you.

Imports with @

"CLAUDE.md files can import additional files using @path/to/import syntax." Paths are relative to the file doing the importing, and "Imported files can recursively import other files, with a maximum depth of four hops." Imports inside code spans and code blocks are ignored. The first time a project imports a file from outside it, Claude Code asks you to approve it.

Imports organise; they don't save anything. They "help you organize a long file but don't reduce its context cost", because the imported file loads in full.

/init: what it wrote for a real project

/init writes a CLAUDE.md for you, and "If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it." It also offers to bring over Cursor and Copilot rules, and OpenAI Codex or Gemini CLI configuration. We ran it on 11 November 2026 on a small data project: a README, a Python script that computes weekly revenue by region with DuckDB, and the SQL it runs. It took 14 turns and about $0.21.

The Windows trap first

We typed claude -p "/init" in Git Bash, and Claude's first words were: "The message C:/Program Files/Git/init looks like /init after Git Bash rewrote the path, so I'll run the init skill." Git Bash turns any argument starting with / into a Windows path. Claude worked it out this time; a skill name might not be so lucky:

Our check in Git Bash 5.2.37: the same arguments, with and without the fix.

Prefix the command with MSYS_NO_PATHCONV=1, write //init, or run it from PowerShell. Inside an interactive Claude Code session, typing /init is unaffected.

The file it wrote

# CLAUDE.md
 
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
## What this is
 
A single-script job that computes last week's revenue KPIs by region from the orders export and writes them to `out/weekly_kpis.csv` for the Monday business review.
 
## Commands
 
pip install duckdb pandas     # README lists only duckdb, but .df() needs pandas
python weekly_kpis.py --week 2026-11-02
 
`--week` must be a Monday (ISO `YYYY-MM-DD`); the script exits otherwise. The repo has no tests, linter or build step.
 
## Architecture
 
- `weekly_kpis.py` is a thin runner. It parses `--week`, computes a half-open `[start, start+7d)` range, loads `sql/weekly_revenue.sql`, runs it in an in-memory DuckDB with named parameters (`$start`, `$end`, `$orders`), and writes the result to CSV. All paths are resolved relative to the script's directory, not the CWD.
- `sql/weekly_revenue.sql` holds all the business logic: filter on `paid_at` (half-open range), exclude `is_test` accounts, left-join refunds and net them out, group by `region`, and sort by net revenue descending.
- Inputs: `data/orders.parquet` and a sibling `data/refunds.parquet`. The SQL builds the refunds path by running `replace($orders, 'orders', 'refunds')`, which rewrites **every** occurrence of "orders" in the absolute path. Renaming the data file or putting the repo under a directory whose name contains "orders" will break that lookup.
- `data/` is not in the repo. The warehouse team refreshes it nightly, so don't edit it by hand. `out/` is created on demand.
 
## Conventions
 
- Keep the business logic in the SQL file and the Python as plumbing. Pass values to the SQL as DuckDB named parameters, not by string formatting.

Verbatim, except that the commands' code fence is dropped so the block displays here.

The best lines are the ones Claude couldn't have guessed from a quick look: pandas missing from the README's install line, the Monday rule, and the fragile replace() on the file path. The Architecture section mostly restates the code, which Anthropic's own advice would trim. And it found a real bug, which it reported instead of fixing: "If an order has more than one refund row, it's counted once per refund in count(*), and its amount is added once per refund in sum(o.amount)." Then it asked whether to fix it.

Set CLAUDE_CODE_NEW_INIT=1 and /init runs an interactive setup that also asks about skills and hooks.

AGENTS.md, CLAUDE.local.md and auto memory

• AGENTS.md. Other coding agents read AGENTS.md. Since v2.1.277 Claude Code does too, but "By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it." To use one file for every tool, put @AGENTS.md in your CLAUDE.md. A symlink works elsewhere, but "if you or anyone who clones the repository works on Windows, use the @AGENTS.md import instead."
• CLAUDE.local.md is still supported, for your own notes on a project. "Create it manually and add it to .gitignore."
• Auto memory. "Auto memory is on by default in local sessions." Claude keeps notes per repository, in a memory folder under ~/.claude/projects/, and "The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation." Turn it off with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
• "Remember this" goes to auto memory. If you tell Claude to remember something, "Claude saves it to auto memory. To add instructions to CLAUDE.md instead, ask Claude directly". The old # shortcut is gone: "Removed # shortcut for quick memory entry (tell Claude to edit your CLAUDE.md instead)", in December 2025.

After a long session is compacted, "Project-root CLAUDE.md survives compaction": Claude Code reads it again.

How CLAUDE.md changed, 2025 to 2026

• December 2025: .claude/rules/, and the # shortcut removed.
• February 2026: auto memory, shared across git worktrees of the same repository.
• March 2026: the InstructionsLoaded hook, to see which instruction files loaded, and a 25 KB cap on MEMORY.md.
• September 2026: omitClaudeMd for subagents that should start without your CLAUDE.md files, AGENTS.md read directly, and a startup notice that counts all instruction files together.
• October 2026: size limits applied to files that load on demand.

Your metric definitions don't have to live in CLAUDE.md

"Revenue means paid orders net of refunds" is the kind of line every data team's CLAUDE.md grows. It works in one repository, for one person's Claude Code. It doesn't reach a colleague asking the same question in Claude on the web, or the dashboard the finance team reads.

Fastero is an AI and data platform where people and AI agents work together on a team's data. It keeps the team's shared definitions, the SQL expression behind each metric, which table holds what and how tables join, next to the data connections. Claude Code reads them through Fastero's connector, so the answer agrees with the team's reports, and a definition settled in one conversation is saved for the next. CLAUDE.md can then say what it's best at: how to work in this repository. More on connecting Claude Code to MCP servers and Claude Code for data analysis.

FAQ

What is CLAUDE.md?

A Markdown file of instructions that Claude Code reads at the start of every session: commands, conventions and gotchas for the project. It's context Claude takes into account, not a set of enforced rules.

Where does CLAUDE.md go?

In the project root as ./CLAUDE.md or ./.claude/CLAUDE.md, committed for the team. Your own instructions for every project go in ~/.claude/CLAUDE.md, and private notes for one project in ./CLAUDE.local.md.

What should I put in CLAUDE.md?

What Claude can't work out from the code: the exact build, test and lint commands, misleading parts of the code, decisions that aren't written down, and anything you've corrected twice.

How long should CLAUDE.md be?

Anthropic suggests under 200 lines per file. Claude Code skips a file over 4 MiB entirely, but long files lose lines well before that.

How do I create a CLAUDE.md?

Run /init in Claude Code. It reads the project and writes one, or suggests improvements to an existing one. In Git Bash on Windows, use MSYS_NO_PATHCONV=1 claude -p "/init" or //init, or the argument is turned into a Windows path.

Does Claude Code read AGENTS.md?

Yes, since v2.1.277, but only when there's no CLAUDE.md in the working directory or above it. To use both, import it from CLAUDE.md with @AGENTS.md.

Why is Claude ignoring my CLAUDE.md?

It's guidance, and Claude may decide a line doesn't apply. Check the file loaded with /context all, shorten it, and move rules that must always hold into hooks or permission rules.

What happened to the # shortcut for memory?

It was removed in December 2025. Ask Claude to edit your CLAUDE.md, or open it with /memory.

Sources

Read on 11 November 2026, when the docs described Claude Code 2.1.322; our /init run used Claude Code 2.1.284 on Windows 11, launched from Git Bash:

• Anthropic: Memory and CLAUDE.md, Best practices, The .claude directory, Commands, Environment variables, Features overview, Claude Code changelog