design-doc-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design Doc Generator - Technical Design Documentation Assistant

设计文档生成器 - 技术设计文档助手

Purpose

用途

Design Doc Generator creates comprehensive technical design documents for software projects. The skill generates production-ready documentation covering database schemas, system architecture, API specifications, and visual diagrams using Mermaid syntax.

设计文档生成器可为软件项目生成全面的技术设计文档。本Skill能够生成可用于生产环境的文档，涵盖数据库schema、系统架构、API规范，并使用Mermaid语法生成可视化图表。

When to Use This Skill

何时使用本Skill

Use this skill when:

Creating a new project and need complete technical design documentation
Designing database schemas with relationships and constraints
Defining RESTful API endpoints and request/response formats
Planning system architecture and module layering
Documenting business processes with flowcharts
Visualizing component interactions with sequence diagrams
Mapping data flow through system layers
Onboarding team members to existing codebase architecture

在以下场景中使用本Skill：

启动新项目，需要完整的技术设计文档时
设计带有关系和约束的数据库schema时
定义RESTful API端点及请求/响应格式时
规划系统架构与模块分层时
用流程图记录业务流程时
用时序图可视化组件交互时
绘制数据在系统各层间的流转图时
帮助团队成员快速了解现有代码库架构时

Core Capabilities

核心能力

1. Database Schema Design

1. 数据库Schema设计

Generate complete database table definitions with fields, types, constraints, indexes, and relationships.

Process:

Analyze requirements to identify entities and their attributes
Define primary keys, foreign keys, and constraints
Specify data types, defaults, and nullable fields
Design indexes for query optimization
Document table relationships (one-to-one, one-to-many, many-to-many)
Reference
```
templates/database-schema.md
```
for standard format

Output includes:

Table definitions with field specifications
Entity-Relationship diagram (Mermaid ER diagram)
Index recommendations with justification
Migration scripts or DDL statements

生成包含字段、类型、约束、索引及关系的完整数据库表定义。

流程：

分析需求，识别实体及其属性
定义主键、外键与约束
指定数据类型、默认值及可为空字段
设计用于查询优化的索引
记录表间关系（一对一、一对多、多对多）
参考
```
templates/database-schema.md
```
的标准格式

输出内容包括：

带字段说明的表定义
实体关系图（Mermaid ER图）
附理由的索引建议
迁移脚本或DDL语句

2. Module Layering Design

2. 模块分层设计

Design system architecture with clear separation of concerns across layers.

Process:

Identify architectural layers (presentation, business, data, infrastructure)
Define module boundaries and responsibilities
Specify dependencies between layers
Establish communication patterns
Reference
```
references/design-patterns.md
```
for architectural patterns

Output includes:

Layer architecture diagram
Module responsibility matrix
Dependency graph
Data flow between layers

设计关注点清晰分离的系统架构分层。

流程：

识别架构分层（表现层、业务层、数据层、基础设施层）
定义模块边界与职责
指定层间依赖关系
确立通信模式
参考
```
references/design-patterns.md
```
中的架构模式

输出内容包括：

分层架构图
模块职责矩阵
依赖关系图
层间数据流

3. Module Interface Design

3. 模块接口设计

Define contracts between modules with clear input/output specifications.

Process:

Identify module boundaries from requirements
Define function/method signatures
Specify data structures for module communication
Document error handling and return codes
Reference
```
templates/module-design.md
```
for interface format

Output includes:

Interface definitions
Data transfer objects (DTOs)
Error handling specifications
Module dependency list

定义模块间的契约，明确输入/输出规范。

流程：

从需求中识别模块边界
定义函数/方法签名
指定模块通信所用的数据结构
记录错误处理与返回码
参考
```
templates/module-design.md
```
的接口格式

输出内容包括：

接口定义
数据传输对象（DTO）
错误处理规范
模块依赖列表

4. API Interface Design

4. API接口设计

Design RESTful API endpoints following industry best practices.

Process:

Identify resources from domain model
Map CRUD operations to HTTP methods
Define request/response schemas
Specify status codes and error responses
Document authentication and authorization
Reference
```
templates/api-spec.md
```
for API documentation format

Output includes:

Endpoint list with methods and paths
Request/response examples (JSON)
Authentication requirements
Rate limiting and pagination specs
OpenAPI/Swagger specification

遵循行业最佳实践设计RESTful API端点。

流程：

从领域模型中识别资源
将CRUD操作映射到HTTP方法
定义请求/响应 schema
指定状态码与错误响应
记录认证与授权方式
参考
```
templates/api-spec.md
```
的API文档格式

输出内容包括：

含方法与路径的端点列表
请求/响应示例（JSON格式）
认证要求
限流与分页规范
OpenAPI/Swagger规范

5. Business Flowchart

5. 业务流程图

Create visual business process diagrams using Mermaid syntax.

Process:

Identify key business processes from requirements
Map decision points and branching logic
Define start/end states and conditions
Specify actors and swimlanes if needed
Reference
```
references/mermaid-diagrams.md
```
for flowchart syntax

Output includes:

Mermaid flowchart code
Process descriptions per step
Decision logic documentation
Alternative flow paths

使用Mermaid语法创建可视化的业务流程图表。

流程：

从需求中识别关键业务流程
绘制决策点与分支逻辑
定义开始/结束状态与条件
必要时指定参与者与泳道
参考
```
references/mermaid-diagrams.md
```
的流程图语法

输出内容包括：

Mermaid流程图代码
各步骤的流程说明
决策逻辑文档
备选流程路径

6. Data Flow Diagram

6. 数据流图

Visualize how data moves through the system from input to persistence.

Process:

Trace data from external input through system layers
Identify data transformations at each stage
Specify data stores and external systems
Document data formats at each boundary
Reference
```
references/mermaid-diagrams.md
```
for DFD syntax

Output includes:

Level 0 DFD (context diagram)
Level 1 DFD (decomposed processes)
Data dictionary defining all data elements
Data transformation rules

可视化数据从输入到持久化的系统流转过程。

流程：

追踪数据从外部输入到系统各层的流转
识别各阶段的数据转换
指定数据存储与外部系统
记录各边界的数据格式
参考
```
references/mermaid-diagrams.md
```
的DFD语法

输出内容包括：

0级DFD（上下文图）
1级DFD（分解后的流程）
定义所有数据元素的数据字典
数据转换规则

7. Sequence Diagram

7. 时序图

Generate sequence diagrams showing component interactions over time.

Process:

Identify actors and components
Map message flow for key operations
Specify synchronous vs asynchronous calls
Document error scenarios and timeouts
Reference
```
references/mermaid-diagrams.md
```
for sequence diagram syntax

Output includes:

Mermaid sequence diagram code
Message descriptions with parameters
Lifeline documentation
Alternative flows and error handling

生成展示组件随时间交互的时序图。

流程：

识别参与者与组件
绘制关键操作的消息流转
指定同步/异步调用
记录错误场景与超时处理
参考
```
references/mermaid-diagrams.md
```
的时序图语法

输出内容包括：

Mermaid时序图代码
带参数的消息说明
生命线文档
备选流程与错误处理

Workflow Integration

工作流集成

New Project Design

新项目设计

Requirements Analysis → Extract entities, processes, and use cases
Database Design → Generate schema with ER diagram
Architecture Design → Create module layering and interfaces
API Design → Define RESTful endpoints
Documentation → Generate all diagrams and compile design document

需求分析 → 提取实体、流程与用例
数据库设计 → 生成带ER图的schema
架构设计 → 创建模块分层与接口
API设计 → 定义RESTful端点
文档编制 → 生成所有图表并整合为设计文档

Existing Project Documentation

现有项目文档补全

Code Analysis → Parse existing code structure
Reverse Engineering → Extract schemas and API patterns
Documentation Generation → Create comprehensive design docs
Gap Analysis → Identify missing or inconsistent elements

代码分析 → 解析现有代码结构
逆向工程 → 提取schema与API模式
文档生成 → 创建全面的设计文档
差距分析 → 识别缺失或不一致的内容

Incremental Updates

增量更新

Change Request → Identify affected components
Impact Analysis → Update relevant diagrams and schemas
Version Documentation → Track changes and maintain history

变更请求 → 识别受影响的组件
影响分析 → 更新相关图表与schema
版本文档 → 追踪变更并维护历史记录

Design Document Structure

设计文档结构

Generate documents following this outline:

markdown

undefined

生成的文档遵循以下大纲：

markdown

undefined

[Project Name] Technical Design Document

[项目名称] 技术设计文档

1. Overview

1. 概述

Project background
System objectives
Scope and boundaries

项目背景
系统目标
范围与边界

2. System Architecture

2. 系统架构

Architecture diagram
Layer descriptions
Technology stack

架构图
分层说明
技术栈

3. Database Design

3. 数据库设计

ER diagram
Table definitions
Index strategy

ER图
表定义
索引策略

4. Module Design

4. 模块设计

Module breakdown
Interface specifications
Dependencies

模块拆分
接口规范
依赖关系

5. API Design

5. API设计

Endpoint specifications
Request/response formats
Authentication

端点规范
请求/响应格式
认证方式

6. Business Processes

6. 业务流程

Flowcharts
Process descriptions

流程图
流程说明

7. Data Flow

7. 数据流

Data flow diagrams
Data dictionary

数据流图
数据字典

8. Sequence Diagrams

8. 时序图

Key operations
Component interactions

undefined

关键操作
组件交互

undefined

Additional Resources

额外资源

Template Files

模板文件

Ready-to-use templates for consistent documentation:

templates/database-schema.md
- Database schema template with ER diagram
templates/api-spec.md
- API specification template following OpenAPI standards
templates/module-design.md
- Module interface design template

用于保持文档一致性的现成模板：

templates/database-schema.md
- 带ER图的数据库schema模板
templates/api-spec.md
- 遵循OpenAPI标准的API规范模板
templates/module-design.md
- 模块接口设计模板

Reference Files

参考文件

Detailed guides and best practices:

references/design-patterns.md
- Architectural patterns (Layered, Hexagonal, Clean Architecture)
references/mermaid-diagrams.md
- Mermaid syntax guide for all diagram types

详细指南与最佳实践：

references/design-patterns.md
- 架构模式（分层架构、六边形架构、整洁架构）
references/mermaid-diagrams.md
- 全类型图表的Mermaid语法指南

Example Files

示例文件

Complete working examples:

examples/ecommerce-design-doc.md
- Full design document for e-commerce system

完整的实用示例：

examples/ecommerce-design-doc.md
- 电商系统的完整设计文档

Best Practices

最佳实践

Start with requirements: Ensure design aligns with business needs before documenting
Iterative refinement: Update docs as design evolves; treat as living documents
Diagram consistency: Use consistent naming and styling across all diagrams
Version control: Track design changes alongside code changes
Stakeholder review: Validate technical design with both technical and business stakeholders
Mermaid validation: Verify Mermaid syntax renders correctly in supported viewers

从需求出发：在编制文档前，确保设计与业务需求对齐
迭代优化：随设计演进更新文档，将其视为活文档
图表一致性：所有图表使用统一的命名与样式
版本控制：将设计文档的变更与代码变更一同追踪
干系人评审：请技术与业务干系人共同验证技术设计
Mermaid验证：在支持的查看器中验证Mermaid语法能否正确渲染

Common Use Cases

常见使用场景

Scenario 1: New Microservice

Generate database schema for service-specific data
Design REST API for service communication
Create sequence diagrams showing service interactions

Scenario 2: Legacy System Migration

Document existing system architecture
Design target architecture with module boundaries
Map data flows between old and new systems

Scenario 3: Feature Addition

Identify affected modules and tables
Update API with new endpoints
Document new business processes

Scenario 4: Team Onboarding

Generate comprehensive design documentation
Create visual diagrams for quick understanding
Document module interfaces for integration guidance

场景1：新微服务开发

生成服务专属数据的数据库schema
设计用于服务通信的REST API
创建展示服务交互的时序图

场景2：遗留系统迁移

记录现有系统架构
设计带模块边界的目标架构
绘制新旧系统间的数据流

场景3：功能新增

识别受影响的模块与表
更新API以添加新端点
记录新增的业务流程

场景4：团队成员入职

生成全面的设计文档
创建可视化图表以帮助快速理解
记录模块接口以提供集成指导

Diagram Syntax Quick Reference

图表语法快速参考

ER Diagram:

mermaid

erDiagram
    USERS ||--o{ ORDERS : places
    USERS {
        int id PK
        string name
        string email
    }

Flowchart:

mermaid

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

Sequence Diagram:

mermaid

sequenceDiagram
    actor User
    participant API
    participant DB
    User->>API: Request
    API->>DB: Query
    DB-->>API: Result
    API-->>User: Response

ER图：

mermaid

erDiagram
    USERS ||--o{ ORDERS : places
    USERS {
        int id PK
        string name
        string email
    }

流程图：

mermaid

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

时序图：

mermaid

sequenceDiagram
    actor User
    participant API
    participant DB
    User->>API: Request
    API->>DB: Query
    DB-->>API: Result
    API-->>User: Response

Technical Requirements

技术要求

Mermaid support: Documentation viewer must support Mermaid rendering
Markdown output: All documentation in Markdown format
UTF-8 encoding: Ensure proper handling of special characters
Version control: Design documents should be tracked in Git

Mermaid支持：文档查看器需支持Mermaid渲染
Markdown输出：所有文档采用Markdown格式
UTF-8编码：确保正确处理特殊字符
版本控制：设计文档应在Git中追踪

Limitations

局限性

Mermaid diagrams may not render in all markdown viewers
Database schema generation assumes relational database patterns
Complex sequence diagrams may become difficult to read; consider splitting
Generated documentation requires human review for business-specific context

Mermaid图表可能无法在部分Markdown查看器中渲染
数据库schema生成默认采用关系型数据库模式
复杂时序图可能难以阅读，建议拆分
生成的文档需结合业务特定语境进行人工评审