CLAUDE.md: a useful project handbook for Claude Code

What CLAUDE.md does

CLAUDE.md contains durable project instructions Claude Code considers while working. It suits architecture boundaries, common commands and quality requirements. It provides context; it is not a technically enforced security policy.

Choose the right scope

Organisation policy, personal preferences and project rules belong at different scopes. Version shared project conventions and keep machine-specific details out of the team document.

Write concrete instructions

Name the test command, the location of domain logic and prohibited actions. A verifiable rule such as “run integration tests after payment changes” is more useful than “test thoroughly”.

Keep context compact

Do not paste an entire internal handbook into one file. Point to focused documents or path-specific rules. Less noise makes important boundaries easier to notice.

No. It summarises what the agent needs in almost every session.

Use a hierarchy

A root file can cover general rules while a specialised folder adds its own instructions. Regularly inspect which instruction files are actually active.

Manage it like code

Assign an owner, review changes and remove stale commands. A short quarterly review prevents the agent from relying on obsolete architecture.

# Project context - Domain logic lives in src/domain/ - Run pnpm test after behaviour changes - Never add secrets or production data

Make CLAUDE.md for Claude Code verifiable

The decision review for CLAUDE.md for Claude Code first focuses on one project rule covering build, tests and directory-scoped instructions that Claude Code must follow. Define the acceptable user outcome, essential inputs and authorised approver for CLAUDE.md for Claude Code before the trial starts. Keep the first CLAUDE.md for Claude Code trial small enough to separate causes from effects.

Build evidence for CLAUDE.md for Claude Code around one realistic successful route and also simulate an obsolete command, conflicting CLAUDE.md layers and a local exception that remains invisible. For every CLAUDE.md for Claude Code check, record the expected outcome, visible evidence and recovery action when it fails. The final decision question for CLAUDE.md for Claude Code is: “Does CLAUDE.md replace documentation?”

CLAUDE.md for Claude Code: from trial to everyday operation

Assign CLAUDE.md for Claude Code one operational owner, one subject reviewer and a clear fallback route. Treat the CLAUDE.md for Claude Code checklist as separate evidenced steps, so punctuation or phrasing never becomes part of the process logic. Ask the relevant user to complete CLAUDE.md for Claude Code without spoken help and record every point that still needs explanation or manual recovery.

Keep change rights, logging, support and review dates for CLAUDE.md for Claude Code in one operating plan. Repeat the CLAUDE.md for Claude Code trial after a change to source data, configuration, model, integration or user role. Expand CLAUDE.md for Claude Code only when the team can also detect, contain and recover an obsolete command, conflicting CLAUDE.md layers and a local exception that remains invisible.

Stop the CLAUDE.md for Claude Code rollout while an obsolete command, conflicting CLAUDE.md layers and a local exception that remains invisible is not reported visibly and recoverable by the assigned owner.