Guide

How to Write a CLAUDE.md File

A complete guide to writing effective CLAUDE.md context files for Claude Code. Includes best practices, real-world examples, and a section-by-section breakdown of what to include.

10 min readLast updated April 2026

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.

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:

01
Project Overview — What is this project and what problem does it solve?
02
Tech Stack — Frameworks, languages, databases, and tools with versions
03
Getting Started — How to run the project locally (commands, env vars)
04
Architecture — How the system is structured at a high level
05
File Structure — Where things live and naming conventions
06
Coding Conventions — Patterns to follow, anti-patterns to avoid
07
Testing — Test framework, coverage requirements, testing patterns
08
Deployment — How the app is deployed and any environment-specific config

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.

Too vague
## Tech Stack
- React
- Node.js
- PostgreSQL
Specific and useful
## 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.

CLAUDE.md
# 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

Example

"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

Example

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

Example

"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

Example

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

Example

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
Free to use No account required

Frequently Asked Questions