CLAUDE.md Guide: What to Put In It and Where

What belongs in CLAUDE.md

Put the facts you would otherwise repeat at the start of every Claude Code session: build commands, test commands, project layout, code style, deployment caveats, known slow tests, and review expectations. The best entries are concrete enough to verify.

Instead of "be careful with tests," write "run npm run build before deploy and use focused tests while iterating." Instead of "follow our style," write the exact formatting, naming, or architectural rule that matters.

Choose the narrowest scope

Claude Code supports multiple locations. Use managed policy files for organization-wide requirements, user files for personal defaults, project files for team-shared repo guidance, and local files for machine-specific or private details.

Do not put personal tokens, customer data, or local-only URLs into a project file that will be committed. Use CLAUDE.local.md and keep it gitignored.

Imports and AGENTS.md

CLAUDE.md can import other files with @path/to/file. That is useful for organization, but it does not reduce context cost because imports are expanded at launch. If a long procedure only matters sometimes, move it to a skill or path-scoped rule instead.

If a repo already uses AGENTS.md, Claude Code docs say Claude reads CLAUDE.md, not AGENTS.md. The bridge is simple: create a CLAUDE.md that imports @AGENTS.md, then add Claude-specific notes below it.

A compact starter shape

# Project Instructions

## Commands
- Install: npm install
- Build: npm run build
- Test: npm test

## Architecture
- Pages live in src/pages.
- Shared components live in src/components.
- Data models live in src/data.

## Working Rules
- Keep edits scoped to the requested behavior.
- Run npm run build before deploying.
- Do not change generated files by hand.

This is intentionally small. Add only instructions that improve future sessions. Remove rules that become obvious from the codebase or drift out of date.