---
name: claude-md-writing
description: Write effective CLAUDE.md files that give AI assistants the context they need. Use when creating new repos, improving existing CLAUDE.md files, or setting up projects.
---

# Writing Effective CLAUDE.md Files

CLAUDE.md is the project's context file for AI assistants. A good CLAUDE.md means Claude understands your project immediately without needing to explore.

## Purpose

CLAUDE.md answers: "What does Claude need to know to work effectively in this repo?"

- **Not a README** - README is for humans discovering the project
- **Not documentation** - Docs explain how to use the product
- **Context for AI** - What Claude needs to make good decisions

## Required Sections

### 1. One-Line Description

Start with what this repo is in one sentence.

```markdown
# Project Name

Brief description of what this project does.
```

### 2. Organization Context

Link to the bigger picture so Claude understands where this fits.

```markdown
## Organization Context

This repo is part of Flowmade. See:
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
- [Vision](./vision.md) - what this specific product does
```

### 3. Setup

How to get the project running locally.

```markdown
## Setup

\`\`\`bash
# Clone and install
git clone <url>
cd <project>
make install  # or npm install, etc.
\`\`\`
```

### 4. Project Structure

Key directories and what they contain. Focus on what's non-obvious.

```markdown
## Project Structure

\`\`\`
project/
├── cmd/           # Entry points
├── pkg/           # Shared packages
│   ├── domain/    # Business logic
│   └── infra/     # Infrastructure adapters
├── internal/      # Private packages
└── api/           # API definitions
\`\`\`
```

### 5. Development Commands

The commands Claude will need to build, test, and run.

```markdown
## Development

\`\`\`bash
make build    # Build the project
make test     # Run tests
make lint     # Run linters
make run      # Run locally
\`\`\`
```

### 6. Architecture Decisions

Key patterns and conventions specific to this repo.

```markdown
## Architecture

### Patterns Used
- Event sourcing for state management
- CQRS for read/write separation
- Hexagonal architecture

### Conventions
- All commands go through the command bus
- Events are immutable value objects
- Projections rebuild from events
```

## What Makes a Good CLAUDE.md

### Do Include

- **Enough context to skip exploration** - Claude shouldn't need to grep around
- **Key architectural patterns** - How the code is organized and why
- **Non-obvious conventions** - Things that aren't standard
- **Important dependencies** - External services, APIs, databases
- **Common tasks** - How to do things Claude will be asked to do

### Don't Include

- **Duplicated manifesto content** - Link to it instead
- **Duplicated vision content** - Link to vision.md
- **API documentation** - That belongs elsewhere
- **User guides** - CLAUDE.md is for the AI, not end users
- **Obvious things** - Don't explain what `go build` does

## Template

```markdown
# [Project Name]

[One-line description]

## Organization Context

This repo is part of Flowmade. See:
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
- [Vision](./vision.md) - what this specific product does

## Setup

\`\`\`bash
# TODO: Add setup instructions
\`\`\`

## Project Structure

\`\`\`
project/
├── ...
\`\`\`

## Development

\`\`\`bash
make build    # Build the project
make test     # Run tests
make lint     # Run linters
\`\`\`

## Architecture

### Patterns
- [List key patterns]

### Conventions
- [List important conventions]

### Key Components
- [Describe main components and their responsibilities]
```

## Examples

### Good: Enough Context

```markdown
## Architecture

This service uses event sourcing. State is rebuilt from events, not stored directly.

### Key Types
- `Aggregate` - Domain object that emits events
- `Event` - Immutable fact that something happened
- `Projection` - Read model built from events

### Adding a New Aggregate
1. Create type in `pkg/domain/`
2. Implement `HandleCommand()` and `ApplyEvent()`
3. Register in `cmd/main.go`
```

Claude can now work with aggregates without exploring the codebase.

### Bad: Too Vague

```markdown
## Architecture

Uses standard Go patterns. See the code for details.
```

Claude has to explore to understand anything.

## Maintenance

Update CLAUDE.md when:
- Adding new architectural patterns
- Changing project structure
- Adding important dependencies
- Discovering conventions that aren't documented

Don't update for:
- Every code change
- Bug fixes
- Minor refactors