CLAUDE.md — your project's brain
Give Claude permanent context with a single markdown file
⏱ Est. ~4 min
01 · Read
Every time you start a new Claude Code session, Claude starts from a blank slate. It doesn't remember your last conversation, your code style, your project conventions, or even what framework you use. You have to re-explain everything each time.
CLAUDE.md solves this. It's a markdown file Claude reads at the start of every session — a permanent instruction manual for your project.
💡 Picture thisThink of CLAUDE.md as the onboarding doc for a new teammate. Instead of explaining team conventions every morning, you write it once. CLAUDE.md is that doc — Claude reads it every time it "starts working".
Key points
- Every Claude Code session starts from scratch — no memory of past conversations
- CLAUDE.md loads automatically at the start of every session
- It tells Claude your project rules, conventions, and important context
- It's just a markdown file — edit it like any other file
02 · Read
CLAUDE.md can live in three places, each with a different scope.
Project level — put CLAUDE.md in the repo root (or .claude/CLAUDE.md). Share it with your team via git. Use it for project conventions, build commands, architecture patterns.
User level — put it in ~/.claude/CLAUDE.md. Personal, applies to all your projects. Use it for your personal preferences.
Subdirectory — CLAUDE.md files in subdirectories load on demand when Claude reads files in that directory. Good for module-specific instructions.
Key points
- Project level (./CLAUDE.md): shared with the team, committed to git
- User level (~/.claude/CLAUDE.md): personal, all your projects
- Subdirectory CLAUDE.md: loads on demand for specific modules
- When they conflict, project rules override user rules
03 · Code example
A good CLAUDE.md includes build commands, code style, architecture, and project-specific conventions. Here's a real example.
Example CLAUDE.md
# Build & Test
- `npm run dev` — start frontend dev server
- `npm run build` — TypeScript check + production build
- `npm test` — run tests (Vitest)
# Code Style
- TypeScript strict mode, ES modules (import/export)
- 2-space indentation, single quotes
- Functional React components, no class components
# Architecture
- API routes in `server/src/routes/`
- Database schema in `server/src/db/schema.ts`
- Frontend components in `src/components/`
# Important
- The `--color-purple` CSS variable is actually orange (#FF6B35)
- Auth cookies use sameSite: 'none' for cross-origin
Notice what's included: things Claude can't discover just by reading code. Build commands, unusual naming conventions, cross-source quirks. Don't include things Claude can find by exploring — focus on what isn't obvious.
04 · Code example
When your CLAUDE.md gets big, you can split it into focused files using imports and a rules directory.
CLAUDE.md with @imports
# Project Overview
See @README.md for project description
See @specs/ARCHITECTURE.md for system design
# Code Style
@docs/code-style.md
Rules directory structure
.claude/
├── CLAUDE.md (main instructions)
└── rules/
├── api-design.md (API conventions)
├── testing.md (test patterns)
└── security.md (security rules)
The @ prefix imports another file's contents into CLAUDE.md. The .claude/rules/ directory holds topic-specific rules that Claude loads automatically. Keep the main CLAUDE.md lean while giving Claude access to detailed domain knowledge.
05 · Quiz
You have project conventions every developer on your team should follow. Where should your CLAUDE.md live to share it with the team?
- Your home directory (~/.claude/CLAUDE.md)
- Repo root (./CLAUDE.md), committed to git
- A Google Doc linked from the README
- A pinned message in a Slack channel
06 · Fill in the blank
To import another file into CLAUDE.md, prefix the path with _____
Other lessons in this chapter
⚠ The full interactive experience needs JavaScript. Please enable it and reload.
※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.