CLAUDE.md – onboarding for your AI teammate

Every Claude Code session starts from zero. Claude doesn't know your project, your conventions, or why you'd better not touch module X.

That's exactly what CLAUDE.md is for: a plain Markdown file in your project that Claude reads automatically at the start of every session. Essentially the onboarding document you'd hand a new team member on day one.

Getting started takes a single command:

/init

Claude analyzes the project and drafts a first version. Review it, trim it, and your foundation is in place.

What belongs in it?

🏗️ Architecture in a few sentences: what lives where, and how do the modules fit together?
⚙️ The key commands: build, tests, lint, local start.
📏 Conventions that aren't obvious: naming schemes, branch rules, "we always use signals instead of BehaviorSubject".
⚠️ Pitfalls: "Never change the legacy API under /v1, a client system depends on it."

What doesn't belong in it?

Platitudes like "write clean code" and anything a linter already checks. The file is loaded in every session and takes up context. Short and precise beats long and complete.

Three tips from practice:

• CLAUDE.md belongs in your Git repository. The whole team benefits, and changes go through review just like code.
• Don't paste in lengthy docs. Reference them via import instead, e.g. @docs/architecture.md.
• If you're explaining the same thing to Claude a second time, it belongs in CLAUDE.md.

There's also a personal file at ~/.claude/CLAUDE.md for your own preferences across all projects.

My rule of thumb:

• Applies to (almost) every task in the project? CLAUDE.md.
• Only for a specific workflow? Skill (see parts 1 and 3).

What's the first thing in your CLAUDE.md? I'd love to hear in the comments

Join the discussion on LinkedIn →