What should be included in CLAUDE.md?

/init

Generates a starting CLAUDE.md from your codebase.

Answer

Keep it to facts Claude should hold in every session: build commands, conventions, project layout, "always do X" rules. Target under 200 lines — longer files consume context and reduce adherence. Multi-step procedures belong in a skill, and instructions that matter for one part of the codebase belong in a path-scoped rule under .claude/rules/.

What it does

CLAUDE.md is where you write down what you would otherwise re-explain. The documented trigger for adding something is concrete:

Claude makes the same mistake a second time
a code review catches something Claude should have known about this codebase
you type the same correction you typed last session
a new teammate would need the same context

Content belongs here if Claude should hold it in every session: build commands, conventions, project layout, "always do X" rules.

Two things belong elsewhere, and the difference is when they load:

A multi-step procedure is a skill — a SKILL.md inside

.claude/skills/<name>/, which Claude reads only when the task calls for it, or when you type /<name>. "How to cut a release" costs nothing on the days you are not cutting one.

**An instruction that only matters for part of the codebase is a path-scoped

rule** — a file in .claude/rules/ with a paths: header, loaded when Claude reads a matching file.

Size is the constraint that shapes the rest, and the documented target of 200 lines is not arbitrary. The file enters the context window at the start of every session, competing for room with your conversation and the files Claude reads. The more instructions it holds at once, the less weight any single one carries — which is why both mechanisms above exist: to keep instructions out of the window until they matter.

When to use it

Write instructions specific enough to check:

Use 2-space indentation
Run `npm test` before committing
API handlers live in `src/api/handlers/`

Rather than:

Format code properly
Test your changes
Keep files organized

The difference is verifiability. A vague instruction gives Claude nothing to comply with, which shows up later as "it ignored my CLAUDE.md".

When not to use it

CLAUDE.md is context, not enforcement. An instruction that must run at a fixed point — before every commit, after each edit — belongs in a hook: a shell command registered against a lifecycle event in .claude/settings.json, which runs whatever Claude decides. See why Claude Code ignores CLAUDE.md for what one looks like.

It is also not a place for content Claude can derive from the codebase itself: directory listings, dependency lists, architecture overviews. Claude Code's own checkup command, /doctor, proposes trimming exactly that — and keeping the pitfalls, the rationale, and the conventions that differ from what the tools would do by default.

Example

Generate a first draft:

/init

Split by topic once the single file grows, using .claude/rules/:

your-project/
├── CLAUDE.md              # or .claude/CLAUDE.md — both load
└── .claude/
    └── rules/
        ├── code-style.md
        ├── testing.md
        └── security.md

This buys tidiness, not context. A rule without a paths: header loads at launch exactly like CLAUDE.md does — same cost, same competition for the window. The saving comes from the header:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

Imports organise, but they do not shrink context:

See @README for project overview and @package.json for npm commands.

Imported files still load at launch. Path-scoped rules are the mechanism that actually keeps content out of context until it is relevant.

Notes for human maintainers cost nothing: an HTML comment on its own line, such as , is stripped before the content reaches Claude and never enters the context window. The exception is a comment inside a fenced code block — that one is part of the example, so it is kept and it does cost you.

Common mistakes

Using imports to reduce context. They do not. Imported files load at launch alongside the file that references them.

Writing procedures. A numbered workflow is a skill. In CLAUDE.md it burns context in every session, including the ones where it is irrelevant.

Letting contradictions accumulate. If two rules disagree, Claude may pick either. Review the file, nested files, and .claude/rules/ periodically.

Documenting what the code already says. Directory layouts and dependency lists are derivable. Rationale and pitfalls are not — those are what the file is for.