CLAUDE.md is your persistent memory for project context. Claude reads it at the start of every conversation, so you only explain things once.
What CLAUDE.md Does
- Loaded automatically when Claude opens a project
- Defines coding style, architecture, commands
- Replaces repeated prompting with permanent instructions
- Works across all Claude interfaces (CLI, API, desktop)
File Locations
| Location | Scope | Use Case |
|---|---|---|
./CLAUDE.md | Project | Project-specific conventions |
~/.claude/CLAUDE.md | Global | Personal preferences |
./.claude/rules/*.md | Modular | Domain-specific rules |
Project-level takes precedence. Global provides defaults.
Essential Sections
A good CLAUDE.md answers: What is this? How do I work on it? What conventions apply?
# project-name
Brief description of what this project does.
## Commands
- `npm run dev` - Start development server
- `npm test` - Run tests
- `npm run lint` - Check formatting
## Architecture
| Path | Purpose |
|------|---------|
| `src/` | Application code |
| `tests/` | Test files |
| `docs/` | Documentation |
## Conventions
- Use TypeScript strict mode
- Components in PascalCase
- Utilities in camelCase
- Tests co-located with source files
## Style
- Prefer composition over inheritance
- No default exports
- Explicit return types on public functions
Real-World Example
From a production Next.js project:
# acme-dashboard
Internal analytics dashboard. Next.js 14, TypeScript, Prisma.
## Commands
| Command | Purpose |
|---------|---------|
| `pnpm dev` | Local dev (port 3000) |
| `pnpm db:push` | Push schema changes |
| `pnpm db:studio` | Open Prisma Studio |
| `pnpm test` | Vitest |
| `pnpm lint` | ESLint + Prettier |
## Architecture
| Path | Purpose |
|------|---------|
| `app/` | Next.js app router pages |
| `components/` | React components |
| `lib/` | Shared utilities |
| `prisma/` | Database schema |
| `actions/` | Server actions |
## Conventions
- Server components by default
- `use client` only when needed
- Server actions for mutations
- Zod for all validation
- shadcn/ui for components
## Database
- PostgreSQL via Supabase
- Run `pnpm db:push` after schema changes
- Never edit migrations manually
## Testing
- Unit tests with Vitest
- E2E tests with Playwright in `e2e/`
- Test files: `*.test.ts` next to source
Anti-Patterns
| Problem | Why It Fails | Fix |
|---|---|---|
| Over 500 lines | Context bloat, slower responses | Split into .claude/rules/ |
| Vague instructions | “Write good code” is useless | Be specific: “Use Zod for validation” |
| Duplicating docs | README content in CLAUDE.md | Reference docs, don’t copy |
| No commands | Claude guesses wrong commands | List exact commands to run |
| Explaining basics | “JavaScript is a language…” | Assume Claude knows fundamentals |
Modular Approach
Large projects benefit from splitting rules by domain. Use .claude/rules/ for focused instruction sets:
.claude/
rules/
frontend.md # React/CSS conventions
api.md # API design rules
database.md # Schema conventions
testing.md # Test patterns
Each file can specify which paths it applies to:
---
paths: "{app/**/*,components/**/*}"
---
# Frontend Rules
- Use Tailwind, no inline styles
- Extract components at 50+ lines
- Props interface above component
Claude loads relevant rules based on which files you’re working on.
Keep It Updated
CLAUDE.md is living documentation:
- Add conventions as you establish them
- Remove outdated instructions
- Note exceptions and edge cases
- Update commands when they change
A stale CLAUDE.md causes more confusion than no CLAUDE.md.
Quick Start Template
# project-name
One line describing the project.
## Commands
- `command` - What it does
## Architecture
| Path | Purpose |
|------|---------|
| `src/` | Source code |
## Conventions
- Key convention 1
- Key convention 2
Start minimal. Add rules when Claude makes wrong assumptions.
related
- AGENTS.md — how to write instructions for AI coding agents
- Claude Code Setup — complete installation and configuration guide
- ACE Framework — implement six-layer cognitive architecture for mission and values
- Auto-Activating Skills — configure skills to trigger automatically based on keywords
- Prompt Engineering — structure prompts that make AI coding agents 30-40% more effective