CLAUDE.md Best Practices: Help Claude Code Follow Project Rules

CLAUDE.md stores human-written rules that should apply to every relevant session; Claude Code builds automatic memory from prior work, and users can review it. Neither replaces source code or formal documentation.

Good candidates include test commands, repository conventions, architectural constraints, and environment pitfalls the tool cannot reliably infer. General programming knowledge, complete API documentation, and file-by-file explanations only consume context.

Run /init after starting Claude Code in the project root directory, and the tool will generate a first draft based on the build system, test framework, and project structure. Generated content must be reviewed by project maintainers.

The first draft contains candidate rules. Remove content Claude can derive from package.json, Makefile, or the code itself, leaving only constraints that materially affect execution correctness.

Each rule should answer "what to do, when" and "how to verify it." "Write high-quality code" has no operational value; "run pnpm typecheck after modifying TypeScript" is directly actionable.

If removing a line would not make Claude more likely to err, remove it. Long rule sets dilute the user's current prompt and the constraints that matter most.

~/.claude/CLAUDE.md suits personal preferences that span projects, the project-root CLAUDE.md holds team rules, and CLAUDE.local.md holds unshared project notes. Subdirectory rules load on demand when Claude accesses the corresponding directory.

In a monorepo, do not pile every package command into the root file. Keep only repository-wide rules at the root, and maintain package-specific test, build, and architecture constraints in each package directory.

CLAUDE.md can import additional files with @path. Rules in .claude/rules/ that have paths frontmatter load on demand for matching files; rules without paths enter the context unconditionally at startup.

Imports should point to stable, short documents. Do not recursively import large README trees, and do not import personal files that may contain keys.

Use /context to see which CLAUDE.md files and rules entered the current context. If a rule does not take effect, check the launch directory, file location, conflicting instructions, and file length first.

Maintain CLAUDE.md like code: add the smallest necessary rule when behavior deviates, and remove redundant rules when default behavior is already correct. Move deterministic enforcement to Hooks instead of making the wording increasingly forceful.