Back to Details

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:
  1. Analyze requirements to identify entities and their attributes
  2. Define primary keys, foreign keys, and constraints
  3. Specify data types, defaults, and nullable fields
  4. Design indexes for query optimization
  5. Document table relationships (one-to-one, one-to-many, many-to-many)
  6. 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
生成包含字段、类型、约束、索引及关系的完整数据库表定义。
流程：
  1. 分析需求，识别实体及其属性
  2. 定义主键、外键与约束
  3. 指定数据类型、默认值及可为空字段
  4. 设计用于查询优化的索引
  5. 记录表间关系（一对一、一对多、多对多）
  6. 参考
    templates/database-schema.md
    的标准格式
输出内容包括：
  • 带字段说明的表定义
  • 实体关系图（Mermaid ER图）
  • 附理由的索引建议
  • 迁移脚本或DDL语句

2. Module Layering Design

2. 模块分层设计

Design system architecture with clear separation of concerns across layers.
Process:
  1. Identify architectural layers (presentation, business, data, infrastructure)
  2. Define module boundaries and responsibilities
  3. Specify dependencies between layers
  4. Establish communication patterns
  5. Reference 
    references/design-patterns.md
    for architectural patterns
Output includes:
  • Layer architecture diagram
  • Module responsibility matrix
  • Dependency graph
  • Data flow between layers
设计关注点清晰分离的系统架构分层。
流程：
  1. 识别架构分层（表现层、业务层、数据层、基础设施层）
  2. 定义模块边界与职责
  3. 指定层间依赖关系
  4. 确立通信模式
  5. 参考
    references/design-patterns.md
    中的架构模式
输出内容包括：
  • 分层架构图
  • 模块职责矩阵
  • 依赖关系图
  • 层间数据流

3. Module Interface Design

3. 模块接口设计

Define contracts between modules with clear input/output specifications.
Process:
  1. Identify module boundaries from requirements
  2. Define function/method signatures
  3. Specify data structures for module communication
  4. Document error handling and return codes
  5. Reference 
    templates/module-design.md
    for interface format
Output includes:
  • Interface definitions
  • Data transfer objects (DTOs)
  • Error handling specifications
  • Module dependency list
定义模块间的契约，明确输入/输出规范。
流程：
  1. 从需求中识别模块边界
  2. 定义函数/方法签名
  3. 指定模块通信所用的数据结构
  4. 记录错误处理与返回码
  5. 参考
    templates/module-design.md
    的接口格式
输出内容包括：
  • 接口定义
  • 数据传输对象（DTO）
  • 错误处理规范
  • 模块依赖列表

4. API Interface Design

4. API接口设计

Design RESTful API endpoints following industry best practices.
Process:
  1. Identify resources from domain model
  2. Map CRUD operations to HTTP methods
  3. Define request/response schemas
  4. Specify status codes and error responses
  5. Document authentication and authorization
  6. 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端点。
流程：
  1. 从领域模型中识别资源
  2. 将CRUD操作映射到HTTP方法
  3. 定义请求/响应 schema
  4. 指定状态码与错误响应
  5. 记录认证与授权方式
  6. 参考
    templates/api-spec.md
    的API文档格式
输出内容包括：
  • 含方法与路径的端点列表
  • 请求/响应示例（JSON格式）
  • 认证要求
  • 限流与分页规范
  • OpenAPI/Swagger规范

5. Business Flowchart

5. 业务流程图

Create visual business process diagrams using Mermaid syntax.
Process:
  1. Identify key business processes from requirements
  2. Map decision points and branching logic
  3. Define start/end states and conditions
  4. Specify actors and swimlanes if needed
  5. Reference 
    references/mermaid-diagrams.md
    for flowchart syntax
Output includes:
  • Mermaid flowchart code
  • Process descriptions per step
  • Decision logic documentation
  • Alternative flow paths
使用Mermaid语法创建可视化的业务流程图表。
流程：
  1. 从需求中识别关键业务流程
  2. 绘制决策点与分支逻辑
  3. 定义开始/结束状态与条件
  4. 必要时指定参与者与泳道
  5. 参考
    references/mermaid-diagrams.md
    的流程图语法
输出内容包括：
  • Mermaid流程图代码
  • 各步骤的流程说明
  • 决策逻辑文档
  • 备选流程路径

6. Data Flow Diagram

6. 数据流图

Visualize how data moves through the system from input to persistence.
Process:
  1. Trace data from external input through system layers
  2. Identify data transformations at each stage
  3. Specify data stores and external systems
  4. Document data formats at each boundary
  5. 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
可视化数据从输入到持久化的系统流转过程。
流程：
  1. 追踪数据从外部输入到系统各层的流转
  2. 识别各阶段的数据转换
  3. 指定数据存储与外部系统
  4. 记录各边界的数据格式
  5. 参考
    references/mermaid-diagrams.md
    的DFD语法
输出内容包括：
  • 0级DFD（上下文图）
  • 1级DFD（分解后的流程）
  • 定义所有数据元素的数据字典
  • 数据转换规则

7. Sequence Diagram

7. 时序图

Generate sequence diagrams showing component interactions over time.
Process:
  1. Identify actors and components
  2. Map message flow for key operations
  3. Specify synchronous vs asynchronous calls
  4. Document error scenarios and timeouts
  5. 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
生成展示组件随时间交互的时序图。
流程：
  1. 识别参与者与组件
  2. 绘制关键操作的消息流转
  3. 指定同步/异步调用
  4. 记录错误场景与超时处理
  5. 参考
    references/mermaid-diagrams.md
    的时序图语法
输出内容包括：
  • Mermaid时序图代码
  • 带参数的消息说明
  • 生命线文档
  • 备选流程与错误处理

Workflow Integration

工作流集成

New Project Design

新项目设计

  1. Requirements Analysis → Extract entities, processes, and use cases
  2. Database Design → Generate schema with ER diagram
  3. Architecture Design → Create module layering and interfaces
  4. API Design → Define RESTful endpoints
  5. Documentation → Generate all diagrams and compile design document
  1. 需求分析 → 提取实体、流程与用例
  2. 数据库设计 → 生成带ER图的schema
  3. 架构设计 → 创建模块分层与接口
  4. API设计 → 定义RESTful端点
  5. 文档编制 → 生成所有图表并整合为设计文档

Existing Project Documentation

现有项目文档补全

  1. Code Analysis → Parse existing code structure
  2. Reverse Engineering → Extract schemas and API patterns
  3. Documentation Generation → Create comprehensive design docs
  4. Gap Analysis → Identify missing or inconsistent elements
  1. 代码分析 → 解析现有代码结构
  2. 逆向工程 → 提取schema与API模式
  3. 文档生成 → 创建全面的设计文档
  4. 差距分析 → 识别缺失或不一致的内容

Incremental Updates

增量更新

  1. Change Request → Identify affected components
  2. Impact Analysis → Update relevant diagrams and schemas
  3. Version Documentation → Track changes and maintain history
  1. 变更请求 → 识别受影响的组件
  2. 影响分析 → 更新相关图表与schema
  3. 版本文档 → 追踪变更并维护历史记录

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

最佳实践

  1. Start with requirements: Ensure design aligns with business needs before documenting
  2. Iterative refinement: Update docs as design evolves; treat as living documents
  3. Diagram consistency: Use consistent naming and styling across all diagrams
  4. Version control: Track design changes alongside code changes
  5. Stakeholder review: Validate technical design with both technical and business stakeholders
  6. Mermaid validation: Verify Mermaid syntax renders correctly in supported viewers
  1. 从需求出发：在编制文档前，确保设计与业务需求对齐
  2. 迭代优化：随设计演进更新文档，将其视为活文档
  3. 图表一致性：所有图表使用统一的命名与样式
  4. 版本控制：将设计文档的变更与代码变更一同追踪
  5. 干系人评审：请技术与业务干系人共同验证技术设计
  6. 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生成默认采用关系型数据库模式
  • 复杂时序图可能难以阅读，建议拆分
  • 生成的文档需结合业务特定语境进行人工评审