CLAUDE.md Files - Claude Code

CLAUDE.md is the canonical place to put project-specific instructions. Claude reads it automatically every session, so you don't have to re-explain the same context.

What it does

A CLAUDE.md at the repo root becomes part of the system context. Nested CLAUDE.md files in subdirectories layer in when Claude works in those paths. Use it for stack overview, conventions, critical rules, common commands, and anything you'd otherwise repeat in every prompt.

When to use it

• Coding standards that should never be broken (style, banned patterns, design rules).
• Architecture overviews so Claude understands module boundaries.
• Stack-specific commands (how to run tests, build, deploy).
• Team-wide prompts you want every contributor's Claude to see.

Gotchas

• Huge CLAUDE.md files eat context budget. Keep it focused - 500 lines is already a lot.
• Nested files stack, they don't replace. A conflicting rule deep in the tree still fires.
• It's committed, so don't put secrets or personal preferences there. Use ~/.claude/CLAUDE.md for those.

Official docs: https://code.claude.com/docs/en/memory.md