Setting up CLAUDE.md so Claude understands your project

The first time you run /init in a new repo, Claude generates a CLAUDE.md at the root. That file gets loaded into every future Claude Code session in that project. It's the cheapest investment with the biggest return — five minutes of editing saves hours of "remind Claude how this project works" later.

What goes in it

Treat CLAUDE.md as a short briefing for a smart engineer joining the team Monday. Cover the things that aren't obvious from reading the code:

# Project Structure
- Frontend (Next.js) and backend (Python/FastAPI) are separate projects.
  Always confirm which project a change belongs to before editing.
- Primary stack: TypeScript, Python, Supabase (database), Vercel + Railway.

# Deployment
- Always push to git AND deploy to Vercel after completing features.
- After deploy, verify the live URL returns 200 before reporting success.
- Batch related fixes into a single deploy cycle. Never deploy per-fix.

# Database
- Verify table schemas with SELECT before assuming columns are missing.
- Check NOT NULL constraints won't conflict with seed data.

# Bug Fixes
- Run `npm run build` to catch import errors before pushing.
- For CSS issues, check for !important overrides — don't apply narrow fixes
  that miss root causes.

The pattern: rules that cost the team something when violated. Deploy gotchas, test conventions, schema quirks, naming conventions that aren't enforced by the linter, the hard-won lessons from past incidents.

What to leave out

• Anything inferable from the code. Don't list file paths Claude can find or grep for. Don't describe what userController.ts does — Claude will read it.
• Resolved bugs. Don't keep "the auth bug from January" in the file forever — it rots. Either the fix held (so the lesson is in the diff) or it didn't (so put the rule in CLAUDE.md once, not the war story).
• TODOs. Use a TODO file or your issue tracker. CLAUDE.md is for invariants.
• Secrets, API keys, internal URLs. It's checked into the repo.

Layered context: project, user, and personal CLAUDE.md

Claude Code reads three layers of CLAUDE.md:

1. Project-level — ./CLAUDE.md at the repo root. Shared with the team via git. Use this for rules that apply to everyone.
2. Subdirectory-level — frontend/CLAUDE.md, backend/CLAUDE.md. Loaded only when working in that subtree. Use this when frontend and backend have different conventions and you don't want to bloat the root file.
3. User-level — ~/.claude/CLAUDE.md on your machine. Personal. Not committed. Use this for "I prefer terse responses" or "always run prettier before committing in any project."

Claude merges all three. More specific overrides less specific.

Keep it tight

The file is loaded into context on every session. Long files cost tokens and dilute the signal. Aim for under 200 lines. If you find yourself adding a fourth rule about the same topic, that topic probably belongs in its own doc that CLAUDE.md links to.

A good CLAUDE.md reads like a senior engineer's onboarding cheat sheet: short, specific, and battle-tested.

Maintain it the same way you maintain code

When you fix a bug whose root cause was "Claude didn't know X," add X. When a rule turns out to be wrong, delete it. Treat changes to CLAUDE.md as commits — review them, write good messages, and roll them back if they cause regressions.

What to do after you write it

• Run a single non-trivial task in the project. Watch where Claude still gets things wrong. Add those gaps.
• Read the Claude Code slash commands guide — /plan, /review, and /init compound with a good CLAUDE.md.
• Browse free Claude Code skills — many of them slot in cleanly once Claude knows your project.