CLAUDE.md Best Practices

Table of content

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.

Next: Getting Started with Your Personal OS

Topics: claude-code prompting setup