What you’ll know by the end of this check

Why CLAUDE.md is the single highest-leverage file you can add to a repo
The hierarchy — project-level vs. user-level — and what goes where
Three patterns that make a CLAUDE.md stay useful instead of going stale

The shortest possible answer

CLAUDE.md is a markdown file at the root of your repo. Claude Code reads it on every session startup and appends it to your prompt. It’s how you stop re-explaining the project every time.

Without one: Claude re-explores your codebase, re-guesses your conventions, re-asks questions you’ve answered before.

With one: it already knows the stack, the commands, the style rules, and your hard constraints.

A CLAUDE.md that earns its keep

# Project

Next.js 15 (App Router), Tailwind, Drizzle ORM, deployed on Cloudflare.

# Commands

- Dev: `pnpm dev`
- Tests: `pnpm test`
- Lint: `pnpm lint`
- Deploy: `pnpm deploy` (publishes to Cloudflare Pages)

# Code style

- 2-space indent
- Named exports only
- API routes → server actions where possible
- No `any` types

# Hard rules

- Do NOT modify `src/schema/` without running the migration check
- Do NOT push to `main` directly — everything goes through a PR

That’s the whole file. Short and honest beats long and aspirational.

The hierarchy (what goes where)

Level	Location	What goes here
Project	`./CLAUDE.md` at repo root	Stack, commands, conventions, hard rules — shared with the team
User	`~/.claude/CLAUDE.md`	Your personal preferences across all projects (voice, defaults, workflow)

Both get loaded. Project rules win on conflicts because they’re closer to the code.

Three patterns that keep it alive

Save corrections to memory. If you find yourself typing “use server actions, not API routes” for the third time, ask Claude to add that rule to CLAUDE.md. Next session, it’s already there.
Reference project docs with @. Instead of pasting long explanations, write @README.md or @docs/architecture.md and Claude will pull in the referenced file when relevant.
Start without one. Run the first session without a CLAUDE.md. Watch where Claude fumbles. Add only the rules that would have prevented the stumbles. This keeps it lean. When you’re ready, run /init to have Claude draft the first version for you.

The staleness failure mode

A CLAUDE.md that hasn’t been touched in two months is worse than no CLAUDE.md. It lies about the codebase, and Claude follows the lie with confidence. Put it in code review. Update it when the stack shifts. Delete lines that no longer apply.

Things to try right now (10 minutes)

cd into a project you use daily.
Run claude, then /init to let Claude draft a starting CLAUDE.md from what it sees.
Read the draft. Cut anything aspirational. Add one hard rule you care about.
Commit it.

The canonical version

Full official lesson is at anthropic.skilljar.com/claude-code-101/469795.

Ready to verify this check?

You have a committed CLAUDE.md. It includes commands, style, and at least one hard rule. You know the difference between project-level and user-level. Mark it cleared.