Anatomy of CLAUDE.md

Team memory, conventions, patterns, and living architecture.

CLAUDE.md

The project memory and "contract" that tells Claude how your project really works.

TL;DR

CLAUDE.md is a markdown file at the repo root that Claude reads first.
It encodes your stack, conventions, architecture, and guardrails.
Keep it short (≤ 300 lines), specific, and current.
Treat it like a living onboarding doc — for humans and the AI.
Update it whenever a real-world decision changes.

Why this matters

Think of CLAUDE.md as the employee handbook you hand to a brilliant new hire on day one. Without it, they guess. With it, they ship like a senior teammate.

Bottom line: A great CLAUDE.md is the single highest-leverage file in your repo.

The Big Picture

Bottom line: Context flows top-down — CLAUDE.md sets the tone for everything else.

Ideal Structure (sections to include)

Section	Purpose
Project overview	One paragraph: what this repo is
Tech stack	Languages, frameworks, versions
Project layout	Folder responsibilities
Conventions	Naming, commits, style
Workflows & commands	How to build/test/deploy
Testing strategy	What "done" means
Security & data handling	Non-negotiables
Do's & don'ts	Quick guardrails
Integrations & MCP servers	External tools available
Known issues / gotchas	Save future-debug time
Pitfalls to avoid	Past mistakes encoded
Important project history	Why things are the way they are

Step-by-Step Setup

1. Create the file

touch CLAUDE.md

2. Drop in the skeleton

# Project: <your-project>
> One-line summary of what this project does.

## 1. Tech Stack
- Next.js 14 (App Router) · TypeScript · Tailwind CSS
- Supabase (Auth, Postgres, Storage)
- Prisma ORM · tRPC API · Zod validation

## 2. Project Layout
- `src/app/`        → Routes (App Router)
- `src/components/` → Reusable UI components
- `src/services/`   → Business logic
- `src/utils/`      → Helpers & utilities
- `prisma/`         → Schema & migrations
- `tests/`          → Unit & integration tests

## 3. Conventions
- Use TypeScript strict mode.
- Prefer server components; use client only when needed.
- Use functional components & hooks.
- File names: kebab-case. Components: PascalCase.
- Export types explicitly.

## 4. Workflows
- Dev:   `npm run dev`
- Build: `npm run build`
- Test:  `npm test`
- MCP:   GitHub, Postgres, Slack (see `.mcp.json`)

## 5. Testing
- Vitest for units; Playwright for e2e.
- Min 80% line coverage on `src/services`.
- Write tests **before** implementation.

## 6. Security
- No secrets in code or logs.
- Validate all user input with Zod.
- Parameterized queries only.

## 7. Git
- Conventional commits (`feat:`, `fix:`, `chore:`).
- Never commit directly to `main`.
- PRs require: green CI + 1 reviewer.

## 8. Known Issues
- Prisma migrations must be applied before deploy.
- Tailwind purges class names built dynamically — use safelist.

## 9. Do / Don't
✅ Be specific and concrete.
✅ Reference docs/ for depth.
❌ Don't include vague statements.
❌ Don't put secrets here.

3. Commit it

git add CLAUDE.md && git commit -m "docs: add CLAUDE.md"

4. Iterate every sprint

Add one section each time you notice Claude getting something wrong.

Variants for Different Team Settings

👤 Solo developer

Keep it ≤ 100 lines. Skip "Git" rules; focus on stack + conventions.

👥 Small team (2–10)

Add Workflows, Testing, and Git rules. Reference docs/onboarding.md for depth.

🏢 Enterprise / regulated

Add Security, Compliance, and Data classification sections.
Link to internal policy docs.
Lock changes behind a code-owner review.

## Compliance
- All PRs must pass `policy-check.sh`.
- PII access requires `@security-auditor` review.
- Data residency: EU only.

🌍 Open-source

Include Contribution guide + Code of Conduct links.
Make examples newcomer-friendly.
Mark decisions ([DECISION]) so contributors don't relitigate them.

Bottom line: Same skeleton, escalating depth.

Anatomy of a Single Section (zoom-in)

## Conventions
- **Language:** TypeScript strict mode (`"strict": true`).
- **Style:** Prettier defaults + ESLint recommended.
- **Naming:** files `kebab-case`, components `PascalCase`, vars `camelCase`.
- **Imports:** absolute paths via `@/` alias.
- **Comments:** only "why", never "what".

Notice: concrete, enforceable, terse.

Common Patterns & Recipes

Pattern 1 — Reference external docs

> For deep architecture details, see `docs/architecture.md`.

Pattern 2 — Encode a non-negotiable

> ⛔ **NEVER** call third-party APIs without a retry + timeout wrapper.

Pattern 3 — Few-shot a convention

### Commit messages — examples
✅ `feat(auth): add magic-link login`
✅ `fix(api): handle 429 from Stripe`
❌ `update stuff`

Pattern 4 — Decision log

## Decisions
- [2026-03-12] Chose tRPC over REST for type safety. (Owner: @vk)
- [2026-04-08] Adopted Prisma migrations as the source of truth.

Best Practices ✅

Be specific & concrete — examples over adjectives.
Show examples for every convention.
Keep it concise (< 300 lines).
Update when things change.
Link to docs for depth instead of inlining everything.

Anti-Patterns ❌

Vague statements ("write clean code").
Outdated info (last edited 9 months ago).
Secrets or tokens.
Walls of text with no structure.
Internal jokes nobody outside the team understands.

Troubleshooting

Symptom	Cause	Fix
Claude ignores rules	File too long / vague	Trim to bullets, add examples
Wrong stack assumed	Stack section missing	Pin versions explicitly
Repeated mistakes	No "anti-patterns" section	Add it; cite real examples
Drift over time	Not updated	Add to PR checklist: "Updated CLAUDE.md?"
Sensitive leak risk	Secrets in file	Remove; reference env vars

Starter Template (the bare minimum)

# Project: <name>
> One-line summary.

## Tech Stack
-

## Workflows
- Dev:
- Build:
- Test:

## Conventions
-

## Security
-

## Notes
-

💡 Tip: Treat CLAUDE.md like a README for Claude. Keep it living & true.

Glossary

CLAUDE.md — Root-level memory file Claude reads first.
Convention — A rule the team agrees to follow consistently.
Decision log — A dated record of architectural choices.
Guardrail — A non-negotiable safety/quality rule.

TL;DR​

Why this matters​

The Big Picture​

Ideal Structure (sections to include)​

Step-by-Step Setup​

1. Create the file​

2. Drop in the skeleton​

3. Commit it​

4. Iterate every sprint​

Variants for Different Team Settings​

👤 Solo developer​

👥 Small team (2–10)​

🏢 Enterprise / regulated​

🌍 Open-source​

Anatomy of a Single Section (zoom-in)​

Common Patterns & Recipes​

Pattern 1 — Reference external docs​

Pattern 2 — Encode a non-negotiable​

Pattern 3 — Few-shot a convention​

Pattern 4 — Decision log​

Best Practices ✅​

Anti-Patterns ❌​

Troubleshooting​

Starter Template (the bare minimum)​

Glossary​

Further Reading​