Write an Effective CLAUDE.md

CLAUDE.md is persistent project context. Claude Code reads it at the start of a session, so it should contain only instructions that matter often.

Start with /init

Run:

/init

Then edit the generated file down to the rules Claude cannot reliably infer from the codebase.

Include

• Project-specific build, test, and typecheck commands.
• Code style rules that differ from defaults.
• Repository etiquette, branch naming, and PR conventions.
• Non-obvious architecture decisions.
• Local development gotchas.
• Common failure modes.

Exclude

• Long tutorials.
• File-by-file codebase descriptions.
• Generic advice like “write clean code.”
• API documentation that should be linked instead.
• Details that change frequently.

Keep it short

Bloated CLAUDE.md files compete with your actual prompt. The official target is under 200 lines per file. Longer files still load in full, but adherence drops.

The docs are blunt about the symptom: if Claude keeps doing something you don’t want despite having a rule against it, the file is probably too long and the rule is getting lost. Shouting (capitals, “IMPORTANT”) is not the fix. Cutting is.

Treat it like code: review it, prune it, and update it when behavior proves the instructions are not working. Run /doctor to get proposed trims and to move task-specific material into skills that load on demand.

Edits apply at session start

CLAUDE.md is read when the session starts, not on every turn. If you add a rule mid-session, the current conversation will not see it.

To pick up the change:

• /compact re-reads the project-root CLAUDE.md from disk and re-injects it.
• /clear or a restart starts fresh with the new file.

Nested CLAUDE.md files in subdirectories load when Claude reads files in those directories.

Useful locations

• ~/.claude/CLAUDE.md: personal instructions for all sessions.
• ./CLAUDE.md: shared project instructions, usually committed.
• ./CLAUDE.local.md: personal project notes, usually ignored by git.

Import related files

Use @path imports for supporting material:

See @README.md for project overview.
See @docs/git-workflow.md for commit and PR conventions.