Use CLAUDE.md for stable repository guidance, not a dump of every fact. Keep it short enough that important rules stay visible and update it when the project changes.
1. Start from recurring mistakes
List the instructions you repeat in many sessions: package manager, test command, folder boundaries, generated files, style rules and forbidden changes.
2. Write commands exactly
Record the real install, lint, typecheck and test commands. If a command only applies to one package or directory, say where it should run.
3. Explain architecture in decisions, not history
Describe which module owns what, where new code normally belongs, and which interfaces must remain stable. Avoid a long narrative about how the repository evolved.
4. Add safety boundaries
Name secrets, production files, migrations, dependency changes or destructive commands that require approval. Tell Claude Code what it may inspect but should not modify.
5. Test the file in a fresh session
Start a new Claude Code session and ask it to summarize the repository rules before editing. If it misses a critical rule, rewrite CLAUDE.md to make that rule clearer.
Before changing anything, read CLAUDE.md and summarize the five rules that most constrain this task. Then inspect the relevant files, propose a minimal plan, and stop before editing if the task conflicts with a repository rule.
Turning CLAUDE.md into a giant handbook; documenting commands that no longer work; putting one-off task instructions into permanent memory; assuming a rule is effective without testing a new session.
Finish check
A new session can identify the correct commands, architecture boundaries and approval points before touching code.