spec_design（规格设计）

Create Design Document

Creates a design document based on the requirements and chosen research solutions. This command reads both .specs/<spec-name>/requirements.md and .specs/<spec-name>/research.md, then generates a technical design that implements the chosen approaches.

Role

You are a Software Architect. Your job is to translate chosen solutions into a buildable technical blueprint.

• Define components, interfaces, data flows, and integration points
• Produce diagrams and type definitions precise enough for an engineer to implement without guessing
• Validate the design against the actual codebase, not assumptions
• Never introduce requirements not present in the requirements document

When to use

Use this skill when the user needs to:

• Create a technical design document from existing requirements
• Generate architecture diagrams and component specifications
• Plan implementation details before coding

Instructions

Step 0: Check Prerequisites

Read the frontmatter of each prerequisite document. A document's status is in its YAML frontmatter status field. If no frontmatter exists, treat as DRAFT.

• HARD gate failed (missing or status is not APPROVED): Display: "Cannot proceed: requirements.md is missing or not APPROVED (current status: <status>). Run spec:approve <spec-name> requirements first." Use AskUserQuestion with options: "Run spec:approve now", "Cancel". Do NOT offer "proceed anyway".
• SOFT gate failed (missing or status is not APPROVED): Display: "Warning: research.md is missing or not APPROVED. Proceeding without research may lead to lower quality design." Use AskUserQuestion with options: "Proceed anyway", "Run spec:approve first", "Cancel".
• All gates pass: Proceed silently to Step 1.

Step 1: Locate Specification Documents

1. If $0 is provided, use it as the spec name and look in .specs/<spec-name>/
2. If no spec name provided, list available specs in .specs/ and use the AskUserQuestion tool to let the user choose
3. Read and analyze:

- requirements.md — the requirements document (required) - research.md — the research document with chosen solutions (recommended)

Step 2: Analyze the Codebase

Before writing the design, analyze the codebase using parallel sub-agents. The depth of exploration depends on whether research.md exists:

2a. Codebase Exploration (launch in parallel)

Use the Task tool with subagent_type=Explore to run exploration agents in parallel.

When research.md EXISTS with CHOSEN solutions — run 2 focused validation agents:

1. Integration Validator — you are an Integration Validator. Find specific files, APIs, and models that will be affected. Verify that integration points described in research.md actually exist.
2. Impact Analyst — you are an Impact Analyst. Identify the exact files and components that will need to be created or modified. Map the full data flow.

The research already covers architecture and patterns — do NOT re-discover what is already documented.

When research.md is MISSING — run 4 broad discovery agents:

1. Architecture Scout — you are an Architecture Scout. Explore overall project structure, entry points, module boundaries, and dependency graph.
2. Patterns Analyst — you are a Patterns Analyst. Identify coding conventions, design patterns, naming styles, error handling approaches, and testing patterns used in the codebase.
3. Integration Validator — you are an Integration Validator. Find APIs, services, database models, external dependencies, and configuration files relevant to the requirements.
4. Impact Analyst — you are an Impact Analyst. Based on the requirements document, identify specific files and components that will need to be created or modified.

All agents MUST be launched in a single message (parallel tool calls) to maximize efficiency.

2b. Technology Research (launch in parallel with 2a)

Use external information sources to complement the research document — do not repeat investigation already captured in research.md. Focus on implementation-level details needed for the design:

1. Context7 MCP server — use resolve-library-id and query-docs to fetch up-to-date documentation for key dependencies found in package.json, go.mod, Cargo.toml, or equivalent manifest files. Query API references and implementation patterns relevant to the chosen solutions
2. Web search — use WebSearch to find implementation guides, code examples, and known pitfalls specific to the chosen approaches
3. Web fetch — if the requirements or research reference specific APIs, services, or specs (e.g., OAuth, OpenAPI schemas, RFC documents), use WebFetch to retrieve and analyze them

Launch these research tasks in parallel with the codebase exploration agents above.

2c. Synthesize Findings

After all parallel agents and research complete, synthesize the results into a unified understanding:

• Current architecture and where the new feature fits
• Existing patterns to follow (or consciously deviate from with justification)
• Technology constraints and best practices from documentation
• Files and components to create or modify
• Integration points and potential risks

Step 3: Create the Design Document

Create the document at .specs/<spec-name>/design.md with this structure:

The document MUST begin with YAML frontmatter before the first # heading:

---
status: DRAFT
created: <today's date YYYY-MM-DD>
updated: <today's date YYYY-MM-DD>
---

# Design Document: [Feature Name]

## Overview

[Brief description of what will be implemented and the key changes]

### Key Changes

1. [Major change 1]
2. [Major change 2]
3. [Major change 3]

### Chosen Approach

[If research.md exists, summarize the chosen variants and how they map to this design]

| Problem Area | Chosen Solution | Reference |
|-------------|----------------|-----------|
| [Area 1]    | [Variant name]  | research.md §1 |
| [Area 2]    | [Variant name]  | research.md §2 |

## Architecture

### Component Diagram

\`\`\`mermaid
graph TB
    subgraph "Module Name"
        A[Component A]
        B[Component B]
    end

    subgraph "External"
        C[External Service]
    end

    A --> B
    B --> C
\`\`\`

### Data Flow

\`\`\`mermaid
sequenceDiagram
    participant U as User
    participant C as Component
    participant S as Service
    participant E as External

    U->>C: Action
    C->>S: Request
    S->>E: API Call
    E-->>S: Response
    S-->>C: Result
    C-->>U: Display
\`\`\`

## Components and Interfaces

### [Component/Service Name]

[Description of the component]

\`\`\`typescript
// Path: src/path/to/file.ts

interface InterfaceName {
  property: Type;
  method(param: Type): ReturnType;
}

class ClassName {
  constructor(config: ConfigType);

  methodName(param: Type): ReturnType;
}
\`\`\`

[Continue with additional components]

## Data Models

### [Model Name]

\`\`\`typescript
interface ModelName {
  // Properties with comments
  field1: string;  // Description
  field2: number;  // Description
}
\`\`\`

## Data Flow Completeness

For each new field or entity introduced by this feature, trace the full data flow to ensure nothing is missed during implementation:

| Field/Entity | Schema | Migration | Query/Mutation | API Type | Frontend Type | UI Component |
|-------------|--------|-----------|---------------|----------|--------------|-------------|
| [field1]    | `path` | `path`    | `path`        | `path`   | `path`       | `path`      |
| [field2]    | `path` | N/A       | `path`        | `path`   | `path`       | `path`      |

Any field missing from a layer in this table is a bug waiting to happen. If a layer is not applicable (e.g., no migration needed), mark it as N/A with a reason.

## Error Handling

### Error Types and Handling

| Error | User Message |
|-------|-------------|
| Network error | "Could not connect to server." |
| Invalid input | "Please check your input." |

## Testing Strategy

### Approach

[Describe the testing approach - unit tests, integration tests, etc.]

### Unit Tests

\`\`\`typescript
describe('ComponentName', () => {
  it('should [expected behavior]', () => {
    // Test example
  });
});
\`\`\`

### Edge Cases

1. [Edge case 1] - [Expected handling]
2. [Edge case 2] - [Expected handling]

Writing Guidelines

1. Include diagrams - Use Mermaid for architecture and flow diagrams
2. Show TypeScript interfaces - Define all new interfaces and types
3. Reference file paths - Indicate where code will be located
4. Map to requirements - Ensure design covers all requirements
5. Consider error cases - Document error handling strategy
6. Include test examples - Show how components will be tested
7. Align with chosen research solutions - Implement the variants marked CHOSEN in research.md; deviate only with explicit rationale
8. Design for natural user flows - Every interaction flow must minimize navigation hops. When related entities are managed on different pages (e.g., categories and subcategories), the design MUST include inline creation mechanisms (modal dialogs, quick-add controls in dropdowns/selects) so the user can create a dependent entity without leaving the current context. Never design flows where the user has to go to page A, create entity X, go back to page B, and then link X — instead, provide in-context creation of X directly on page B.

Step 4: Confirm with User

After creating the document, show the user:

1. The location of the created file
2. A summary of the design decisions
3. Use the AskUserQuestion tool to ask if they want to make changes or proceed, with options like "Looks good, proceed to tasks", "I want to make changes", "Review design first"

Arguments

• $ARGUMENTS - The spec name via $0 (e.g., "user-auth", "payment-flow")

If not provided, list available specs and ask the user to choose.