CLAUDE.md: Your Project's Brain

What Goes In It

• CLAUDE.md lives at your project root and is automatically loaded into every Claude Code session — think of it as your project's operating manual for AI.
• What to put in it
  • › Build commands — so AI can compile and test without guessing
  • › Project structure — which directories contain what
  • › Naming conventions — how you name files, components, branches
  • › Architecture patterns — the decisions behind your code
  • › Gotchas — things that trip up newcomers (and AI)
• What NOT to put in it
  • › Things derivable from code (function signatures, imports)
  • › Git history (use git log)
  • › Temporary notes (use tasks instead)
• The file compounds in value — every gotcha you add saves time in every future session across every team member.

Why It Changes Everything

1. 1 Without CLAUDE.md, every AI session starts from zero — the AI guesses your conventions and gets them wrong. With it, the AI behaves like a team member who's read the onboarding docs.
2. 2 Create a CLAUDE.md at your project root with your build command and one naming convention — watch the difference in AI responses
3. 3 Add your project's top 3 gotchas — the things that trip up newcomers are exactly what trips up AI
4. 4 Commit CLAUDE.md to git so the entire team benefits from the same AI context