Back to Details

tech-design-doc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Design Document Skill

技术设计文档Skill

When to Use

适用场景

  • Designing a new feature or system
  • Documenting architecture decisions (ADR/RFC)
  • Planning refactoring or optimization work
  • 设计新功能或系统
  • 记录架构决策（ADR/RFC）
  • 规划重构或优化工作

Execution Flow

执行流程

1. Assess Complexity

1. 评估复杂度

LevelScopeSections Required
SmallSingle component, <100 LOCTL;DR, Design, Implementation
MediumCross-component, API changes+ Background, Solution Analysis
LargeSystem-level, new serviceFull template
级别范围所需章节
小型单一组件，代码量<100行TL;DR、设计、实现
中型跨组件、涉及API变更+ 背景、方案分析
大型系统级、新增服务完整模板

2. Gather Context

2. 收集上下文信息

Before writing, explore the codebase:
  • Identify affected components (grep/glob for related code)
  • Read existing implementations and patterns
  • Note dependencies and potential side effects
  • Check for similar solutions already in codebase
在撰写前，先梳理代码库：
  • 确定受影响的组件（使用grep/glob查找相关代码）
  • 阅读现有实现和模式
  • 记录依赖关系和潜在副作用
  • 检查代码库中是否已有类似解决方案

3. Write Document

3. 撰写文档

Follow the template structure below, scaled to complexity level.
按照以下模板结构撰写，根据复杂度级别调整内容范围。

4. Verify Before Handoff

4. 交付前验证

  • Problem clearly defined (what breaks if we do nothing?)
  • Options compared with trade-offs (not just one solution)
  • Decision rationale documented
  • Diagrams illustrate key flows
  • Implementation steps are concrete and actionable
  • Risks identified with mitigations
  • 问题定义清晰（如果不处理会有什么问题？）
  • 对比了多种方案并说明取舍（不只是单一方案）
  • 记录了决策依据
  • 图表清晰展示关键流程
  • 实现步骤具体且可执行
  • 识别了风险并给出缓解措施

Document Template

文档模板

markdown
undefined
markdown
undefined

[Feature/System Name] Technical Design

[功能/系统名称] 技术设计

TL;DR

TL;DR

  • 3-5 bullets: problem, solution, key decisions, expected outcome
  • 3-5条要点：问题、解决方案、关键决策、预期成果

Background (Medium/Large)

背景（中型/大型项目适用）

Current State

当前状态

  • Existing behavior and limitations
  • 现有行为和局限性

Problem Statement

问题陈述

  • What breaks if we do nothing?
  • Who is affected and how?
  • 如果不处理会产生什么问题？
  • 受影响的对象及影响方式？

Goals / Non-Goals

目标/非目标

  • Goals: what this design achieves
  • Non-Goals: explicitly out of scope
  • 目标：本设计要达成的内容
  • 非目标：明确排除在范围外的内容

Solution Analysis (Medium/Large)

方案分析（中型/大型项目适用）

Option 1: [Name]

方案1：[名称]

Pros: ... Cons: ...
优点：... 缺点：...

Option 2: [Name]

方案2：[名称]

Pros: ... Cons: ...
优点：... 缺点：...

Comparison

对比

CriteriaOption 1Option 2
Performance......
Complexity......
评估维度方案1方案2
性能......
复杂度......

Recommendation

推荐方案

Selected: Option X Rationale: [why]
选定：方案X 依据：[原因]

Detailed Design

详细设计

Architecture

架构

[Mermaid diagram - see examples below]
[Mermaid图表 - 见下方示例]

Component Design

组件设计

  • Responsibilities
  • Interfaces
  • Dependencies
  • 职责
  • 接口
  • 依赖关系

Data Model (if applicable)

数据模型（如适用）

[Schema or structure]
[Schema或结构]

API Design (if applicable)

API设计（如适用）

[Endpoints, request/response]
[接口、请求/响应格式]

Implementation Plan

实施计划

Phase 1: [Name]

阶段1：[名称]

  • Task 1
  • Task 2
  • 任务1
  • 任务2

Migration Strategy (if applicable)

迁移策略（如适用）

Risk Assessment

风险评估

RiskProbabilityImpactMitigation
...High/Med/LowHigh/Med/Low...
风险概率影响缓解措施
...高/中/低高/中/低...

References

参考资料

  • Related docs, external resources
undefined
  • 相关文档、外部资源
undefined

Mermaid Diagram Examples

Mermaid图表示例

Architecture (flowchart):
mermaid
flowchart TD
    A[Client] --> B[API Gateway]
    B --> C[Service]
    C --> D[(Database)]
Sequence:
mermaid
sequenceDiagram
    Client->>Server: Request
    Server->>DB: Query
    DB-->>Server: Result
    Server-->>Client: Response
State:
mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> Processing: start
    Processing --> Done: complete
    Processing --> Failed: error
架构（流程图）：
mermaid
flowchart TD
    A[Client] --> B[API Gateway]
    B --> C[Service]
    C --> D[(Database)]
时序图：
mermaid
sequenceDiagram
    Client->>Server: Request
    Server->>DB: Query
    DB-->>Server: Result
    Server-->>Client: Response
状态图：
mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> Processing: start
    Processing --> Done: complete
    Processing --> Failed: error

Handling Feedback

反馈处理

When user requests changes:
  1. Understand which section needs revision
  2. Update only affected sections
  3. Ensure changes don't contradict other sections
  4. Re-verify the checklist items related to changes
当用户要求修改时：
  1. 明确需要修订的章节
  2. 仅更新受影响的章节
  3. 确保修改内容与其他章节不矛盾
  4. 重新验证与修改内容相关的检查项

Output Location

输出位置

  • Check if project has 
    docs/
    , 
    ai_docs/
    , or 
    design/
    directory
  • Ask user if location is unclear
  • Use descriptive filename: 
    design-[feature-name].md
  • 检查项目是否有
    docs/
    、
    ai_docs/
    或
    design/
    目录
  • 若位置不明确，询问用户
  • 使用描述性文件名：
    design-[feature-name].md