CLAUDE.md: teaching Claude your project

Every project has a few facts about it that you find yourself re-explaining every session. "The tests run with npm run test:unit, not npm test." "We use Tailwind, not styled-components." "Database migrations live in db/migrations/ and run via npm run migrate." Without somewhere to write these down, every new Claude Code session starts from scratch.

CLAUDE.md is the place to write them down.

What CLAUDE.md is

A plain Markdown file named CLAUDE.md, placed at the root of your project. Claude Code automatically reads it at the start of every session in that project. The contents become part of Claude's working knowledge for the entire conversation.

Think of it as the project briefing you'd give a new contractor on day one. What is this thing? How is it laid out? What conventions does it follow? What lessons have you learned the hard way that you don't want to repeat?

What belongs in it

• What the project is in one or two sentences. What problem does it solve, what stack is it on, who uses it.
• How to run common commands.The actual command to run tests, build, lint, deploy. The ones with the project's quirks.
• The folder layout. Where do components live? Where are utilities? Where do new pages go? Two or three paragraphs at most.
• Conventions you care about.Naming patterns, file structure, what to import from where, the difference between this project's style and the generic default.
• Hard-won lessons.Mistakes that took an hour to debug. Tools that look attractive but don't work in this codebase. Things you've tried and rejected.

What doesn't belong

• Anything derivable from the code. The list of dependencies is in package.json already. Claude can read it.
• Secrets. Same reasoning as the env-vars lesson. CLAUDE.md is committed to git.
• One-off task context."Today I'm working on the bug Sarah mentioned" belongs in the conversation, not the file.
• Documentation aimed at humans only. The README is for that. CLAUDE.md is for the agent.

A starter template

Here's a minimal example you can adapt:

# My Project

A small Next.js app for taking and organising recipe notes. TypeScript,
Tailwind, deployed to Vercel.

## Commands

- `npm run dev` — start the local dev server on port 3000
- `npm run build` — production build, also runs typecheck
- `npm run test` — vitest unit tests
- `npm run lint` — eslint check (must pass before commits)

## Layout

- `src/app/` — Next.js App Router pages
- `src/components/` — shared React components, one per file
- `src/lib/` — non-React utilities and types
- `src/db/` — drizzle schema and migrations

## Conventions

- Server components by default; add `"use client"` only when needed.
- Date formatting goes through `src/lib/date.ts` — don't inline.
- Database access only in server components or API routes, never in
  client code.

## Things to avoid

- Don't install new UI libraries — we use Radix primitives + Tailwind.
- Don't refactor the legacy `src/pages/` directory; we're slowly
  migrating to App Router. Leave it alone.
- Don't run migrations against the prod database from this checkout.

That's about a hundred lines of writing. It pays back its cost within the first session.

Generating a starter with /init

You don't have to write the whole thing from scratch. Inside a session, the slash command /init asks Claude to analyse the project and propose a starting CLAUDE.md. It reads the folder structure, the package.json, any existing READMEs, and writes a first draft.

Don't accept the draft blindly — read it, edit it, delete anything redundant. But it's a much faster path than typing from a blank file.

Multiple CLAUDE.md files

For larger projects, you can put a CLAUDE.md inside any sub-folder. Claude reads them when working in that folder, in addition to the root one. This is useful for:

• A monorepo where each package has its own conventions.
• A particularly tricky sub-system that needs extra context.
• A folder of legacy code with specific "do not touch" rules.

Don't go overboard. One root file plus the occasional sub-folder file is usually plenty. A CLAUDE.md in every folder creates noise; Claude can only hold so much in context at once.

Keep it alive

The most common failure mode of CLAUDE.mdis the same as every other docs file: written once, never updated. Six months later it's telling Claude to use a library you've since removed.

Treat it like a living document. When you discover a new convention, add a line. When you remove a system, delete the section about it. The cost of an outdated CLAUDE.md is Claude confidently doing the wrong thing.