tech-design-doc

Imported from wyf027/leetcode-solu (agent-config/codex/skills/tech-design-doc/SKILL.md). Install upstream with npx skills add wyf027/leetcode-solu --skill tech-design-doc. Copyright stays with the author (MIT).

技术方案文档生成（Skill）

当用户需要把一个需求 / PRD / 改造点整理成技术方案文档或技术设计文档时，使用本 Skill 按团队《技术文档模版》的固定结构产出，保证团队内文档标题、章节命名、背景要素一致，便于评审与归档。

何时应用

• 用户说「帮我写技术方案 / 技术设计文档」「按模版出一份方案」「把这个需求整理成技术方案」时
• 用户贴出 PRD、需求描述、Figma、改造目标并要求输出技术实现方案时
• 需要为某个功能 / 升级 / 重构沉淀可评审、可归档的技术文档时

核心原则

• 结构固定：严格按下方章节顺序组织，不随意增删一级章节；二级及以下小节可按实际内容增减。
• 背景五要素固定：背景章节必须按 Issue / Context / Decision / Why / Who 五项填写，每项尽量控制在 20 字左右。信息不足时写 待补充。
• 不编造：背景、目标、技术选型来源于用户提供的需求 / PRD / 代码现状。信息不足的章节用 待补充：<需要用户提供什么> 显式标注，不要凭空臆造数据、接口、指标。
• 贴合现状：技术实现部分优先结合当前项目实际技术栈（如已有 TailwindCSS / Antd / Next.js 等）与代码现状，不引入与项目无关的方案。
• 可评审：风险评估、技术栈预警、补充说明面向团队评审，要写出真实可讨论的点，而非套话。

文档结构（严格按此模版）

生成时使用 assets/tech-design-template.md 作为骨架，逐节填充。一级章节如下：

# 【版本号-服务名】xxxx技术方案

# 背景

· Issue (问题)：发生了什么？（20字）
· Context (背景)：当时系统状态/限制条件是什么？（20字）
· Decision (判断)：团队决定怎么处理？（20字）
· Why (原因)：为什么这样选？(进度/风险/结构原因)（20字）
· Who (负责人)：谁为结果负责（20字）

# 目标

针对问题进行解构，列出所有目标项

# 技术实现

1. 简单描述功能实现
2. 如果需要，补充相关图进行说明

# 存储设计

涉及到的存储相关调整

# 接口设计

涉及到的接口相关调整

# 风险评估

涉及到的风险评估

# 同行评审

无需填写

# 技术栈预警

存在其他事情导致的技术妥协

# 补充说明

其他补充说明

各章节写法要点

1. 标题：使用 # 【版本号-服务名】xxxx技术方案，版本号与服务名未知时用 待补充，不要省略格式。
2. 背景：按五要素填写：Issue、Context、Decision、Why、Who。每项尽量 20 字左右，信息不足时写 待补充。
3. 目标：针对问题拆解目标项，使用列表或小节表达，避免泛泛而谈。
4. 技术实现：核心章节。先简单描述功能实现；必要时补充 Mermaid 图、时序图、流程图或关键代码片段。
5. 存储设计：说明表结构、字段、索引、迁移、兼容逻辑；不涉及存储时写 无存储调整。
6. 接口设计：说明新增/调整接口的 URL、方法、入参、出参、调用方；不涉及接口时写 无接口调整。
7. 风险评估：列出真实风险、影响和规避方式。
8. 同行评审：默认写 无需填写，除非用户明确要求补充评审项。
9. 技术栈预警：记录由于历史包袱、环境限制、进度原因造成的技术妥协；没有时写 暂无。
10. 补充说明：放置验证结果、发布说明、产品需求文档/Figma 链接、兼容范围、待办等其他信息。

输出方式

1. 默认输出为 Markdown，直接贴在对话中并按需写入项目 docs/tech-design/ 下（文件名形如 <feature>-technical-plan.md）。先与用户确认落盘路径，再写文件。
2. 若用户明确要 .docx，先产出 Markdown，再用 pandoc（如可用）转换：

   pandoc <plan>.md -o <plan>.docx

   无 pandoc 时提示用户，或保留 Markdown。
3. 信息不全时，先按模版搭好骨架并在缺失章节标注 待补充，再向用户追问关键缺口（背景五要素、目标指标、技术栈约束、兼容范围），补齐后完善。

注意

• 不要把模版当成必须塞满的表格。没有内容的小节宁可标「待补充 / 暂无」也不要编造。
• 一级标题必须使用 #，并保持用户给出的章节顺序。
• 贴合 quality-gate / code-format-generation 等工作区规范：示例代码片段也要符合项目既有风格。