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. If Claude keeps missing a rule, the file may be too long or the rule may be ambiguous.

Treat it like code: review it, prune it, and update it when behavior proves the instructions are not working.

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.