CLAUDE.md
Also called claude md file
CLAUDE.md is a Markdown file in your repository that Claude Code reads at the start of every session. It carries project conventions, architecture notes, common commands, and constraints, so the agent starts each task knowing how your codebase works.
It is the highest-leverage file in a repository that uses Claude Code, and it is consistently underused. Most complaints about an agent ignoring conventions are really complaints about conventions that were never written down.
What earns its place: the commands to build, test, and lint; architectural decisions that are not obvious from the code; patterns the team requires; and things that look wrong but are deliberate. What does not: anything the agent can read directly from the code.
What this means in practice
Treat it as living documentation. When the agent does something you have to correct, that correction is usually a missing line in CLAUDE.md — adding it there fixes the problem for every future session rather than the current one.
A CLAUDE.md skeleton that earns its tokens
# Project Invoice API. Fastify + Postgres (Drizzle). pnpm, Node 22. # Commands - pnpm dev — start with hot reload - pnpm test — vitest; pnpm test:int needs the Docker Postgres up - pnpm db:migrate / pnpm db:rollback # Architecture notes - All money values are integer cents. Never float. - src/billing/ is generated from the OpenAPI spec — edit the spec, not the output. - Auth middleware runs on every route except /health and /webhooks. # Looks wrong, is deliberate - The retry loop in src/queue/consumer.ts swallows errors on purpose; dead letters are handled downstream. # Boundaries - Ask before adding dependencies or touching migrations. - Run pnpm test before declaring any task done.
The "looks wrong, is deliberate" section is the one most projects skip and the one that saves the most corrections.
Prompts for the tools this applies to
Related terms
- AGENTS.md
AGENTS.md is a tool-neutral convention for a Markdown file in a repository that gives AI coding agents the project context they need — build commands, conventions, architecture, and constraints.
- Cursor rules
Cursor rules are project-level instructions stored in your repository that Cursor applies to every AI request — conventions, framework versions, patterns to follow, things never to do.
- Custom instructions
Custom instructions are standing directions you give an AI tool that apply to every request rather than a single one — preferred language and framework, response style, conventions to follow.
- Context engineering
Context engineering is the practice of deciding what information an AI model sees for a given task — which files, which conventions, which prior results — and in what form.