220 lines
4.8 KiB
Markdown
220 lines
4.8 KiB
Markdown
---
|
|
name: claude-md-writing
|
|
model: haiku
|
|
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.
|
|
user-invocable: false
|
|
---
|
|
|
|
# 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
|