writing-claude-md-files

# 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

```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/