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.