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:

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

[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

[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

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

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.

date +%Y-%m-%d

Include in file:

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:

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