Back to Details

yuque-group-tech-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tech Design — Technical Design Document Generator (Team)

Tech Design — 技术设计文档生成器（团队版）

Help the user write a structured technical design document following a standard template, then save it to the team's Yuque knowledge base for group review.
帮助用户按照标准模板编写结构化的技术设计文档，随后保存到团队的Yuque知识库供团队评审。

When to Use

适用场景

  • User wants to write a technical design document or RFC and save it to the group repo
  • User says "帮我写技术方案到团队库", "write a tech design for the team", "团队技术方案"
  • User describes a feature/system and needs it formalized into a design doc for group review
  • 用户需要编写技术设计文档或RFC并保存到团队仓库
  • 用户提及「帮我写技术方案到团队库」、「为团队编写技术设计文档」、「团队技术方案」
  • 用户描述某个功能/系统，需要将其正式化为设计文档供团队评审

Required MCP Tools

所需MCP工具

All tools are from the 
yuque-mcp
server:
  • yuque_search
    — (Optional) Search for related existing docs for context
  • yuque_list_repos
    — Find the target group knowledge base
  • yuque_create_doc
    — Create the design document
所有工具均来自
yuque-mcp
服务端：
  • yuque_search
    — （可选）搜索相关现有文档获取上下文
  • yuque_list_repos
    — 查找目标团队知识库
  • yuque_create_doc
    — 创建设计文档

Reference

参考资料

The full template is in references/template.md. Load it when generating the document.
完整模板位于references/template.md，生成文档时请加载该模板。

Workflow

工作流

Step 1: Understand the Requirements

步骤1：理解需求

Gather from the user:
FieldRequiredDescription
项目/功能名称YesWhat is being designed
背景与问题YesWhy this is needed, what problem it solves
目标YesWhat success looks like
约束条件NoTechnical constraints, timeline, budget
已有方案NoAny existing approaches or prior art
团队标识 (Group login)YesThe team's Yuque group login
If the user provides a brief description, ask clarifying questions:
  • "这个功能要解决什么问题？"
  • "有什么技术约束吗？比如必须用某个框架、要兼容现有系统？"
  • "预期的时间节点是什么？"
If the user hasn't specified a group login, ask: "请告诉我团队的语雀团队标识（group login），我来把技术方案存到团队知识库。"
从用户处收集以下信息：
字段必填说明
项目/功能名称是设计的对象是什么
背景与问题是为什么需要做这个设计，它解决什么问题
目标是成功的标准是什么
约束条件否技术约束、时间线、预算等
已有方案否任何现有方案或先前的同类设计
团队标识 (Group login)是团队的Yuque团队标识
如果用户仅提供了简短描述，询问澄清问题：
  • "这个功能要解决什么问题？"
  • "有什么技术约束吗？比如必须用某个框架、要兼容现有系统？"
  • "预期的时间节点是什么？"
如果用户未指定团队标识，询问："请告诉我团队的语雀团队标识（group login），我来把技术方案存到团队知识库。"

Step 2: (Optional) Search for Context

步骤2：（可选）搜索上下文

If relevant, search Yuque for related existing documents:
Tool: yuque_search
Parameters:
  query: "<related keywords>"
  type: "doc"
This helps:
  • Avoid duplicating existing designs
  • Reference prior decisions
  • Understand the current architecture
如果有相关内容，在Yuque中搜索相关现有文档：
Tool: yuque_search
Parameters:
  query: "<相关关键词>"
  type: "doc"
这有助于：
  • 避免重复设计现有方案
  • 参考过往决策
  • 理解当前架构

Step 3: Generate the Design Document

步骤3：生成设计文档

Load the template from 
references/template.md
and fill in each section based on the user's input and your technical analysis.
Key sections to fill:
  1. 背景 (Background) — Problem statement, current situation
  2. 目标 (Goals) — What this design achieves, non-goals
  3. 方案设计 (Design) — The core technical approach
    • Architecture diagram description (describe in text/ASCII if needed)
    • Core components and their responsibilities
    • Data model / API design
    • Key flows (sequence of operations)
  4. 技术选型 (Tech Stack) — Why specific technologies were chosen
  5. 方案对比 (Alternatives) — Other approaches considered and why they were rejected
  6. 排期 (Timeline) — Milestones and estimated effort
  7. 风险评估 (Risks) — What could go wrong and mitigation strategies
  8. 参考资料 (References) — Related docs, links, prior art
从
references/template.md
加载模板，根据用户输入和你的技术分析填充每个章节。
需要填充的核心章节：
  1. 背景 (Background) — 问题描述、当前现状
  2. 目标 (Goals) — 本设计要实现的内容，非目标
  3. 方案设计 (Design) — 核心技术思路
    • 架构图描述（如有需要可用文本/ASCII图描述）
    • 核心组件及其职责
    • 数据模型 / API设计
    • 核心流程（操作顺序）
  4. 技术选型 (Tech Stack) — 选择特定技术的原因
  5. 方案对比 (Alternatives) — 考虑过的其他方案以及被否决的原因
  6. 排期 (Timeline) — 里程碑和预估工作量
  7. 风险评估 (Risks) — 可能出现的问题及缓解策略
  8. 参考资料 (References) — 相关文档、链接、先前的同类设计

Step 4: Review with User

步骤4：与用户评审

Present the draft to the user before saving. Ask:
  • "方案内容是否准确？有需要调整的地方吗？"
  • "要补充其他技术细节吗？"
保存前将草稿展示给用户，询问：
  • "方案内容是否准确？有需要调整的地方吗？"
  • "要补充其他技术细节吗？"

Step 5: Save to Team Yuque

步骤5：保存到团队Yuque

Tool: yuque_list_repos
Parameters:
  login: "<group_login>"
  type: "group"
Find or ask for the target group repo (often "技术方案" or "设计文档" or "RFC").
Tool: yuque_create_doc
Parameters:
  repo_id: "<namespace>"    # e.g., "my-team/tech-docs"
  title: "[技术方案] <项目名称>"
  body: "<formatted design document>"
  format: "markdown"
Tool: yuque_list_repos
Parameters:
  login: "<group_login>"
  type: "group"
找到或询问用户目标团队仓库（通常是「技术方案」、「设计文档」或「RFC」）。
Tool: yuque_create_doc
Parameters:
  repo_id: "<namespace>"    # 例如："my-team/tech-docs"
  title: "[技术方案] <项目名称>"
  body: "<格式化后的设计文档>"
  format: "markdown"

Step 6: Confirm

步骤6：确认结果

markdown
✅ 技术方案已创建（草稿状态）！

📄 **[[技术方案] 项目名称](文档链接)**
📚 已保存到：「团队知识库名称」
markdown
✅ 技术方案已创建（草稿状态）！

📄 **[[技术方案] 项目名称](文档链接)**
📚 已保存到：「团队知识库名称」

文档结构

文档结构

  • 背景与目标
  • 方案设计（含 X 个核心模块）
  • 技术选型对比
  • 排期（预计 X 周）
  • 风险评估（X 个风险点）
💡 文档为草稿状态，请团队评审后发布。
undefined
  • 背景与目标
  • 方案设计（含 X 个核心模块）
  • 技术选型对比
  • 排期（预计 X 周）
  • 风险评估（X 个风险点）
💡 文档为草稿状态，请团队评审后发布。
undefined

Guidelines

使用规范

  • Write the design doc in Chinese (default) unless the user specifies English
  • Be specific in the design section — include data models, API signatures, flow descriptions
  • For tech stack comparison, use a table with pros/cons
  • Keep the document actionable — someone should be able to implement from this doc
  • If the user's requirements are vague, make reasonable assumptions and note them clearly with "【假设】" markers
  • Don't over-engineer — match the design complexity to the project scope
  • Always end the confirmation with "请团队评审后发布" — group designs need review
  • This skill saves to group repos — for personal repos, use the 
    tech-design
    skill in the 
    yuque-personal
    plugin
  • 默认使用中文编写设计文档，除非用户指定用英文
  • 设计章节内容要具体——包含数据模型、API签名、流程描述
  • 技术选型对比使用带优缺点的表格呈现
  • 保证文档可落地——其他人可以根据该文档进行实现
  • 如果用户需求模糊，做出合理假设并使用「【假设】」标记明确标注
  • 不要过度设计——设计复杂度要匹配项目范围
  • 确认信息末尾始终附上「请团队评审后发布」——团队设计文档需要评审
  • 本技能存储到团队仓库——如果是个人仓库，请使用
    yuque-personal
    插件中的
    tech-design
    技能

Error Handling

错误处理

SituationAction
User provides very vague requirementsAsk 2-3 targeted questions before generating
yuque_search
finds conflicting existing designs		Mention them and ask user how to reconcile
yuque_create_doc
fails		Show error, offer to output the markdown for manual copy
User wants to update an existing design docUse 
yuque_search
to find it, then suggest creating a v2 or appendix
Group login not providedAsk user for the team's group login
Team Token not configuredInform user that group repos require a team-level Token
场景处理方式
用户提供的需求非常模糊生成前提出2-3个针对性问题询问
yuque_search
找到存在冲突的现有设计		告知用户并询问如何协调
yuque_create_doc
调用失败		展示错误信息，提供markdown格式内容供用户手动复制
用户想要更新现有设计文档使用
yuque_search
找到对应文档，建议创建v2版本或附录
未提供团队标识询问用户的团队group login
未配置团队Token告知用户团队仓库需要团队级Token