CLAUDE.md Architecture

What this lesson covers

Every Claude Code session starts cold. Claude has no memory of your project, your conventions, or the decisions you made last week. CLAUDE.md is how you solve that permanently.

What CLAUDE.md actually does

CLAUDE.md is injected into Claude's context at the start of every session — not cached, read fresh each time. This means:

• Every session starts briefed, not blank
• Changes take effect immediately next session
• It's the only persistent memory Claude has about your project

Think of it as a briefing document for an expert contractor who just walked in. Not a tutorial. Not documentation. A briefing — dense, operational, current.

The six-section architecture

A production CLAUDE.md has exactly six sections. Anything outside this structure is usually noise.

1. Project identity — What this is, who it's for, the core value prop in two sentences. Claude needs this to make judgment calls: "would this change be appropriate for this project?"

2. Tech stack (exact versions) — Not just "React" — specify library, version, pattern, and configuration. Next.js 15 App Router with TypeScript 5.4 — not Pages Router is the level of specificity that prevents wrong decisions.

3. Critical rules — Absolute constraints. Anything Claude must never do. If a constraint is non-obvious, explain why — context helps Claude generalize the rule correctly to situations you didn't anticipate.

4. Common commands — The exact commands for your specific setup. Not general patterns — the actual command Claude should run for build, test, type check, and lint.

5. Directory structure — A one-level-deep map of where things live and which directories are off-limits.

6. Current work — What's in progress right now. This section changes most frequently and has the highest value per word.

Annotated real example

This is the CLAUDE.md from this platform — annotated line by line:

# Project: AI Execution Lab

## What this is
Next.js 15 App Router content + learning platform for AI operator training.
Deployed on Vercel. Content is MDX files in /content/. No backend database.

## Tech stack
- Runtime: Node.js 20 / TypeScript 5.4
- Framework: Next.js 15 App Router (NOT Pages Router)
- Styling: Tailwind CSS 3.4
- Content: next-mdx-remote v6 (blockJS: false required — v6 breaking change)
- Deploy: Vercel (auto-deploy on push to master)

## Critical rules
- NEVER run `npm install` — npm is blocked on this machine
Use: node node_modules/next/dist/bin/next build
- NEVER import server-only modules (fs, path) in 'use client' components
Server code → lib/lesson-content.ts or suffix .server.ts
- ALWAYS run TypeScript before committing:
node node_modules/typescript/bin/tsc --noEmit
- NEVER modify files in /generated/ — auto-generated, changes are overwritten

## Common commands
```bash
# Build
node node_modules/next/dist/bin/next build

# Type check  
node node_modules/typescript/bin/tsc --noEmit

# Dev server
node node_modules/next/dist/bin/next dev
```

## Directory structure
```
app/           Route pages + API routes (App Router)
components/    React components — mdx/, tracks/, layout/, media/
content/       MDX files — docs/, systems/, lessons/[track]/[module]/
lib/           Utilities — lesson-content.ts is server-only
public/        Static assets
```

## Current work
- Building claude-code-operator flagship track (Module 2 content in progress)
- lib/lesson-content.ts imports fs — never import in client components
- Progress event bus: window.dispatchEvent('track:progress') for reactive sidebar

Notice what's absent: project history, general rationale, motivational framing, explanations of why TypeScript is good. CLAUDE.md is dense and operational.

The "Current Work" section is highest-value real estate

Every other section is static. Current Work updates every few sessions. It's high-value because it tells Claude what you're actively building — so it makes better decisions without re-explaining.

Pattern: At the end of a working session, update Current Work with what's in progress, what you learned, what's broken or unfinished.

Common CLAUDE.md mistakes

## About the project
This project was started in 2024 as a way to learn Next.js.
We decided to use TypeScript because it helps with type safety.
The architecture was inspired by Vercel's documentation site...

## What this is
Next.js 15 App Router content platform. MDX files in /content/.
Deployed to Vercel. No backend database.

## Rules
- Be careful with the database
- Don't break things
- Follow best practices

## Critical rules
- NEVER run raw SQL against production — use the migration system in /db/migrations/
- ALL database reads go through lib/db.ts — never import pg directly in routes
- Run `npm test` before ANY commit touching /lib/ or /api/

## Commands
Build: use npm to build
Tests: run the test suite

## Common commands
```bash
# Build (npm is blocked — use node directly)
node node_modules/next/dist/bin/next build

# Tests
node node_modules/jest/bin/jest.js --passWithNoTests
```

The CLAUDE.md refinement loop

Your first CLAUDE.md will be incomplete. The refinement loop:

1. Start a session — notice Claude makes a wrong assumption
2. Identify what context would have prevented it
3. Add it to CLAUDE.md in the relevant section
4. Next session: verify the assumption is now correct

After 3–5 sessions, your CLAUDE.md becomes genuinely useful. After 10–15, it becomes a reliable briefing document that meaningfully improves Claude's output on first response.

Slash commands that interact with CLAUDE.md