CLAUDE.md
A markdown file at the root of your project that gives Claude project-level instructions, conventions, and constraints.
CLAUDE.md is to Claude what README.md is to humans, but optimized for an LLM reader. Claude Code automatically reads it at session start; everything inside becomes part of the system prompt for that project. Without one, Claude has to re-infer your conventions every session, which wastes tokens and produces inconsistent results.
What goes in a great CLAUDE.md: stack overview (frameworks, key libraries), conventions (naming, testing, error handling), file-structure tour, anti-patterns to avoid, env vars, deployment quirks, and a list of skills/agents/MCP servers configured for this repo. Be direct, terse and explicit about constraints. Keep it under 500 lines — Claude reads it every session and longer files erode its attention budget.
Treat CLAUDE.md as code: review on every PR, update when you add a new convention, drop sections when you remove a library. A stale CLAUDE.md actively confuses Claude.