CLAUDE.md Reference
The CLAUDE.md file is the heart of your pair programming setup. It provides context, instructions, and guidelines that help your coding assistant understand your project.
What is CLAUDE.md?
CLAUDE.md is a Markdown file placed at the root of your project that coding assistants read to understand your project context. It's like a README specifically for your pair programmer.
Automatically Loaded
Claude Code and compatible coding assistants automatically read CLAUDE.md when you start working in a project.
Persistent Context
Unlike chat history that resets, CLAUDE.md provides persistent context across sessions.
Recommended Structure
A well-organized CLAUDE.md follows this structure:
1. Project Overview
Brief description of what the project does, its purpose, and key features.
2. Commands
Common commands for development, testing, building, and deployment.
3. Architecture
Project structure, data flow, key directories, and important files.
4. Coding Standards
Style guide, naming conventions, patterns to follow, and anti-patterns to avoid.
5. Tech Stack
Languages, frameworks, libraries, and tools used in the project.
Example CLAUDE.md
# CLAUDE.md
This file provides guidance to Claude Code when working with this repository.
## Project Overview
MyApp - A Next.js e-commerce application with real-time inventory
management and Stripe payment integration.
## Commands
```bash
npm run dev # Start development server
npm run build # Production build
npm run test # Run tests
npm run lint # Run ESLint
```
## Architecture
### Core Data Flow
```
User Action → API Route → Database → Response → UI Update
```
### Key Directories
- `src/app/` - Next.js App Router pages
- `src/components/` - React components
- `src/lib/` - Utilities and helpers
- `src/db/` - Database schema and queries
## Coding Standards
### Principles
- **KISS**: Keep solutions simple
- **DRY**: Extract duplicated code (3+ occurrences)
- **YAGNI**: Don't add features until needed
### TypeScript
- Use strict mode
- No `any` types
- Prefer interfaces over types
### React
- Functional components only
- Custom hooks for shared logic
- Keep components under 200 lines
## Tech Stack
Next.js 15, React 19, TypeScript, Tailwind CSS,
Prisma, PostgreSQL, StripeBest Practices
Be Specific About Commands
Include exact commands with flags. "npm run test" is better than "run tests".
Document Architecture Decisions
Explain why you chose certain patterns or libraries. This helps AI make consistent decisions.
Include Anti-Patterns
Tell the AI what NOT to do. "Never use var" or "Don't create new utility files".
Keep It Current
Update CLAUDE.md when you add new features, change patterns, or update dependencies.
Use Code Examples
Show preferred patterns with actual code snippets. AI learns better from examples.
Common Mistakes
Too Vague
"Write good code" doesn't help. Specify what "good" means in your context.
Too Long
A 50-page CLAUDE.md dilutes important information. Keep it focused and scannable.
Outdated Information
Stale documentation is worse than none. Review CLAUDE.md regularly.
Missing Context
Don't assume the AI knows your domain. Explain business logic and terminology.
Section Deep Dive
Commands Section
List all common development commands with clear descriptions:
## Commands
```bash
npm run dev # Start development server at localhost:3000
npm run build # Production build (runs type check + lint first)
npm run test # Run all tests
npm run test:watch # Run tests in watch mode
npm run lint # Check for linting errors
npm run lint:fix # Auto-fix linting errors
npm run db:migrate # Run database migrations
npm run db:seed # Seed database with test data
```Architecture Section
Explain your project structure and data flow:
## Architecture
### Directory Structure
```
src/
├── app/ # Next.js App Router
├── components/ # UI Components (shadcn/ui)
├── lib/ # Utilities, helpers, validators
├── hooks/ # Custom React hooks
├── store/ # Zustand stores
└── types/ # TypeScript type definitions
```
### Key Files
| File | Purpose |
|------|---------|
| `src/store/cart.ts` | Shopping cart state |
| `src/lib/stripe.ts` | Stripe integration |
| `src/app/api/` | API routes |Coding Standards Section
Define rules the AI should follow:
## Coding Standards
### Core Principles
- **KISS**: Functions under 50 lines, max 4 parameters
- **DRY**: Extract code duplicated 3+ times
- **YAGNI**: No "just in case" features
### Do
- Use TypeScript strict mode
- Write tests for new features
- Use async/await over promises
- Prefer const over let
### Don't
- Use `any` type
- Create new utility files without approval
- Disable ESLint rules
- Skip error handling