Module 2: CLAUDE.md & Project Memory
CLAUDE.md is the most impactful 10 minutes you'll spend on any project. It's the difference between Claude Code guessing at your conventions and Claude Code knowing them.
Think of It as Onboarding Docs
A markdown file at your repo root that Claude Code reads automatically at the start of every session. It's like onboarding docs for your AI agent instead of a new hire.
No special syntax. No schema. Just markdown that describes what Claude Code needs to know to work effectively in your codebase.
For the mechanics of the memory hierarchy (project CLAUDE.md, user CLAUDE.md, modular rules, auto-memory), path-specific rules with paths: frontmatter, and commands like /init and /memory, see the official CLAUDE.md documentation.
What to Include (and Why)
Your CLAUDE.md should cover what would surprise someone competent who just cloned the repo. Each type of content serves a specific purpose:
Project overview — One paragraph so Claude understands the domain and deployment target. Without this, it makes generic assumptions about your architecture.
Build / test / lint commands — The exact commands, not "use your package manager." This enables the verify loop (Module 6): Claude can't run your tests if it doesn't know the command.
Architecture — Key directories, important patterns, how data flows. This prevents Claude from putting new code in the wrong place or creating redundant abstractions.
Naming conventions — If you have opinions, state them. Claude defaults to reasonable conventions, but "reasonable" might not match yours.
Gotchas — Things that break in non-obvious ways, workarounds, known issues. These are the things a new hire would trip over — and Claude will trip over them too.
Deployment target — Where this runs, what the constraints are. "Static export to Netlify" vs. "serverless on Lambda" vs. "containers on Kubernetes" changes how Claude approaches solutions.
What NOT to Include
- Obvious things the code already says. Don't describe every file if
package.jsonscripts are self-explanatory. - Long documentation. Link to it instead of pasting it in.
- Secrets or credentials. CLAUDE.md gets committed to version control.
- Frequently changing info. Version numbers, sprint goals, things that go stale fast.
30 Good Lines Beat 200 Stale Ones
Keep it tight. A concise, accurate CLAUDE.md beats a comprehensive one that's half-outdated. Every line in CLAUDE.md consumes context in every session. Include what Claude needs; link to docs for everything else.
Template
# CLAUDE.md
## Project
[One-line description. What is this, who uses it, where does it run.]
## Commands
\`\`\`bash
npm run dev # Local dev server
npm run build # Production build
npm test # Run test suite
npm run lint # Lint + format check
\`\`\`
## Architecture
- `src/app/` — Next.js App Router pages
- `src/lib/` — Shared utilities, API clients
- `src/components/` — React components (colocated tests)
- `prisma/` — Database schema and migrations
## Conventions
- [Naming, patterns, do's and don'ts]
- [Anything that would surprise a new contributor]
## Deployment
[Target platform, build output, environment variables needed]Personal Overrides
You can create a .claude.local.md file alongside your CLAUDE.md for personal overrides that aren't committed to version control (add it to .gitignore). This is useful for individual preferences that shouldn't affect the team — your preferred commit message style, local environment quirks, or tools you personally use.
Your user-level CLAUDE.md (~/.claude/CLAUDE.md) applies to all your projects. Use it for preferences that span projects: formatting opinions, personal workflow shortcuts, or global conventions.
Modular Rules for Large Projects
For large codebases where different areas follow different conventions, split your guidance into .claude/rules/*.md files. Each can be scoped to specific directories with paths: frontmatter. This keeps rules focused and avoids bloating the root CLAUDE.md.
For example: .claude/rules/api.md scoped to src/api/** with REST conventions, .claude/rules/components.md scoped to src/ui/** with React patterns.
See the official docs on modular rules for the full syntax and configuration options.