writing-technical-design

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: writing-technical-design
description: Creates agent-optimized technical design documents backed by deep research of every technical component. Each component (library, framework, protocol, service) is investigated via web search / official docs and distilled into its own Agent Skill under skills/tech-{component}/, so future implementation sessions auto-load the relevant knowledge. Use when writing technical designs, architecture docs, defining system components, or making technology choices for spec-driven development.
---

# Writing Technical Design Documents

Create a technical design doc **plus** a set of per-component Agent Skills that capture the deep-research findings used to justify each technology choice. Implementation-time agents then auto-discover only the component skills relevant to the file they are editing.

**Use this skill when** designing how to build a feature, documenting architecture decisions, or making technology choices for spec-driven development.

**Supporting files:**
- [DEEP-RESEARCH.md](references/DEEP-RESEARCH.md) — research methodology, sources, per-category checklists.
- [COMPONENT-SKILLS.md](references/COMPONENT-SKILLS.md) — how to package each researched component as an Agent Skill.
- [CONTEXT-LAYERS.md](references/CONTEXT-LAYERS.md) — layer mapping details.
- [EXAMPLES.md](references/EXAMPLES.md) — complete design doc + component skill examples.

## Outputs

Running this skill produces **two kinds of artifacts**:

```
specs/design-{feature}.md            # The design doc (L3 core + L4 rationale)
skills/tech-{component-1}/SKILL.md   # Auto-discovered research digest per component
skills/tech-{component-2}/SKILL.md
skills/tech-{component-n}/SKILL.md
```

Each `tech-{component}` skill is a **first-class Agent Skill** — Claude loads it automatically when the implementation task touches that component. The design doc itself stays slim: it points to the component skills instead of inlining their contents.

## Context Layer Distribution

```
Layer   What goes here                       File location
============================================================================
L1      Tech stack summary + feature ref     CLAUDE.md / AGENTS.md (constitution)
        "Go 1.23, Echo v4, PostgreSQL 16, sqlc"
        "specs/design-notifications.md - Notification architecture"

L2      Component-local coding constraints   .claude/rules/ or .github/instructions/
        "Handlers in this dir use async sender interface"

L3      Design body (this doc)               specs/design-{feature}.md
        Decision summary, component overview, interfaces, data model
L3'     Component research digests           skills/tech-{component}/SKILL.md
        Auto-discovered via skill metadata when editing related code

L4      Deep reference                       specs/design-{feature}.md (lower sections)
        Alternatives considered, migration plan, ADR rationale
L4'     Component deep reference             skills/tech-{component}/references/*.md
        API surface, edge cases, benchmark notes
============================================================================
```

## Workflow

```
1. Read the approved feature spec (skills/prd-{feature}/SKILL.md)
2. Draft the Decision Summary: list candidate technologies per decision area
3. DEEP RESEARCH each candidate and each confirmed component
   → see "Deep Research Phase" below
4. Record findings as skills/tech-{component}/SKILL.md (one skill per component)
5. Write the design doc (specs/design-{feature}.md) referencing those skills
6. Extract L2 coding constraints to .claude/rules/
7. Set status: "draft" → review → "approved"
```

## Deep Research Phase

This is the part that distinguishes this skill from a plain "write an architecture doc" prompt. **Do not skip it.** A design that names technologies without verifying their current behavior has an expiry date measured in months.

### Step 1 — Enumerate components to research

From the draft Decision Summary, e