CLAUDE.md Setup Guide for Claude Code

CLAUDE.md is the project memory file Claude Code reads for durable instructions. Use it for commands, architecture boundaries, coding rules, test expectations, and warnings that should apply across sessions. Keep it short, current, and specific to the repository.

Quick Answer

Put a project-level CLAUDE.md in the repository root when the guidance should be shared with the team. Put personal preferences in user-level memory. Use nested CLAUDE.md files only when a monorepo has separate frontend, backend, infrastructure, or package rules.

What To Include

Write rules that Claude Code can act on during real work:

• Exact install, dev, build, lint, test, and type-check commands.
• The package manager and runtime version policy.
• Important directories and ownership boundaries.
• Auth, payment, database, and deployment safety rules.
• Test commands that should run after common changes.
• Known pitfalls that repeatedly cause wrong edits.

Avoid filling the file with every component, every route, or stale sprint notes. If the instruction will not change Claude Code's behavior, it probably belongs somewhere else.

Minimal Template

# CLAUDE.md

## Project Commands

- `pnpm install`: install dependencies
- `pnpm dev`: start local development
- `pnpm build`: production build
- `pnpm lint`: lint checks
- `pnpm test`: run tests

## Architecture Notes

- Keep public marketing pages in `content/pages`.
- Keep tutorial documentation in `content/docs`.
- Do not change auth, payment, or deployment code without a plan first.

## Working Rules

- Prefer small, reviewable diffs.
- Preserve existing URLs unless a redirect is explicitly planned.
- Run the relevant checks before summarizing implementation work.

This is enough for most projects. Add detail only when Claude Code repeatedly needs it.

Monorepo Pattern

For a monorepo, keep the root file broad and place local rules near the code they govern:

repo/
├── CLAUDE.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md
│   └── admin/
│       └── CLAUDE.md
└── packages/
    └── db/
        └── CLAUDE.md

Use the root file for shared commands and safety rules. Use subdirectory files for framework-specific rules, migration commands, generated-code boundaries, or package-specific tests.

Keep It Useful

Updating CLAUDE.md

Update the file when a rule becomes durable:

• A new command replaces an old command.
• The project moves to a different package manager.
• A risky module gets a required verification step.
• A repeated correction should become a standing rule.
• A migration changes the way routes, content, or services are organized.

Do not use CLAUDE.md as a scratchpad for every task. Temporary notes belong in the current conversation or a short handoff document.

Common Mistakes

• Adding secrets, tokens, API keys, or private customer data.
• Writing vague preferences that cannot be verified.
• Letting old commands remain after the project changes.
• Duplicating the entire README instead of writing Claude-specific operating rules.
• Adding too many nested files without explaining which rules override which.

Related Pages

• Basic Usage
• Tools allowlist
• Plan Mode workflow
• Context management
• Architecture analysis

Official Sources

• How Claude remembers your project
• Common workflows
• CLI reference

Next: Tools Allowlist - Control what Claude Code can read, edit, and run.