blueprints-writing

# Writing Technical Blueprints

## Purpose

Technical blueprints document **how systems work internally**. They differ from user documentation (how to use) and README files (project overview).

## When to Write Blueprints

Write blueprints for:

- Complex systems with multiple components
- Public APIs and their contracts
- Architecture decisions and their rationale
- Behavior that isn't obvious from code
- Integration points between systems

Skip blueprints for:

- Self-documenting code (simple utilities)
- Test files (tests ARE the documentation)
- External dependencies (link to their docs)

## Creating Blueprints

**IMPORTANT:** Always use the `write_blueprint` MCP tool to create or update blueprints. This automatically adds the required frontmatter.

```typescript
// Before writing, search for existing blueprints
const existing = await search_blueprints({ keyword: "auth" });

// Read existing blueprint if updating
const current = await read_blueprint({ name: "authentication" });

// Write or update the blueprint
await write_blueprint({
  name: "system-name",
  summary: "Brief one-line description",
  content: "# System Name\n\n## Overview\n..."
});
```

The MCP tool handles frontmatter automatically - you just provide the content.

## Blueprint File Structure

When writing blueprint content (passed to `write_blueprint`), use this structure:

```markdown
# System Name

One-line description of what this system does.

## Overview

2-3 paragraphs covering:
- Why this system exists (problem it solves)
- What it does at a high level
- Where it fits in the larger architecture

## Architecture

### Components

List major components:
- **ComponentA** - Purpose and responsibility
- **ComponentB** - Purpose and responsibility

### Data Flow

Describe how data moves through the system:
1. Input arrives via X
2. ComponentA processes and transforms
3. Result passed to ComponentB
4. Output returned/stored

### Dependencies

- **Dependency** - Why it's needed, what it provides