architecture/old/skills/claude-md-writing/SKILL.md

name, model, description, user-invocable

name	model	description	user-invocable
claude-md-writing	haiku	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.	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.

# Project Name

Brief description of what this project does.

2. Organization Context

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

## 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.

## 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.

## 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.

## 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.

## 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

# [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

## 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

## 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