CLAUDE.md File: The Complete Guide to Project Instructions

The CLAUDE.md file is the most important configuration file in any Claude Code project. It tells Claude who your project is, how it works, and what rules to follow -- like an onboarding document for an AI engineer joining your team. Getting your claude md file right is the difference between Claude producing generic code and Claude producing code that fits your project perfectly.

This guide covers everything: file locations, syntax, real-world examples, best practices, and advanced patterns for the claude md file.

What Is a CLAUDE.md File?

A CLAUDE.md file is a plain Markdown file that provides project-specific instructions to Claude Code. When you start a Claude Code session, the contents of your claude.md file are automatically loaded into Claude's context as system-level guidance -- like an onboarding document for an AI engineer joining your team.

A CLAUDE.md file typically controls: project architecture and stack, build/test commands, coding conventions, things to avoid, deployment context, and team preferences like PR formats and commit message styles.

File Locations and Load Order

Claude Code supports multiple CLAUDE.md files at different locations. Understanding this hierarchy is essential for teams and multi-project setups.

• Project root: CLAUDE.md -- Primary location. Committed to version control, shared with the whole team.
• User-specific: .claude/CLAUDE.md -- Personal overrides for a project. Typically gitignored so each developer can set their own preferences.
• Global: ~/.claude/CLAUDE.md -- Applies to every project. Use for personal coding style and workflow preferences.
• Subdirectory: path/to/dir/CLAUDE.md -- Loaded when Claude works within that directory. Essential for monorepos.

Typical file structure

my-project/
  CLAUDE.md              # Project-wide (committed)
  .claude/
    CLAUDE.md            # User-specific (gitignored)
    skills/              # Reusable skill files
  apps/
    web/CLAUDE.md        # Frontend-specific rules
    api/CLAUDE.md        # Backend-specific rules
~/.claude/CLAUDE.md      # Global preferences

Syntax and Structure

A CLAUDE.md file uses standard Markdown. There is no special syntax or frontmatter required -- Claude reads it as plain text. That said, a well-structured claude md file follows patterns that maximize clarity and minimize wasted context.

Recommended structure

# CLAUDE.md

## Project
Brief description of what this project is and the tech stack.

## Key Directories
- src/ - Application source code
- tests/ - Test files
- docs/ - Documentation

## Commands
- `npm run dev` - Start development server
- `npm run build` - Production build
- `npm test` - Run test suite
- `npm run lint` - Lint and format check

## Conventions
- Use TypeScript strict mode
- Named exports only, no default exports
- Error handling: use Result types, not try/catch
- Tests colocated with source as *.test.ts

## Avoid
- No `any` type -- use `unknown` and narrow
- No barrel files (index.ts re-exports)
- No relative imports crossing package boundaries

Formatting tips

• Use headers to organize sections -- Claude uses them to understand context hierarchy
• Use code blocks for commands and file paths -- keeps them unambiguous
• Use bullet lists for conventions -- easier to scan than paragraphs
• Be imperative -- "Use named exports" is clearer than "We prefer named exports"
• Be specific -- npm run test:unit -- --bail is better than "run tests"

Complete CLAUDE.md Examples

Below are production-ready claude.md file examples for common project types. Use these as starting points and customize for your specific needs.

Next.js / React project

# CLAUDE.md

## Project
E-commerce platform. Next.js 15 (App Router), TypeScript,
Tailwind CSS, Prisma ORM + PostgreSQL.

## Commands
- `npm run dev` - Dev server on port 3000
- `npm run build` - Production build
- `npm test` - Vitest unit tests
- `npx playwright test` - E2e tests
- `npx prisma migrate dev` - Database migrations

## Conventions
- Server Components by default; 'use client' only when needed
- Tailwind for styling; no CSS modules or styled-components
- API routes return NextResponse.json()
- Form validation with zod in lib/validations/
- Named exports everywhere

## Avoid
- No pages/ directory (App Router only)
- No getServerSideProps (use async components)
- No direct database queries outside lib/db/

Python / FastAPI project

# CLAUDE.md

## Project
REST API for ML pipeline. FastAPI + SQLAlchemy + Celery. Python 3.12, uv.

## Commands
- `uv run fastapi dev` - Start dev server
- `uv run pytest` / `uv run pytest -x -v` - Run tests
- `uv run alembic upgrade head` - Apply migrations
- `uv run ruff check . && uv run ruff format .` - Lint + format

## Conventions
- Type hints on all function signatures
- Pydantic models for all request/response schemas
- Dependency injection via FastAPI Depends()
- Tests use pytest fixtures; factory_boy for test data

## Avoid
- No global mutable state; no raw SQL; no print() (use structlog)
- No synchronous I/O in async handlers

Go project

# CLAUDE.md

## Project
Payment processing microservice. Go 1.22, chi router + sqlx.

## Commands
- `go run ./cmd/server` - Start server
- `go test ./...` / `go test -race ./...` - Tests
- `golangci-lint run` - Full lint suite

## Conventions
- Errors: return error last, wrap with fmt.Errorf("op: %w", err)
- context.Context as first parameter
- Table-driven tests with t.Run() subtests

## Avoid
- No init() functions; no panic() for error handling
- No ORM -- use sqlx with raw SQL

Rust project

# CLAUDE.md

## Project
CLI tool for log analysis. Rust 1.78 with clap, tokio, serde.

## Commands
- `cargo build` / `cargo build --release`
- `cargo test` - Run all tests
- `cargo clippy -- -D warnings` - Lint
- `cargo fmt --check` - Format check

## Conventions
- thiserror for library errors, anyhow for application errors
- Prefer &str over String in function parameters
- Document public items with /// doc comments

## Avoid
- No unwrap() or expect() in library code (ok in tests)
- No unsafe blocks without a safety comment

Monorepo (Turborepo)

# CLAUDE.md

## Project
SaaS platform. Turborepo monorepo with shared packages.

## Structure
- apps/web - Next.js frontend
- apps/api - Express.js API
- packages/shared - Shared types, utils, constants
- packages/db - Prisma client and schema

## Commands
- `turbo run build` / `turbo run test` / `turbo run lint`
- `npm run dev -w apps/web` - Start web frontend

## Conventions
- All cross-package imports through packages/shared
- Each package has its own CLAUDE.md with specific rules

## Avoid
- No circular dependencies between packages
- No importing directly from another app's src/

CLAUDE.md vs Other Instruction Files

If you have used other AI coding tools, you may be familiar with similar project instruction files. Here is how the claude md file compares to its equivalents in other tools.

The biggest advantage of CLAUDE.md is its multi-level hierarchy. You can have global preferences, project-wide standards, and directory-specific rules that all compose together. Combined with skills, hooks, and MCP servers, it forms a complete configuration system rather than just a single instructions file.

Best Practices

After analyzing hundreds of claude.md file configurations across open-source projects, these are the patterns that consistently produce the best results.

1. Start with commands. The single most valuable thing in a CLAUDE.md is accurate build and test commands. Claude needs to know how to verify its work.
2. Be explicit about conventions. Do not assume Claude knows your preferences. "Use named exports" is better than hoping Claude infers your style.
3. Include "avoid" rules. What not to do is just as important. List deprecated patterns, forbidden dependencies, and known anti-patterns.
4. Keep it under 200 lines. Every line consumes context window space. Extract verbose instructions into skills.
5. Use imperative language. "Use TypeScript strict mode" beats "We generally prefer TypeScript strict mode."
6. Version control it. Commit the root CLAUDE.md. Only gitignore .claude/CLAUDE.md (personal preferences).
7. Update it regularly. A stale CLAUDE.md produces stale suggestions. Evolve it with your project.

CLAUDE.md and Skills

Skills are reusable CLAUDE.md patterns. While CLAUDE.md provides always-on baseline instructions, skills are Markdown files in .claude/skills/ that are activated on demand via slash commands. Think of CLAUDE.md as the baseline and skills as task-specific instruction sets.

For example, your CLAUDE.md might say "use Vitest for tests," while a /test skill provides detailed fixture patterns, assertion conventions, and coverage requirements:

# .claude/skills/test.md
When writing tests:
1. Use describe/it blocks, not test()
2. One assertion per test when possible
3. Mock external services with msw
4. Name: "should [action] when [condition]"
5. Always test error paths, not just happy paths

Browse community skills at the Skills library, or test your own in the Playground.

Advanced Patterns

Conditional rules

You can write CLAUDE.md instructions that apply only in certain contexts by using clear conditional language:

## TypeScript Files
When editing .ts or .tsx files:
- Use strict TypeScript; no `any`
- Prefer interfaces over type aliases for object shapes

## CSS/Styling
When editing styles:
- Use Tailwind utility classes
- Follow mobile-first responsive design (sm: md: lg:)

Team conventions with roles

Team members can define role-specific instructions in their personal ~/.claude/CLAUDE.md:

# ~/.claude/CLAUDE.md (personal global file)

## My Role
I am a backend engineer. When I ask for help:
- Focus on API design, database queries, and service logic
- Default to writing Go code unless I specify otherwise

Monorepo subdirectory configs

In monorepos, subdirectory CLAUDE.md files let each package define its own rules:

# apps/api/CLAUDE.md
- All routes must have OpenAPI documentation
- Use middleware for auth, not inline logic
- Rate limiting on all public endpoints

# apps/web/CLAUDE.md
- Components in PascalCase, hooks with use prefix
- No useEffect for data fetching; use server components
- All interactive elements need aria labels

Integrating with MCP servers

Your CLAUDE.md can reference MCP servers configured in your project. For example: "Use the database MCP for all queries and schema inspection. Use the github MCP for PR creation. Check sentry before closing bug tickets."

Troubleshooting

CLAUDE.md not being loaded

Verify the file is named exactly CLAUDE.md (all caps). Check that it is in the project root or a recognized location. Start a new session -- CLAUDE.md is read at session start. Ask Claude "What does my CLAUDE.md say?" to confirm it was loaded.

Instructions being ignored

CLAUDE.md instructions are advisory, not enforced -- for strict enforcement, use hooks. Vague instructions are more likely to be missed, so be specific and imperative. If your file is long, move critical rules to the top. Audit for contradictions.

CLAUDE.md too large

Move task-specific instructions into skills. Remove obvious conventions that your linter already enforces. Consolidate similar rules -- five bullet points about imports can become one clear rule.

Team conflicts

Keep the committed CLAUDE.md focused on team-wide standards. Use .claude/CLAUDE.md (gitignored) for personal preferences. Review CLAUDE.md changes in PRs just like code changes.

Related Resources

Your CLAUDE.md file is one part of a complete Claude Code setup:

• Claude Code Best Practices -- overall workflow and setup guide
• Skills Library -- browse reusable CLAUDE.md patterns
• MCP Servers -- extend Claude with external tools
• Hooks Guide -- enforce rules that CLAUDE.md cannot guarantee
• System Prompt Guide -- how CLAUDE.md fits into the full prompt
• Memory Guide -- context persistence across sessions
• Plugins Guide -- install and create plugins
• Cursor Rules Guide -- the equivalent for Cursor users