What is CLAUDE.md?
CLAUDE.md is a context file that Claude Code — Anthropic's AI coding CLI — automatically reads from your project root when you start a session. It tells Claude Code about your project's tech stack, coding conventions, architecture, and requirements so it can write code that fits your project from the first prompt.
Think of it as the difference between hiring a contractor who's read your project brief versus one who walks in blind. A well-written CLAUDE.md eliminates the repeated setup conversations and produces more consistent, project-appropriate code.
This guide covers what to include, how to structure it, and the common mistakes that make CLAUDE.md files counterproductive.
In this guide
1. Recommended structure
A good CLAUDE.md follows a consistent structure that moves from high-level context to specific rules. Here's the recommended order:
Not every section is required. A new project might only need Overview, Tech Stack, and Conventions. The key is being specific about what matters — vague instructions are worse than no instructions.
2. Section-by-section breakdown
Project Overview
Start with 2-3 sentences describing what the project does and who it's for. This gives Claude Code the context to make product-level decisions, not just code-level ones.
# TaskFlow A team task management app for small engineering teams (5-20 people). Users create projects, assign tasks with priorities and deadlines, and track progress through kanban boards and sprint views.
Tech Stack
Be specific about versions. "React" tells Claude Code almost nothing — "React 18 with Next.js 14 App Router" tells it exactly which APIs to use and which patterns are current.
## Tech Stack - React - Node.js - PostgreSQL
## Tech Stack - Next.js 14 (App Router) - TypeScript 5.3 (strict mode) - Tailwind CSS 3.4 - PostgreSQL 16 via Prisma 5 - Supabase Auth (JWT)
Coding Conventions
This is where CLAUDE.md pays off the most. Be explicit about the rules your team follows. Frame them as instructions, not descriptions.
## Conventions - Always use server components unless client interactivity is needed - Use `use client` directive only at the component level, never in pages - Validate all API inputs with Zod schemas in lib/validations/ - Use next-safe-action for all server actions - Error handling: throw AppError from lib/errors.ts, never raw Error - Prefer named exports over default exports for components - All database queries go through repository files in lib/db/
File Structure
Without this section, Claude Code creates files wherever seems logical to it — which may not match your project's actual organisation. A clear file structure map prevents this.
## File Structure
```
src/
app/ # Next.js pages and layouts
(app)/ # Authenticated routes
(marketing)/ # Public pages
api/ # API route handlers
components/
ui/ # Reusable primitives (Button, Input, etc)
features/ # Feature-specific components
lib/
db/ # Database repositories
validations/ # Zod schemas
errors.ts # Custom error classes
utils.ts # General utilities
hooks/ # Custom React hooks
```3. Full CLAUDE.md example
Here's a complete, real-world CLAUDE.md for a SaaS application. Notice how each section is concise but specific — giving Claude Code actionable instructions, not vague guidelines.
# InvoiceApp
A SaaS invoicing tool for freelancers and small agencies. Users create
clients, generate invoices with line items, send them via email, and
track payment status. Supports recurring invoices and multiple currencies.
## Tech Stack
- Next.js 14 (App Router, server components by default)
- TypeScript 5.3 (strict mode enabled)
- Tailwind CSS 3.4 + shadcn/ui components
- PostgreSQL 16 via Prisma 5 ORM
- Supabase Auth (email + Google OAuth)
- Resend for transactional email
- Stripe for subscription billing
- Deployed on Vercel
## Getting Started
```bash
cp .env.example .env.local # Fill in Supabase, Stripe, Resend keys
npm install
npx prisma db push
npm run dev # http://localhost:3000
```
## Architecture
- Server components for data fetching, client components for interactivity
- API routes only for webhooks (Stripe, email); use server actions for mutations
- All business logic in lib/services/ (not in components or API routes)
- Background jobs via Vercel Cron (app/api/cron/)
## File Structure
```
src/
app/
(app)/ # Authenticated: dashboard, invoices, clients, settings
(marketing)/ # Public: landing, pricing, blog
api/webhooks/ # Stripe + email webhooks only
components/
ui/ # shadcn/ui primitives
invoices/ # Invoice-specific components
clients/ # Client management components
lib/
services/ # Business logic (invoice.service.ts, payment.service.ts)
db/ # Prisma client + repository functions
validations/ # Zod schemas matching Prisma models
email/ # Email templates and sending logic
```
## Conventions
- Server components by default; add 'use client' only for interactivity
- Validate inputs with Zod schemas from lib/validations/
- Use next-safe-action for server actions with built-in validation
- Money amounts stored as integers (cents) in the database
- All dates stored as UTC; convert to user timezone only in UI
- Named exports for components; default exports only for pages
- Error handling: throw AppError from lib/errors.ts
## Testing
- Vitest for unit tests, Playwright for E2E
- Unit test all services in lib/services/
- E2E tests for critical flows: signup, create invoice, send, mark paid
- Run: npm test (unit), npm run test:e2e (playwright)4. Common mistakes
Being too vague
"Use modern best practices and clean code"
Claude Code can't act on vague instructions. "Best practices" means different things in different contexts.
Be specific: "Use server components by default. Only add 'use client' when the component needs useState, useEffect, or event handlers."
Dumping your entire docs
Pasting 2000 lines of API documentation into CLAUDE.md
Long CLAUDE.md files dilute the important context with noise. Claude Code reads the whole file — if it's bloated, the signal-to-noise ratio drops.
Keep CLAUDE.md under 500 lines. Reference external docs with file paths instead: "See docs/api.md for endpoint details."
Listing tools without conventions
"We use React, TypeScript, and PostgreSQL"
Knowing the tech stack is necessary but not sufficient. Claude Code needs to know how you use these tools.
Add the patterns: "React 18 with Next.js App Router. Always use server components for data fetching. Use Zod + react-hook-form for all forms."
Forgetting the file structure
No file structure section at all
Claude Code will create files wherever seems logical to it. Without a file map, you get components in random directories.
Add a tree diagram showing where different types of files should live.
Never updating it
Writing CLAUDE.md once and never touching it again
A stale CLAUDE.md with outdated dependencies or deprecated patterns actively misleads Claude Code into writing wrong code.
Review CLAUDE.md when you update major dependencies, change architecture patterns, or add new conventions.
5. Advanced tips
Use subdirectory CLAUDE.md files
For large projects, place additional CLAUDE.md files in subdirectories. The root file covers project-wide context, while src/frontend/CLAUDE.md covers frontend-specific conventions. Claude Code reads all CLAUDE.md files in the path hierarchy.
Frame rules as instructions, not descriptions
Write CLAUDE.md like you're briefing a new team member, not documenting existing code.
"We use Prisma for database access"
"Use Prisma for all database queries. Put repository functions in lib/db/. Never use raw SQL."
Include "don't" rules
Explicit constraints are often more useful than positive instructions. If your team has learned the hard way not to do something, tell Claude Code: Never use any type. Never import from @/internal/. Never add dependencies without checking package.json first.
Reference files instead of duplicating content
Instead of pasting your entire API schema into CLAUDE.md, reference it:See openapi.yaml for the full API specification. Claude Code can read files you reference, keeping CLAUDE.md focused on decisions and rules.
Skip the writing — generate your CLAUDE.md
Keeborg generates a complete CLAUDE.md plus 7 other specification documents from a plain English description of your project. Ready in under 90 seconds.
Generate CLAUDE.md Free