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

Claude

Posted on May 15, 2026May 15, 2026 | by rajeshkumar

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

Goes in root `CLAUDE.md`	Goes in per-repo `CLAUDE.md`
System architecture and how repos relate	This repo’s folder structure
Cross-repo workflows (e.g., signup spans 3 services)	Entry points and main modules
Shared conventions (commit style, PR rules, branch naming)	Local build, test, and run commands
Glossary of domain terms	Repo-specific gotchas and quirks
Tech stack overview across repos	Internal patterns and idioms
Deployment topology	Dependencies and external integrations specific to this repo

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

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.
Create per-repo files. Inside each repo, run /init in Claude Code to auto-generate a starter CLAUDE.md, then refine it by hand.
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.