How to Set Up CLAUDE.md So Claude Actually Understands Your Project

If you've ever re-explained your project to Claude Code for the third time this week — "no, the frontend and backend are separate," "no, we deploy to Railway not Vercel," "no, check the schema before assuming that table's missing" — you already know the problem. You just haven't fixed it yet.

There's a file for this. It's called CLAUDE.md, it probably already exists in your project, and five minutes of editing will save you from ever having that conversation again.

What it actually is

The first time you run /init in a Claude Code session, it generates a CLAUDE.md at the root of your project. That file loads into every future session in that project — automatically, before you type a word. Think of it as the onboarding doc you'd hand a smart new engineer on their first day: not what the code does (Claude can read that), but the stuff that isn't obvious from reading the code.

What actually belongs in it

The pattern that works: rules that cost you something when they're violated. Deploy gotchas. Schema quirks. The hard-won lesson from the incident three weeks ago. Not documentation — scar tissue.

# Project Structure
- Frontend (Next.js) and backend (Python/FastAPI) are separate projects.
  Always confirm which project a change belongs to before editing.

# Deployment
- Always push to git AND deploy 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.

Notice none of that is "here's what userController.ts does." Claude will read the file. Tell it the things the file can't tell it.

What to leave out

• Anything Claude can grep for. File paths, function descriptions — skip it.
• Resolved bugs. If the fix held, the lesson lives in the diff. Don't keep a war-story museum.
• TODOs. That's what your issue tracker is for.
• Secrets. It's checked into git. Obviously.

The three layers most people never find

Claude Code actually reads three of these, and merges them:

• Project-level (./CLAUDE.md) — checked into git, shared with your whole team.
• Subdirectory-level (frontend/CLAUDE.md, backend/CLAUDE.md) — only loaded when you're working in that folder. Use this when your frontend and backend genuinely have different rules and you don't want to bloat the root file.
• User-level (~/.claude/CLAUDE.md) — personal, not committed, applies across every project on your machine. "I prefer terse answers" or "always run prettier before committing" lives here.

More specific overrides less specific. A personal preference file and a shared team file both apply at once.

Keep it tight

This file loads into every session — long files cost tokens and dilute the signal. Aim under 200 lines. If you're adding a fourth rule about the same topic, that topic wants its own doc, linked from CLAUDE.md instead of buried in it.

Try it right now

Open your project in Claude Code and run:

/init

Then read the file it creates, all the way through, before you touch anything. Delete anything that reads like documentation instead of a hard-won rule. You're not writing a README. You're writing the thing you wish someone had told you on day one.

The same principle applies one level up when you're building with Cameron. The more specific, scar-tissue context you give your AI cofounder about your actual business, the less you repeat yourself. Meet Cameron →