A markdown file at the project root that Claude Code auto-loads as context every session. It tells Claude about the project's overview, structure, commands, and conventions upfront.

Project-scope: `CLAUDE.md` at the project root. User-global: `~/.claude/CLAUDE.md`. If both exist, user-global loads first and project overrides — project rules take precedence.

What should it contain?

Project overview, tech stack, directory layout summary, common commands (build/dev/test), code conventions, and explicit "do not" rules. Keep it concise — longer isn't better.

How do I bootstrap one?

Run `/init` in Claude Code. It analyzes the project and produces a draft, which is faster to refine than writing from scratch.

Does a long CLAUDE.md cause problems?

Yes — it's loaded into every session and consumes tokens. One screen of content is the sweet spot. For detailed rules, split them into separate Skills.

Writing a Great CLAUDE.md

Why CLAUDE.md matters

Claude Code auto-loads the project root’s CLAUDE.md into context at the start of every session. Write it well once and the same guidance applies to every session — no repeating yourself.

A good CLAUDE.md immediately improves answer quality and reduces wrong assumptions and repeated mistakes.

Two locations

Location	Scope
`~/.claude/CLAUDE.md`	User-global (every project)
`<project>/CLAUDE.md`	Just this project

If both exist, user-global loads first and project follows — project-specific rules effectively take precedence.

Bootstrap a draft

/init

Claude Code analyzes the project and produces a draft. Refining the draft is faster than writing from scratch.

Five principles

1. Short and structured

It’s loaded into every session, so longer means less token budget. Aim for one or two screens.

2. “How to handle it” beats “what’s there”

Skip the full directory tree — describe what each key directory is for and the commands you actually run. Claude can explore files itself.

3. State the don’ts

A list of “don’ts” is more effective than positive instructions.

## Rules
* Never commit or push without explicit user instruction
* Don't add error handling for impossible scenarios
* Don't introduce new dependencies without approval

4. Put commands in code blocks

Build/dev/test commands should be in code blocks so Claude copies and runs them exactly.

## Commands
\```bash
npm run build       # production build
npm run dev         # dev server (port 3030)
npm test            # unit tests
\```

5. Document recurring workflows

Tasks like adding content, running migrations, or shipping a release belong here as procedures.

Solid structure example

# Project Name

## Overview
One paragraph on what the project does.

## Stack
* Frontend: Next.js 15, Tailwind CSS
* Backend: Node.js, Prisma, PostgreSQL
* Hosting: Cloudflare Pages

## Commands
\```bash
npm run dev
npm run build
npm test
\```

## Layout
* src/app — Next.js App Router pages
* src/components — UI components
* prisma/ — DB schema and migrations

## Conventions
* Function components only
* State via Zustand
* Tests with Vitest

## Rules
* Commit/push only on explicit instruction
* Confirm before adding new dependencies

Common mistakes

❌ Pasting the full directory tree — Claude can explore
❌ Mixing languages — pick one and stay consistent
❌ Feature descriptions (those belong in the README)
❌ Generic best practices (“write readable code”) — keep it project-specific

Move detailed rules into Skills

When CLAUDE.md grows, extract recurring workflows (content authoring, migration procedures) into separate Skill files. Leave a short pointer in CLAUDE.md saying “for X, invoke skill Y.”

Next steps

Andrej Karpathy Skills — a CLAUDE.md template plugin distilling Karpathy’s principles
Superpowers — pair with CLAUDE.md for stronger workflow consistency
Build a Skill — extract rules into reusable Skills