CLAUDE.md Guide

Templates and examples for writing effective Claude Code instructions

What Is CLAUDE.md?

CLAUDE.md is a Markdown file in your project’s root directory that tells Claude Code how to work on your codebase. It contains your project’s build commands, architecture overview, coding conventions, and constraints — everything Claude needs to write code that fits your project.

Claude Code reads CLAUDE.md automatically at the start of every session. Instead of repeating “we use TypeScript strict mode” or “run npm test before committing” in every prompt, you write it once in CLAUDE.md.

Think of it as onboarding documentation for AI: the same information you’d give a new developer on their first day, but optimized for an AI agent’s context window.

Quick Start

Create a CLAUDE.md file in your project root. Here is the minimum viable version:

CLAUDE.md (minimal) # Project Instructions ## Commands - `npm run dev` — start dev server - `npm test` — run tests - `npm run lint` — check formatting ## Rules - TypeScript strict mode, no `any` - Prefer server components by default - Never commit .env files

This 10-line file already prevents the most common issues: wrong test command, wrong coding style, leaked secrets.

CLAUDE.md Template

A comprehensive template covering everything Claude Code needs. Copy this and fill in your project details:

CLAUDE.md (full template) # Project Instructions ## Overview SaaS dashboard built with Next.js 15, TypeScript, Tailwind CSS. PostgreSQL database, Prisma ORM, deployed on Vercel. ## Commands - `npm run dev` — dev server on localhost:3000 - `npm test` — Vitest unit tests - `npm run test:e2e` — Playwright end-to-end tests - `npx prisma migrate dev` — run pending migrations - `npx prisma generate` — regenerate client after schema changes - `npm run lint` — ESLint + Prettier - `npm run build` — production build (run before opening PRs) ## Architecture - `app/` — Next.js App Router pages and layouts - `app/api/` — API route handlers - `components/` — shared React components - `components/ui/` — design system primitives - `lib/` — utilities, database client, auth helpers - `lib/actions/` — server actions - `prisma/schema.prisma` — database schema ## Conventions - Server components by default, `'use client'` only when needed - Tailwind CSS only — no CSS modules, no inline styles - Use `cn()` from `lib/utils` for conditional class names - Zod schemas for all input validation - Server actions for form mutations, not API routes - Date handling with date-fns, always UTC in database - Error handling: throw typed errors from lib/errors ## Constraints - No `any` type — use `unknown` and narrow with Zod - Images through `next/image` only - Environment variables: validated in `lib/env.ts`, never accessed directly via `process.env` - Do not modify `lib/auth/` without explicit approval - Max component file size: 300 lines. Split into smaller components. - All new API endpoints need rate limiting middleware ## Testing - Unit tests next to source: `foo.test.ts` - E2E tests in `tests/e2e/` - Use `createTestUser()` from `tests/helpers` for auth in tests - Mock external APIs with MSW, never call real services ## Git - Branch from `main`, PR title format: `feat|fix|chore: description` - Run `npm run build` before opening PRs — CI will reject build failures - Squash merge only

CLAUDE.md Examples by Stack

Ready-to-use templates for common tech stacks:

Python / Django

CLAUDE.md (Django) # Project Instructions ## Stack Python 3.12, Django 5.1, DRF, PostgreSQL, Celery, Redis ## Commands - `uv run manage.py runserver` — dev server - `uv run pytest` — run tests - `uv run pytest --cov --cov-report=term` — tests with coverage - `uv run ruff check . && uv run ruff format --check .` — lint - `uv run manage.py makemigrations` — create migrations - `uv run manage.py migrate` — apply migrations ## Architecture - `apps/` — Django apps (accounts, billing, dashboard) - `apps/api/` — DRF viewsets and serializers - `core/` — settings, URLs, middleware, base classes - `tasks/` — Celery task definitions - `templates/` — Django templates (email, admin) ## Conventions - Type hints on all functions (mypy strict) - DRF serializers for all request/response validation - Fat models, thin views — business logic in model methods - Use `select_related` / `prefetch_related` to avoid N+1 queries - Celery for anything that takes > 500ms ## Constraints - No raw SQL — use Django ORM - No `print()` — use `structlog` logger - Secrets via environment variables only - All migrations must be reversible

Go / Chi

CLAUDE.md (Go) # Project Instructions ## Stack Go 1.23, Chi router, sqlc, PostgreSQL, Docker Compose ## Commands - `go run ./cmd/server` — start server on :8080 - `go test ./...` — run all tests - `go test -race -count=1 ./...` — tests with race detector - `sqlc generate` — regenerate query code from SQL - `golangci-lint run` — lint - `docker compose up -d db` — start local PostgreSQL ## Architecture - `cmd/server/` — main entry point and server setup - `internal/handler/` — HTTP handlers (one file per resource) - `internal/service/` — business logic layer - `internal/store/` — database access (sqlc generated code) - `internal/middleware/` — auth, logging, rate limiting, CORS - `sql/queries/` — SQL queries (sqlc input) - `sql/migrations/` — goose migration files ## Conventions - Accept interfaces, return structs - Errors: `fmt.Errorf("operation: %w", err)` — always wrap - Context as first argument, logger as second - Table-driven tests with `t.Run` subtests - No `init()` functions, no package-level variables ## Constraints - No global mutable state - All HTTP calls require `context.Context` with timeout - SQL through sqlc only — no `database/sql` queries - No external dependencies without team approval

Swift / iOS

CLAUDE.md (Swift) # Project Instructions ## Stack Swift 6, SwiftUI, SwiftData, Xcode 16, minimum iOS 17 ## Commands - `xcodebuild -scheme MyApp -sdk iphonesimulator build` — build - `xcodebuild test -scheme MyApp -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 16'` — run tests - `swift build` — build SPM packages ## Architecture - `MyApp/` — main app target - `MyApp/Views/` — SwiftUI views - `MyApp/ViewModels/` — ObservableObject view models - `MyApp/Models/` — SwiftData models - `MyApp/Services/` — networking, persistence, analytics - `MyAppTests/` — unit and integration tests ## Conventions - SwiftUI with MVVM pattern - @Observable macro for view models (not ObservableObject) - Structured concurrency (async/await), no Combine - SwiftData for persistence, no Core Data - Swift strict concurrency checking enabled ## Constraints - No force unwrapping (`!`) except in tests - No UIKit unless SwiftUI has no equivalent - Minimum iOS 17 — use latest APIs freely - All network calls through APIClient service

File Hierarchy

Claude Code reads CLAUDE.md files at three levels. Instructions merge together, with more specific files taking precedence:

  • Project root (./CLAUDE.md) — global project instructions, always loaded when Claude works in this project
  • Subdirectories (./app/CLAUDE.md, ./backend/CLAUDE.md) — module-specific context, loaded when Claude works in that directory
  • User-level (~/.claude/CLAUDE.md) — personal preferences that apply across all projects (e.g., preferred coding style, editor settings)

A typical monorepo might have:

  • ./CLAUDE.md — shared commands, Git conventions, CI requirements
  • ./frontend/CLAUDE.md — React patterns, component naming, Tailwind setup
  • ./backend/CLAUDE.md — API conventions, database patterns, error handling
  • ./infra/CLAUDE.md — Terraform style, deployment constraints

CLAUDE.md vs AGENTS.md

CLAUDE.md is specific to Claude Code. It can reference Claude-specific features: memory system, custom slash commands, hooks, and MCP servers.

AGENTS.md is a cross-tool convention — any AI coding agent can read it. It contains universal instructions: architecture, conventions, and constraints that apply regardless of which AI tool your team uses.

When to use which:

  • Claude Code only? — use CLAUDE.md
  • Multiple AI tools on the team? — use AGENTS.md for shared instructions + CLAUDE.md for Claude-specific settings
  • Not sure? — start with CLAUDE.md (Claude Code reads it natively). You can always split later.

Claude Code reads both files. Instructions from CLAUDE.md and AGENTS.md are merged.

Writing Tips

  • Be concise — Claude reads the entire file into its context window. Every line reduces the space available for code. Aim for 50–200 lines.
  • Commands, not descriptions — “npm test -- --watch” beats “we use Jest with watch mode for development testing.”
  • Constraints are the most valuable section — “Do not modify lib/auth/” prevents an entire class of mistakes. “No any type” is more actionable than “we prefer strong typing.”
  • Link, don’t duplicate — “See docs/api.md for API design guide” keeps CLAUDE.md lean. Claude reads linked files on demand.
  • Update in the same PR — when you rename a directory, change a convention, or switch a dependency, update CLAUDE.md in the same pull request.
  • Test your instructions — start a fresh Claude session and ask it to make a small change. If Claude gets it right without additional prompting, your CLAUDE.md is working.

Common Mistakes

  • Too long — a 500-line CLAUDE.md wastes tokens. If it’s long, split into subdirectory files or link to separate docs.
  • Duplicating README.md — Claude already reads your README. CLAUDE.md should contain operational instructions (commands, constraints, patterns) not project marketing.
  • Too vague — “write clean code” tells an AI nothing. “Max 30 lines per function, early returns, no nested ternaries” is actionable.
  • Missing constraints — the “do not” rules prevent the most expensive mistakes. List modules Claude should not touch, dependencies it should not add, patterns it should avoid.
  • Stale instructions — CLAUDE.md describing last month’s architecture actively causes wrong code. Review it when the project changes.

Other Markdown Files Claude Code Uses

Beyond CLAUDE.md, Claude Code reads and works with several Markdown files in your project:

  • README.md — project overview, always read for initial context
  • AGENTS.md — cross-agent instructions (read alongside CLAUDE.md)
  • CONTRIBUTING.md — contribution guidelines, PR conventions
  • CHANGELOG.md — version history, used when making releases
  • docs/*.md — documentation files, read on demand when relevant

The entire AI coding workflow — from context to output — runs on Markdown. For more on why, see Why AI Tools Use Markdown.

Related Guides

View CLAUDE.md with MDViewer

MDViewer renders CLAUDE.md with full formatting — headings, code blocks, syntax highlighting, and links. See your AI instructions the way Claude Code sees them. Edit inline, preview changes, and keep your context files accurate.

Download MDViewer

Requires macOS 13.0 or later. Intel and Apple Silicon.