Writing CLAUDE.md Files
REQUIRED BACKGROUND: Read ed3d-extending-claude:writing-claude-directives for foundational guidance on token efficiency, compliance techniques, and directive structure.
Core Principle
CLAUDE.md files bridge Claude's statelessness. They preserve context so humans don't re-explain architectural intent every session.
Key distinction:
- •Top-level: HOW to work in this codebase (commands, conventions)
- •Subdirectory: WHY this piece exists and what it PROMISES (contracts, intent)
File Hierarchy
Claude automatically reads CLAUDE.md files from current directory up to root:
code
project/
├── CLAUDE.md # Project-wide: tech stack, commands, conventions
└── src/
└── domains/
├── auth/
│ ├── CLAUDE.md # Auth domain: purpose, contracts, invariants
│ └── oauth2/
│ └── CLAUDE.md # OAuth2 subdomain (rare, only when needed)
└── billing/
└── CLAUDE.md # Billing domain: purpose, contracts, invariants
Depth guideline: Typically one level (domain). Occasionally two (subdomain like auth/oauth2). Rarely more.
Top-Level CLAUDE.md
Focuses on project-wide WHAT and HOW.
What to Include
| Section | Purpose |
|---|---|
| Tech Stack | Framework, language, key dependencies |
| Commands | Build, test, run commands |
| Project Structure | Directory overview with purposes |
| Conventions | Naming, patterns used project-wide |
| Boundaries | What Claude can/cannot edit |
Template
markdown
# [Project Name] Last verified: [DATE - use `date +%Y-%m-%d`] ## Tech Stack - Language: TypeScript 5.x - Framework: Next.js 14 - Database: PostgreSQL - Testing: Vitest ## Commands - `npm run dev` - Start dev server - `npm run test` - Run tests - `npm run build` - Production build ## Project Structure - `src/domains/` - Domain modules (auth, billing, etc.) - `src/shared/` - Cross-cutting utilities - `src/infrastructure/` - External adapters (DB, APIs) ## Conventions - Functional Core / Imperative Shell pattern - Domain modules are self-contained - See domain CLAUDE.md files for domain-specific guidance ## Boundaries - Safe to edit: `src/` - Never touch: `migrations/` (immutable), `*.lock` files
What NOT to Include
- •Code style rules (use linters)
- •Exhaustive command lists (reference package.json)
- •Content that belongs in domain-level files
- •Sensitive information (keys, credentials)
Subdirectory CLAUDE.md (Domain-Level)
Focuses on WHY and CONTRACTS. The code shows WHAT; these files explain intent.
What to Include
| Section | Purpose |
|---|---|
| Purpose | WHY this domain exists (not what it does) |
| Contracts | What this domain PROMISES to others |
| Dependencies | What it uses, what uses it, boundaries |
| Key Decisions | ADR-lite: decisions and rationale |
| Invariants | Things that must ALWAYS be true |
| Gotchas | Non-obvious traps |
Template
markdown
# [Domain Name] Last verified: [DATE - use `date +%Y-%m-%d`] ## Purpose [1-2 sentences: WHY this domain exists, what problem it solves] ## Contracts - **Exposes**: [public interfaces - what callers can use] - **Guarantees**: [promises this domain keeps] - **Expects**: [what callers must provide] ## Dependencies - **Uses**: [domains/services this depends on] - **Used by**: [what depends on this domain] - **Boundary**: [what should NOT be imported here] ## Key Decisions - [Decision]: [Rationale] ## Invariants - [Thing that must always be true] ## Key Files - `index.ts` - Public exports - `types.ts` - Domain types - `service.ts` - Main service implementation ## Gotchas - [Non-obvious thing that will bite you]
Example: Auth Domain
markdown
# Auth Domain Last verified: 2025-12-17 ## Purpose Ensures user identity is verified exactly once at the system edge. All downstream services trust the auth token without re-validating. ## Contracts - **Exposes**: `validateToken(token) → User | null`, `createSession(credentials) → Token` - **Guarantees**: Tokens expire after 24h. User objects always include roles. - **Expects**: Valid JWT format. Database connection available. ## Dependencies - **Uses**: Database (users table), Redis (session cache) - **Used by**: All API routes, billing domain (user identity only) - **Boundary**: Do NOT import from billing, notifications, or other domains ## Key Decisions - JWT over session cookies: Stateless auth for horizontal scaling - bcrypt cost 12: Legacy decision, migration to argon2 tracked in ADR-007 ## Invariants - Every user has exactly one primary email - Deleted users are soft-deleted (is_deleted), never hard deleted - User IDs are UUIDs, never sequential ## Key Files - `service.ts` - AuthService implementation - `tokens.ts` - JWT creation/validation - `types.ts` - User, Token, Session types ## Gotchas - Token validation returns null on invalid (doesn't throw) - Never return raw password hashes in User objects
Freshness Dates: MANDATORY
Every CLAUDE.md MUST include a "Last verified" date.
CRITICAL: Use Bash to get the actual date. Do NOT hallucinate dates.
bash
date +%Y-%m-%d
Include in file:
markdown
Last verified: 2025-12-17
Why mandatory: Stale CLAUDE.md files are worse than none. The date signals when contracts were last confirmed accurate.
Referencing Files
You can reference key files in CLAUDE.md:
markdown
## Key Files - `index.ts` - Public exports - `service.ts` - Main implementation
Do NOT use @ syntax (e.g., @./service.ts). This force-loads files into context, burning tokens. Just name the files; Claude can read them when needed.
Heuristics: Top-Level vs Subdirectory
| Question | Top-level | Subdirectory |
|---|---|---|
| Applies project-wide? | ✓ | |
| New engineer needs on day 1? | ✓ | |
| About commands/conventions? | ✓ | |
| About WHY a component exists? | ✓ | |
| About contracts between parts? | ✓ | |
| Changes when the domain changes? | ✓ |
Rule of thumb:
- •Top-level = "How to work here"
- •Subdirectory = "Why this exists and what it promises"
When to Create Subdirectory CLAUDE.md
Create when:
- •Domain has non-obvious contracts with other parts
- •Architectural decisions affect how code should evolve
- •Invariants exist that aren't obvious from code
- •New sessions consistently need the same context re-explained
Don't create for:
- •Trivial utility folders
- •Implementation details that change frequently
- •Content better captured in code comments
Updating CLAUDE.md Files
When updating any CLAUDE.md:
- •Update the freshness date using Bash
date +%Y-%m-%d - •Verify contracts still hold - read the code, check invariants
- •Remove stale content - better short and accurate than long and wrong
- •Keep token-efficient - <300 lines top-level, <100 lines subdirectory
Common Mistakes
| Mistake | Fix |
|---|---|
| Describing WHAT code does | Focus on WHY it exists, contracts it keeps |
| Missing freshness date | Always include, always use Bash for real date |
| Using @ to reference files | Just name files, let Claude read on demand |
| Too much detail | Subdirectory files should be <100 lines |
| Duplicating parent content | Subdirectory inherits parent; don't repeat |
| Stale contracts | Update when domain changes; verify dates |
Checklist
Top-level:
- • Tech stack listed
- • Key commands documented
- • Project structure overview
- • Freshness date (from
date +%Y-%m-%d)
Subdirectory:
- • Purpose explains WHY (not what)
- • Contracts: exposes, guarantees, expects
- • Dependencies and boundaries clear
- • Key decisions with rationale
- • Invariants documented
- • Freshness date (from
date +%Y-%m-%d) - • Under 100 lines