How to Write a CLAUDE.md File

A complete guide to configuring Claude Code for your project. Updated March 2026.

Contents

  1. What is CLAUDE.md?
  2. Where to put it
  3. Recommended structure
  4. Essential sections
  5. Writing tips
  6. Common mistakes
  7. Starter template
  8. Validate your file

1. What is CLAUDE.md?

CLAUDE.md is a special markdown file that Claude Code reads automatically when it opens your project. It tells Claude about your codebase: the tech stack, coding conventions, testing requirements, project structure, and any rules you want Claude to follow.

Think of it as a project briefing for your AI pair programmer. Without it, Claude Code makes reasonable guesses. With a good CLAUDE.md, Claude Code writes code that matches your project's exact style and conventions from the first interaction.

2. Where to put it

Claude Code looks for CLAUDE.md in several locations, with different scopes:

Tip: Start with a single CLAUDE.md in the project root. Only add subdirectory files when you have genuinely different rules for different parts of the codebase.

3. Recommended structure

A good CLAUDE.md follows a consistent structure. Here's the recommended skeleton:

# Project Name

## Tech Stack
[Languages, frameworks, and key dependencies]

## Code Style
[Formatting rules, naming conventions, patterns to follow]

## Project Structure
[Key directories and what they contain]

## Testing
[How to run tests, coverage requirements, test patterns]

## Git Conventions
[Commit format, branch strategy, PR rules]

## Common Commands
[Build, test, lint, deploy commands]

## Important Context
[Domain knowledge, business rules, gotchas]

4. Essential sections explained

Tech Stack

List your languages, frameworks, and major dependencies with versions. This helps Claude Code generate code using the right APIs.

## Tech Stack
- TypeScript 5.3, strict mode
- React 18 with functional components and hooks
- Next.js 14 (App Router, not Pages)
- PostgreSQL 16 with Prisma ORM
- Tailwind CSS 4 for styling
- Vitest for testing

Code Style

Be specific about naming, patterns, and preferences. Vague rules like "write clean code" don't help — Claude already tries to write clean code.

## Code Style
- Use `const` by default, `let` only when reassignment is needed
- Named exports only, no default exports
- Prefer early returns over nested conditionals
- Error messages must be user-facing (no technical jargon)
- Use `async/await`, never raw promises with `.then()`
- File naming: kebab-case for files, PascalCase for components

Project Structure

Help Claude understand where things live. You don't need to list every file — focus on the patterns.

## Project Structure
- `src/app/` — Next.js App Router pages and layouts
- `src/components/` — Shared React components
- `src/components/ui/` — Design system primitives
- `src/lib/` — Utilities and shared logic
- `src/server/` — Server-only code (API routes, DB queries)
- `prisma/` — Database schema and migrations

Testing

Tell Claude how to run tests and what kind of tests you expect. This is one of the most impactful sections.

## Testing
- Run: `npm test` (Vitest)
- Run single: `npm test -- path/to/file.test.ts`
- Integration tests: `npm run test:integration`
- New features require tests in `__tests__/` alongside the source file
- Use `describe` and `it` blocks, not `test`
- Mock external APIs, never mock internal modules
- Minimum 80% coverage for new code

Common Commands

List the commands Claude might need. This prevents Claude from guessing wrong build tools.

## Common Commands
- `npm run dev` — Start dev server on port 3000
- `npm run build` — Production build
- `npm test` — Run all tests
- `npm run lint` — ESLint check
- `npm run db:migrate` — Run Prisma migrations
- `npm run db:seed` — Seed development database

5. Writing tips

Be specific, not general. "Use functional components" is better than "follow React best practices." Claude already knows best practices — tell it what your project does differently.

6. Common mistakes

Leftover placeholders. The #1 mistake is copying a template and leaving [Your Project Name] or [TODO: fill this in] in the file. Claude reads these literally.

7. Starter template

Copy this template and customize it for your project:

# [Your Project Name]

## Tech Stack
- [Language and version]
- [Framework and version]
- [Database]
- [Key dependencies]

## Code Style
- [Naming convention for files]
- [Naming convention for variables/functions]
- [Import ordering preference]
- [Error handling approach]

## Project Structure
- `src/` — [description]
- `tests/` — [description]
- `config/` — [description]

## Testing
- Run: `[test command]`
- [Test framework and version]
- [Coverage requirements]
- [Testing patterns/conventions]

## Git Conventions
- [Commit message format]
- [Branch naming]
- [PR requirements]

## Common Commands
- `[build command]` — [description]
- `[test command]` — [description]
- `[lint command]` — [description]
Important: Replace every [bracketed placeholder] with your actual project details before committing. Leftover placeholders confuse Claude Code.

8. Validate your CLAUDE.md

After writing your CLAUDE.md, validate it to catch common issues:

ClaudeCheck runs 12 rules covering structure, placeholders, secrets, and best practices.

Validate Your CLAUDE.md Now

See real-world examples: CLAUDE.md Examples for Different Project Types