CLAUDE.md is the configuration file that Claude Code reads automatically when starting in a project. It’s your way of telling the agent how to behave, what conventions to follow, and what context it needs to be useful from the first message.

What goes in CLAUDE.md and what doesn’t

CLAUDE.md is not technical documentation for the project. It’s a briefing for the agent. Include information Claude needs to operate well but can’t infer from reading the code.

Include:

  • Tech stack and specific versions
  • Project code conventions
  • Development, test, and deploy commands
  • Restrictions and files it shouldn’t touch
  • Business or domain context that isn’t obvious

Don’t include:

  • Function documentation (that goes in the code)
  • Change history
  • Documentation for human users
  • Things Claude can infer from reading the code
# Project

[2-3 sentences describing what the project does and for whom]

## Stack

- Runtime: Node.js 20
- Framework: Next.js 14 App Router
- Database: PostgreSQL via Drizzle ORM
- Tests: Vitest + Testing Library

## Commands

```bash
npm run dev          # dev server at :3000
npm run test         # tests in watch mode
npm run test:ci      # tests without watch (for CI)
npm run db:push      # sync schema with DB

Conventions

  • Components in PascalCase, hooks with use prefix
  • Absolute imports from @/ (alias configured in tsconfig)
  • No any in TypeScript — use unknown if you need to
  • Tests next to the file they test, not in a separate folder

Restrictions

  • Do not modify src/migrations/ — migrations are auto-generated
  • Do not install dependencies without confirming first
  • src/lib/vendor/ is third-party code, don’t touch it

## The most common mistake: vague instructions

Vague instructions don't help. "Write clean code" or "follow best practices" tells the agent nothing useful. Be specific about what clean means in your project.

Instead of:

Use good security practices.


Write:

Input validation: use Zod on all API endpoints. Never build SQL queries with string concatenation — always use prepared parameters. API keys go in environment variables, never hardcoded.


## CLAUDE.md in subdirectories

Claude Code reads all CLAUDE.md files in the directory hierarchy. You can have a root one with global config and additional files in subdirectories for specific context:

project/ ├── CLAUDE.md # global config ├── frontend/ │ └── CLAUDE.md # frontend-specific conventions └── backend/ └── CLAUDE.md # backend conventions


The agent combines all relevant contexts based on the directory it's working in.

## Update CLAUDE.md when the project changes

CLAUDE.md is a living document. If you change the stack, add a new convention, or notice the agent consistently doing something you don't want, update the file. It's more efficient than correcting it in every session.

A well-maintained CLAUDE.md is the difference between an agent that needs constant guidance and one that operates well from the start.