Module 03
CLAUDE.md: the project briefing
Developer Tools How Claude Code Works
Module 3 — CLAUDE.md: the project briefing
← Module 2 | Index | Next: Module 4 →
CLAUDE.md is the most important file you’ll ever write for Claude. Think of it as the onboarding document you’d hand a new team member: how this project is set up, what conventions to follow, what to avoid.
Claude automatically reads CLAUDE.md at the start of a session and treats it as standing instructions. So instead of repeating “we use tabs not spaces, run tests with make test, never touch the legacy folder” in every conversation, you write it once.
What goes in a good CLAUDE.md
- Project overview in a sentence or two (“This is a billing service written in Python”).
- How to run, build, and test things (the exact commands).
- Conventions and style rules (“use snake_case,” “all dates in UTC”).
- What not to do (“don’t edit
/vendor, it’s auto-generated”). - Anything you find yourself explaining more than once.
Where it can live
Claude reads several, and they stack:
- The project root
CLAUDE.md(shared with the team). - A personal
CLAUDE.mdin your home~/.claude/folder (applies to all your projects). CLAUDE.mdfiles in subfolders (apply when working in that part of the project).
Tips that separate beginners from pros
- Keep it tight. It’s loaded into context every session, so every line costs a little of the “working memory” budget you’ll learn about in Module 4. Be concise; prune what’s stale.
- Use it for decisions and conventions, not for things Claude can already see in the code. Don’t restate the obvious.
- When Claude does something wrong and you correct it, ask: “should this go in CLAUDE.md so I never explain it again?” Often, yes.
- In Cowork, the same idea appears as project instructions and a memory system — files that persist facts about you and your work across sessions.