Back to Details

design-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design Documentation

设计文档

Create technical blueprints that bridge requirements and implementation. This skill teaches how to document architecture decisions, component design, and system interactions.
创建连接需求与开发实现的技术蓝图。本技能将指导你如何记录架构决策、组件设计和系统交互。

When to Use This Skill

何时使用该技能

Use design documentation when:
  • Requirements phase is complete and approved
  • You need to plan technical implementation
  • Multiple developers will work on the feature
  • Architecture decisions need documentation
  • The feature involves complex integrations
在以下场景使用设计文档：
  • 需求阶段已完成并获批
  • 需要规划技术实现方案
  • 多名开发者将参与该功能开发
  • 架构决策需要被记录留存
  • 功能涉及复杂的系统集成

Design Document Structure

设计文档结构

Standard Template

标准模板

markdown
undefined
markdown
undefined

Design Document: [Feature Name]

设计文档: [Feature Name]

Overview

Overview

[High-level summary of the feature and approach]
[High-level summary of the feature and approach]

Architecture

Architecture

[System architecture and component overview]
[System architecture and component overview]

Components and Interfaces

Components and Interfaces

[Detailed component descriptions and interactions]
[Detailed component descriptions and interactions]

Data Models

Data Models

[Data structures and relationships]
[Data structures and relationships]

Error Handling

Error Handling

[Error scenarios and response strategies]
[Error scenarios and response strategies]

Testing Strategy

Testing Strategy

[Testing approach and quality assurance]
undefined
[Testing approach and quality assurance]
undefined

Step-by-Step Process

分步流程

Step 1: Requirements Analysis

步骤1: 需求分析

Before designing, ensure you understand:
  • All functional requirements
  • Non-functional requirements (performance, security, scalability)
  • Constraints (technology stack, timeline, resources)
  • Integration points with existing systems
Analysis Questions:
  • What does the system need to do?
  • What are the performance expectations?
  • What existing code/systems does this touch?
  • What are the security requirements?
  • What could go wrong?
在开始设计前，确保你理解以下内容：
  • 所有功能需求
  • 非功能需求（性能、安全性、可扩展性）
  • 约束条件（技术栈、时间线、资源）
  • 与现有系统的集成点
分析问题清单：
  • 系统需要实现什么功能？
  • 性能预期是什么？
  • 会涉及哪些现有代码/系统？
  • 安全要求有哪些？
  • 可能出现哪些故障？

Step 2: Research and Context Building

步骤2: 研究与背景构建

Identify areas needing research:
  • Technology choices and alternatives
  • Third-party integrations and APIs
  • Best practices for similar systems
  • Security and compliance considerations
Research Documentation:
markdown
undefined
确定需要研究的领域：
  • 技术选型与替代方案
  • 第三方集成与API
  • 同类系统的最佳实践
  • 安全与合规考量
研究记录模板：
markdown
undefined

Research Findings

Research Findings

[Topic]

[Topic]

Sources: [Links/references] Key Insights:
  • [Finding 1]
  • [Finding 2] Impact on Design: [How this affects our approach]
undefined
Sources: [Links/references] Key Insights:
  • [Finding 1]
  • [Finding 2] Impact on Design: [How this affects our approach]
undefined

Step 3: Define System Architecture

步骤3: 定义系统架构

Document the high-level structure:
markdown
undefined
记录高层架构结构：
markdown
undefined

Architecture

Architecture

System Overview

System Overview

[How the overall system works]
[How the overall system works]

Component Architecture

Component Architecture

[Major components and their responsibilities]
[Major components and their responsibilities]

Data Flow

Data Flow

[How information moves through the system]
[How information moves through the system]

Technology Decisions

Technology Decisions

[Key technology choices and rationale]

**Architecture Diagram (Mermaid):**
```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[Feature Service]
    D --> E[Database]
    D --> F[Cache]
[Key technology choices and rationale]

**架构图 (Mermaid):**
```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[Feature Service]
    D --> E[Database]
    D --> F[Cache]

Step 4: Design Components and Interfaces

步骤4: 设计组件与接口

For each major component:
markdown
undefined
针对每个核心组件：
markdown
undefined

Components and Interfaces

Components and Interfaces

[Component Name]

[Component Name]

Purpose: [What this component does]
Responsibilities:
  • [Responsibility 1]
  • [Responsibility 2]
Interfaces:
  • Input: [What it receives]
  • Output: [What it produces]
  • Dependencies: [What it requires]
API Definition:
typescript
interface ComponentName {
  method(input: InputType): Promise<OutputType>;
}
undefined
Purpose: [What this component does]
Responsibilities:
  • [Responsibility 1]
  • [Responsibility 2]
Interfaces:
  • Input: [What it receives]
  • Output: [What it produces]
  • Dependencies: [What it requires]
API Definition:
typescript
interface ComponentName {
  method(input: InputType): Promise<OutputType>;
}
undefined

Step 5: Define Data Models

步骤5: 定义数据模型

Document all data structures:
markdown
undefined
记录所有数据结构：
markdown
undefined

Data Models

Data Models

[Entity Name]

[Entity Name]

Purpose: [What this entity represents]
Properties:
FieldTypeRequiredDescription
idstringYesUnique identifier
namestringYesDisplay name
createdAtDateYesCreation timestamp
Validation Rules:
  • [Rule 1]
  • [Rule 2]
Relationships:
  • [Relationship to other entities]
Example:
json
{
  "id": "abc123",
  "name": "Example",
  "createdAt": "2024-01-15T10:30:00Z"
}
undefined
Purpose: [What this entity represents]
Properties:
FieldTypeRequiredDescription
idstringYesUnique identifier
namestringYesDisplay name
createdAtDateYesCreation timestamp
Validation Rules:
  • [Rule 1]
  • [Rule 2]
Relationships:
  • [Relationship to other entities]
Example:
json
{
  "id": "abc123",
  "name": "Example",
  "createdAt": "2024-01-15T10:30:00Z"
}
undefined

Step 6: Plan Error Handling

步骤6: 规划错误处理

Document error scenarios:
markdown
undefined
记录错误场景：
markdown
undefined

Error Handling

Error Handling

Error Categories

Error Categories

  1. Validation Errors: Invalid user input
  2. Authentication Errors: Unauthorized access
  3. External Service Errors: Third-party failures
  4. System Errors: Internal failures
  1. Validation Errors: Invalid user input
  2. Authentication Errors: Unauthorized access
  3. External Service Errors: Third-party failures
  4. System Errors: Internal failures

Error Response Strategy

Error Response Strategy

Error TypeHTTP CodeUser MessageSystem Action
Validation400Specific field errorLog, return details
Auth401"Please log in"Redirect to login
Not Found404"Resource not found"Log, return error
Server500"Something went wrong"Log, alert, retry
Error TypeHTTP CodeUser MessageSystem Action
Validation400Specific field errorLog, return details
Auth401"Please log in"Redirect to login
Not Found404"Resource not found"Log, return error
Server500"Something went wrong"Log, alert, retry

Recovery Mechanisms

Recovery Mechanisms

  • [Retry strategies]
  • [Fallback behaviors]
  • [Circuit breaker patterns]
undefined
  • [Retry strategies]
  • [Fallback behaviors]
  • [Circuit breaker patterns]
undefined

Step 7: Define Testing Strategy

步骤7: 定义测试策略

markdown
undefined
markdown
undefined

Testing Strategy

Testing Strategy

Unit Testing

Unit Testing

  • Coverage Target: 80%+
  • Focus Areas: [Critical business logic]
  • Mocking Strategy: [What to mock]
  • Coverage Target: 80%+
  • Focus Areas: [Critical business logic]
  • Mocking Strategy: [What to mock]

Integration Testing

Integration Testing

  • Scope: [Component interactions to test]
  • Environment: [Test environment setup]
  • Data Strategy: [Test data approach]
  • Scope: [Component interactions to test]
  • Environment: [Test environment setup]
  • Data Strategy: [Test data approach]

End-to-End Testing

End-to-End Testing

  • Critical Paths: [User journeys to test]
  • Tools: [Testing tools]
  • Critical Paths: [User journeys to test]
  • Tools: [Testing tools]

Performance Testing

Performance Testing

  • Load Targets: [Expected load]
  • Benchmarks: [Performance requirements]
undefined
  • Load Targets: [Expected load]
  • Benchmarks: [Performance requirements]
undefined

Decision Documentation

决策记录

Document key decisions using this template:
markdown
undefined
使用以下模板记录关键决策：
markdown
undefined

Decision: [Brief Title]

Decision: [Brief Title]

Context: [Situation requiring a decision]
Options Considered:
Option 1: [Name]
  • Pros: [Benefits]
  • Cons: [Drawbacks]
  • Effort: [Low/Medium/High]
Option 2: [Name]
  • Pros: [Benefits]
  • Cons: [Drawbacks]
  • Effort: [Low/Medium/High]
Decision: [Chosen option]
Rationale: [Why this option was selected]
Implications: [What this means for implementation]
undefined
Context: [Situation requiring a decision]
Options Considered:
Option 1: [Name]
  • Pros: [Benefits]
  • Cons: [Drawbacks]
  • Effort: [Low/Medium/High]
Option 2: [Name]
  • Pros: [Benefits]
  • Cons: [Drawbacks]
  • Effort: [Low/Medium/High]
Decision: [Chosen option]
Rationale: [Why this option was selected]
Implications: [What this means for implementation]
undefined

Common Design Decisions

常见设计决策

API Design

API设计

markdown
undefined
markdown
undefined

Decision: API Architecture

Decision: API Architecture

Options:
  1. REST API - Standard HTTP methods, well-understood
  2. GraphQL - Flexible queries, single endpoint
  3. RPC-style - Direct operation mapping
Decision: REST API Rationale: Standard CRUD operations, team familiarity, good tooling support
undefined
Options:
  1. REST API - Standard HTTP methods, well-understood
  2. GraphQL - Flexible queries, single endpoint
  3. RPC-style - Direct operation mapping
Decision: REST API Rationale: Standard CRUD operations, team familiarity, good tooling support
undefined

Data Storage

数据存储

markdown
undefined
markdown
undefined

Decision: Database Choice

Decision: Database Choice

Options:
  1. PostgreSQL - ACID compliance, complex queries
  2. MongoDB - Schema flexibility, horizontal scaling
  3. Redis - High performance, limited queries
Decision: PostgreSQL with JSON columns Rationale: Data consistency needs + flexibility for user preferences
undefined
Options:
  1. PostgreSQL - ACID compliance, complex queries
  2. MongoDB - Schema flexibility, horizontal scaling
  3. Redis - High performance, limited queries
Decision: PostgreSQL with JSON columns Rationale: Data consistency needs + flexibility for user preferences
undefined

Authentication

身份验证

markdown
undefined
markdown
undefined

Decision: Authentication Strategy

Decision: Authentication Strategy

Options:
  1. Session-based - Server-controlled, simple
  2. JWT tokens - Stateless, scalable
  3. OAuth 2.0 - External provider, no password management
Decision: JWT with refresh token rotation Rationale: Scalability requirements, API-first architecture
undefined
Options:
  1. Session-based - Server-controlled, simple
  2. JWT tokens - Stateless, scalable
  3. OAuth 2.0 - External provider, no password management
Decision: JWT with refresh token rotation Rationale: Scalability requirements, API-first architecture
undefined

Quality Checklist

质量检查清单

Before finalizing design:
Completeness:
  • All requirements addressed in design
  • Major system components defined
  • Data models cover all entities
  • Error handling covers expected failures
  • Testing strategy addresses all layers
Clarity:
  • Design decisions clearly explained
  • Component responsibilities well-defined
  • Interfaces between components specified
  • Technical choices include rationale
Feasibility:
  • Design is technically achievable
  • Performance requirements can be met
  • Security requirements addressed
  • Implementation complexity reasonable
Traceability:
  • Design elements map to requirements
  • All requirements covered by design
  • Testing validates requirement fulfillment
在最终确定设计前，完成以下检查：
完整性：
  • 所有需求均在设计中得到体现
  • 已定义核心系统组件
  • 数据模型覆盖所有实体
  • 错误处理覆盖预期故障场景
  • 测试策略覆盖所有层级
清晰性：
  • 设计决策解释清晰
  • 组件职责定义明确
  • 组件间接口已明确指定
  • 技术选型包含决策依据
可行性：
  • 设计在技术上可实现
  • 可满足性能要求
  • 已解决安全要求
  • 实现复杂度合理
可追溯性：
  • 设计元素与需求一一对应
  • 所有需求均被设计覆盖
  • 测试可验证需求的实现

Common Pitfalls

常见陷阱

  1. Over-Engineering: Design for current requirements, not hypothetical futures
  2. Under-Specified Interfaces: Define clear component boundaries
  3. Ignoring Non-Functional Requirements: Address performance, security, scalability
  4. Technology-First Design: Let requirements drive technology choices
  5. Insufficient Error Handling: Plan for failures, not just happy paths
  1. 过度设计： 针对当前需求设计，而非假设性的未来需求
  2. 接口定义不足： 明确组件边界
  3. 忽略非功能需求： 关注性能、安全性、可扩展性
  4. 技术优先设计： 让需求驱动技术选型
  5. 错误处理不足： 不仅要规划正常流程，还要为故障做预案

Example: User Profile Design

示例：用户资料设计

markdown
undefined
markdown
undefined

Design Document: User Profile Management

Design Document: User Profile Management

Overview

Overview

Enable users to view and edit their profile information, including personal details, preferences, and profile picture.
Enable users to view and edit their profile information, including personal details, preferences, and profile picture.

Architecture

Architecture

Component Architecture

Component Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Client    │────▶│  Profile API │────▶│  Database   │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │ Image Store  │
                    └──────────────┘
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Client    │────▶│  Profile API │────▶│  Database   │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │ Image Store  │
                    └──────────────┘

Technology Stack

Technology Stack

  • API: Node.js with Express
  • Database: PostgreSQL
  • Image Storage: S3-compatible object storage
  • Cache: Redis for session data
  • API: Node.js with Express
  • Database: PostgreSQL
  • Image Storage: S3-compatible object storage
  • Cache: Redis for session data

Components

Components

ProfileService

ProfileService

Purpose: Manage user profile CRUD operations
Interface:
typescript
interface ProfileService {
  getProfile(userId: string): Promise<UserProfile>;
  updateProfile(userId: string, data: ProfileUpdate): Promise<UserProfile>;
  uploadAvatar(userId: string, image: File): Promise<string>;
  deleteAvatar(userId: string): Promise<void>;
}
Purpose: Manage user profile CRUD operations
Interface:
typescript
interface ProfileService {
  getProfile(userId: string): Promise<UserProfile>;
  updateProfile(userId: string, data: ProfileUpdate): Promise<UserProfile>;
  uploadAvatar(userId: string, image: File): Promise<string>;
  deleteAvatar(userId: string): Promise<void>;
}

Data Models

Data Models

UserProfile

UserProfile

FieldTypeRequiredValidation
idUUIDYesAuto-generated
emailstringYesValid email format
displayNamestringYes2-50 characters
biostringNoMax 500 characters
avatarUrlstringNoValid URL
preferencesJSONNoValid JSON object
updatedAttimestampYesAuto-updated
FieldTypeRequiredValidation
idUUIDYesAuto-generated
emailstringYesValid email format
displayNamestringYes2-50 characters
biostringNoMax 500 characters
avatarUrlstringNoValid URL
preferencesJSONNoValid JSON object
updatedAttimestampYesAuto-updated

Error Handling

Error Handling

ScenarioResponseAction
Profile not found404Return error message
Invalid update data400Return validation errors
Image too large413Return size limit error
Unauthorized401Redirect to login
ScenarioResponseAction
Profile not found404Return error message
Invalid update data400Return validation errors
Image too large413Return size limit error
Unauthorized401Redirect to login

Testing Strategy

Testing Strategy

  • Unit tests for validation logic
  • Integration tests for API endpoints
  • E2E test for profile edit flow
undefined
  • Unit tests for validation logic
  • Integration tests for API endpoints
  • E2E test for profile edit flow
undefined

Next Steps

后续步骤

After completing design:
  1. Get design review and approval
  2. Move to Task Planning phase
  3. Break design into implementation tasks
  4. Begin systematic implementation
完成设计后：
  1. 获取设计评审与批准
  2. 进入任务规划阶段
  3. 将设计拆解为开发任务
  4. 开始系统化开发实现