CLAUDE.md is a project-specific instruction file for Claude Code. Drop it in your project root and Claude Code reads it automatically at the start of every session. No configuration needed — if the file exists, it's loaded.

It's the difference between Claude Code being a generic coding assistant and one that knows your project's conventions, architecture, and quirks.

What to Put In It

A practical CLAUDE.md covers four things:

1. Build and Test Commands

## Commands

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Dev server: `npm run dev` (port 3000)

Claude Code will use these instead of guessing. Without this, it might run npx jest when your project uses vitest, or try yarn when you use pnpm.

2. Project Structure

## Structure

- `src/shared/` — shared utilities used by all entry points
- `src/api/` — Express API routes
- `src/workers/` — background job processors
- `scripts/` — build and deployment scripts

Helps Claude Code navigate the codebase without reading every file.

3. Conventions and Rules

## Conventions

- Use Zod for all input validation (not Joi or yup)
- Database queries use parameterized SQL only — never string interpolation
- All times in America/Chicago timezone
- Error responses follow the format: `{ error: string, code: string }`

This prevents Claude Code from introducing patterns that don't match your codebase.

4. Learned Corrections

## Corrections

- The Code node in n8n does NOT have access to fetch() — use HTTP Request nodes instead
- Docker Compose v2 uses `docker compose` (no hyphen), not `docker-compose`
- The Postgres node's queryReplacement option uses commas between values, not arrays

Things that tripped you up once and shouldn't trip Claude Code up ever.

Where to Put It

Location	Scope
`./CLAUDE.md`	Current project only
`./subfolder/CLAUDE.md`	Loaded when working in that subfolder
`~/.claude/CLAUDE.md`	Global — loaded for every project

Project-level files override global ones. You can have both.

Keep It Short

Claude Code loads the entire CLAUDE.md into context at the start of every conversation. A 50-line file with the essential commands, conventions, and gotchas is more effective than a 500-line specification. Put detailed documentation in separate files and reference them:

For database schema details, see `docs/schema.md`.
For deployment procedures, see `docs/deploy.md`.

Auto-Generate from MCP Tools

If you're building MCP servers, you can generate a CLAUDE.md from your tool definitions:

import { ALL_TOOLS } from "./shared/tools.js";

let md = "# MCP Tools\n\n";
for (const tool of ALL_TOOLS) {
  md += `## ${tool.name}\n${tool.description}\n\n`;
  const params = Object.entries(tool.inputSchema);
  if (params.length) {
    md += "| Param | Type |\n|-------|------|\n";
    for (const [name, schema] of params) {
      md += `| ${name} | ${schema.description || 'string'} |\n`;
    }
    md += "\n";
  }
}

The MCP Server Starter Kit includes a full CLAUDE.md generator script.

Configuration Notes

Format: Plain Markdown. No front matter, no special syntax. Just headings and text.
Updates: Claude Code reads CLAUDE.md once at session start. If you edit it mid-session, restart Claude Code to pick up changes.
Version control: Commit CLAUDE.md to your repo. It's useful for the whole team, not just one person's local setup.
Don't duplicate README: CLAUDE.md is instructions for the AI, not documentation for humans. Keep them separate. The AI doesn't need your project's license section or contribution guidelines.

CLAUDE.mdReference