Introducing CLAUDE.md — Your Project’s Memory for Claude

What is CLAUDE.md?

CLAUDE.md is a plain markdown file that Claude Code reads automatically every time you start a session. It’s how you give Claude persistent context about your project — architecture, conventions, commands, gotchas — so you don’t have to re-explain everything each time you come back.

Think of it as an onboarding document, but written for Claude instead of a new teammate.

How Claude Loads It

When you run Claude Code from any directory, it walks upward through the folder tree and loads every CLAUDE.md it finds. The files stack — Claude reads all of them together. No manual loading, no special commands.

That’s why a two-layer setup works so well for multi-repo projects.

The Two-Layer Setup

Layer 1 — Root CLAUDE.md (parent project folder)

Lives at the workspace root, above all your repos:

~/projects/my-app/
├── CLAUDE.md          ← root (shared context)
├── repo-frontend/
├── repo-backend/
└── repo-shared-lib/

This file holds cross-cutting context — things that are true for the whole project, not just one repo.

Layer 2 — Per-repo CLAUDE.md (inside each service/repo)

Lives inside each repo folder:

repo-backend/
├── CLAUDE.md          ← repo-specific context
├── src/
└── package.json

This file holds repo-specific details — folder layout, local commands, internal patterns unique to that codebase.

When you work inside repo-backend/, Claude automatically loads both repo-backend/CLAUDE.md and the root CLAUDE.md. You get the big picture and the local detail at the same time.

Rule of Thumb — What Goes Where

Quick test when you’re unsure: if the info is true for more than one repo, lift it to the root. If it only matters when working inside one specific repo, keep it there.

Getting Started in 3 Steps

1. Create the root file. From your project root, create CLAUDE.md and write a short overview: what the project does, list of repos with one-line descriptions, shared conventions.
2. Create per-repo files. Inside each repo, run /init in Claude Code to auto-generate a starter CLAUDE.md, then refine it by hand.
3. Keep it alive. Treat CLAUDE.md like code — review it in PRs, update it when conventions change, delete stale parts. The more current it is, the better Claude works.

Tips

• Keep each file under ~500 lines. Long context files get skimmed, not read carefully.
• Commit CLAUDE.md to git so the whole team benefits.
• For personal or sensitive notes, use CLAUDE.local.md (add it to .gitignore).
• If the same info is repeating across repo files, lift it to the root. If the root is getting bloated with details only one repo cares about, push them down.