CLAUDE.md: what it is and how to write one
Updated Oct 26, 2026 · Sources listed at the end
CLAUDE.md is a Markdown file of instructions that Claude Code loads at the start of every session, so it knows your build and test commands, coding standards and conventions without being told each time.1 Each session starts with a fresh context window; CLAUDE.md (plus Claude’s own “auto memory”) is how knowledge carries over.1
Where to put it
| File | Use | Shared with |
|---|---|---|
~/.claude/CLAUDE.md | Personal preferences for all projects | Only you |
./CLAUDE.md or ./.claude/CLAUDE.md | Project architecture, standards, workflows | Your team via source control |
./CLAUDE.local.md | Personal, project-specific notes (add to .gitignore) | Only you |
Source: Claude Code memory docs.1
Getting started
Run /init and Claude analyses the codebase and writes a starting CLAUDE.md with build commands, test instructions and conventions it finds; if one exists, it suggests improvements instead of overwriting.1 Run /context to confirm it loaded.1
Writing tips from the docs
- Be specific: “Use 2-space indentation” works better than “format code nicely”.
- Remove conflicting instructions across files.
- If something must happen at a fixed point (before every commit), use a hook instead.1
CLAUDE.md and AGENTS.md
Claude Code can read a repository’s AGENTS.md in place of CLAUDE.md, but by default only when there is no CLAUDE.md in the working directory or above it.1
Footnotes
Tools mentioned
- Claude Code: paid from $20/mo