What is a CLAUDE.md file?

What a CLAUDE.md file actually does

When you open Claude Code in a project, it looks for a CLAUDE.md file and loads it into context before doing anything else. That file becomes a standing set of instructions for the whole session — the agent treats it as ground truth about your project.

Think of it as the onboarding doc you would hand a new senior engineer, except the engineer reads the whole thing every single time and never forgets it mid-task. Conventions, commands, architecture decisions, and the things that must never happen all live here.

Where CLAUDE.md files live

There are three useful locations, and they stack: a personal file at ~/.claude/CLAUDE.md applies to every project on your machine; a root CLAUDE.md applies to one repository; and subdirectory CLAUDE.md files load when the agent is working inside that folder.

Most teams start with a single root-level CLAUDE.md and only split out subdirectory files once a monorepo has genuinely different rules per package.

What to put in it (and what to leave out)

Lead with the things an agent gets wrong without guidance: the exact commands to build, test, and lint; the tech stack and where things live; hard constraints ("never edit the generated schema by hand", "all list endpoints must paginate"); and the gotchas you have already paid for in lost time.

Leave out anything the agent can trivially discover by reading the code, and anything aspirational that is not actually enforced. A rule you do not follow teaches the agent that rules here are optional.

What separates a good CLAUDE.md from a bad one

Bad CLAUDE.md files are vague ("write clean code", "follow best practices"). Good ones are specific and testable ("build NestJS with tsc directly, not nest build — webpack OOMs on this machine"). Specific rules survive contact with a real task; vague ones get silently ignored.

The highest-leverage section is usually a short list of hard-won lessons — concrete incidents turned into rules. Every production mistake you encode is a mistake your agents will not repeat.

A starter CLAUDE.md structure

Copy this skeleton, replace the placeholders, and you have a working CLAUDE.md in ten minutes. Or use the free CLAUDE.md generator to fill it in interactively.

# {{PROJECT_NAME}}

## What this is
One-paragraph description of the product and who it serves.

## Tech stack
- Backend: {{e.g. NestJS + TypeScript}}
- Frontend: {{e.g. Next.js 14 App Router}}
- Database: {{e.g. Postgres + Prisma}}

## Commands
- Install: {{install command}}
- Dev: {{dev command}}
- Test: {{test command}}
- Lint: {{lint command}}

## Architecture
Where things live; the 2-3 patterns to follow.

## Rules (never do these)
- {{hard constraint #1}}
- {{hard constraint #2}}

## Lessons (paid for in real incidents)
- {{lesson: what broke, and the rule that prevents it}}

CLAUDE.md FAQ