10 minutes to a CLAUDE.md that actually teaches Claude how your project works.
Every time a new developer joins a project — or you hand a project to a contractor, or you start using Claude Code on a new codebase — there's a tax. The person reads the README, asks questions for a week, gets up to speed slowly. A CLAUDE.md with an onboarding section collapses that timeline.
This checklist is for the person writing the CLAUDE.md. If you're the new arrival, skip to the FAQ at the bottom.
Most CLAUDE.md files brief Claude on the person writing the code. An onboarding CLAUDE.md briefs Claude on the project — the context, conventions, and tribal knowledge that lives in the heads of the existing team.
The difference matters: you write yourself a CLAUDE.md so Claude understands you. You write an onboarding CLAUDE.md so Claude understands this codebase — and can onboard someone else by proxy.
Work through these sections in order. Each one is a section you add to your CLAUDE.md.
Before anything else, state what this project is. A new person reading the CLAUDE.md needs to know the name, what it does, and who it's for — without digging through a README.
## What this project is
[Product name] — [one sentence on what it does]. [Who uses it / who it serves].
[One sentence on current stage: "in active development," "maintenance mode," "pre-launch."]
## Who maintains this
[Name] — [role]. [Contact / Slack handle / GitHub handle if relevant].
New team members always waste time figuring out which tools are in play. Name them here, with versions where it matters.
## Stack
- Language + version: [e.g., Python 3.12, Node 20]
- Framework(s): [e.g., Next.js 15, FastAPI]
- Package manager: [e.g., pnpm, uv, Poetry — Claude defaults to pip/npm and will corrupt your lockfile if you don't specify]
- Database: [Postgres 16, SQLite, DynamoDB]
- Deploy target: [Vercel, Render, Fly.io, etc.]
## Local setup
- `npm install` installs all dependencies.
- `npm run dev` starts the dev server at http://localhost:3000.
- `.env` required — copy from 1Password: [vault/item path].
- If you see `node:internal/errors: Cannot find module`, run `npm install` first.
One of the highest-value things you can put in an onboarding CLAUDE.md: a walkthrough of the folder structure. What lives where, and why.
## Folder structure
- src/ — application code
- tests/ — [what kind: unit, e2e, both]
- docs/ — [what lives here: runbooks, architecture decisions]
- scripts/ — [what runs here: build scripts, one-off tools]
- [anything non-obvious like a monorepo workspace structure]
The folder structure section prevents the "I didn't know this existed" problem that compounds over time.
New team members lose hours finding the right command to run the tests, start the server, or deploy. Put it in the CLAUDE.md.
## Common commands
```bash
npm run dev # start dev server
npm test # run unit tests
npm run test:e2e # e2e tests (requires dev server)
npm run lint # lint + typecheck
npm run build # production build
Include the commands you actually run daily. Leave out the ones that exist but nobody uses.
### 5. Decision log — the "why" the code doesn't explain
Projects make decisions over time that don't live in the code. "We went with SQLite because Postgres was overkill for the edge case we were solving." "We chose not to use Redux because Zustand was sufficient and added less overhead."
An onboarding CLAUDE.md should capture the decisions that would otherwise have to be learned by asking someone.
### 6. Where not to edit
Every codebase has places that look editable but aren't. Generated files. Locked configs. Third-party vendor code. Name them so Claude doesn't touch them and so a new developer doesn't waste time reading them.
### 7. How to ship a change
What happens after a developer writes code? Branch strategy, testing requirements, who reviews, how to deploy. A new team member should be able to look at this section and know their first pull request workflow.
git checkout -b feat/your-feature-namenpm test before pushing.npm run lint passes locallynpm test passes
### 8. Current priorities and known problems
A new team member who reads this section will immediately know what's in flight and what to stay away from. A developer just joining will waste less time asking about a known issue that's already being tracked.
### 9. Who to ask and when
An onboarding CLAUDE.md should set expectations about how to get unblocked. Who to ping for what. When to ask vs. when to just figure it out.
### 10. Offboarding and context handover
When someone finishes their time on the project — or when you're handing off to the next person — the CLAUDE.md should make the handoff trivial. Add a section that captures the current state:
## The complete onboarding CLAUDE.md
Here's the template assembled:
```markdown
# CLAUDE.md — [Project name]
## What this project is
[Product name] — [one sentence]. [Stage: active dev / maintenance / etc.]
## Stack
- Language: [version]
- Framework: [name + version]
- Package manager: [name — Claude will default wrong if you don't say]
- Database: [what + version]
- Deploy target: [where]
## Local setup
```bash
npm install # first time only
npm run dev # start dev server
npm test # run tests
.env required — see 1Password: [vault path].
npm run dev
npm test
npm run lint
npm run build
git checkout -b feat/your-featurenpm test.
## FAQ
**How long should an onboarding CLAUDE.md be?**
Under 200 lines. If you're pushing 400, split it: a root CLAUDE.md for cross-cutting rules and a `CLAUDE.local.md` in each subdirectory for team-specific context. Claude only reads the relevant nested file depending on what directory you're working in.
**Should I put an onboarding CLAUDE.md in a new repo or an existing one?**
New repos benefit most — onboarding cost is highest when there's nothing. Add this as part of your README setup checklist: "create CLAUDE.md before writing any code." It takes ten minutes and saves a full week of onboarding questions over the first three months.
**Who should write the onboarding CLAUDE.md?**
The person who's been on the project longest. But also: the person who's leaving. If someone is finishing their time on a project, adding a "current state" section to the CLAUDE.md is the highest-leverage thing they can do in their last sprint.
**Should contractors and AI pair-programmers get different CLAUDE.md files?**
Use `CLAUDE.local.md` (gitignored by default) for contractor-specific rules — they shouldn't see team-internal context. An AI pair-programmer gets the same files as a human developer, but you can add an explicit section noting that it should use the `#` shortcut to update the file when it learns something useful.
**What's the difference between an onboarding CLAUDE.md and a team CLAUDE.md?**
An onboarding CLAUDE.md is specifically for the handoff moment — it explains the project as it exists today. A team CLAUDE.md evolves over time as the project changes. Think of onboarding as a snapshot; team CLAUDE.md is the running document.
**Should I put this in CLAUDE.md or a README?**
Both, but different things. README is for humans reading it end-to-end. CLAUDE.md is for Claude, which means it needs to be in imperative, directive form — not narrative prose. Put the narrative in README; put the directives in CLAUDE.md.
Practical guides and prompt patterns — no fluff, unsubscribe any time.