技术方案写作助手

把一句需求整理成可评审的技术方案文档：锚点确认、方案对比与选型、接口与数据设计、风险灰度与回滚预案，附定稿前自查清单。

自由如风最新版本 0.1.0更新于 2026-11-07下载 0 次

SKILL.md

1	---
2	name: "design-doc-writer"
3	description: "把一句需求或口头想法整理成完整技术方案文档：背景与目标、方案对比与选型、接口与数据设计、风险与灰度回滚，附定稿前自查清单。"
4	---
5
6	# 技术方案写作助手
7
8	> 把一句需求、一段口头想法或一份粗糙提纲，整理成能拿去评审的技术方案文档。纯指令技能：不带脚本、不联网、不写任何文件，产出为方案文本本身。
9
10	## 触发时机
11
12	- 用户要求写技术方案、设计文档、RFC、评审材料或「把这个想法落成文档」；
13	- 用户给出需求一句话，希望拆解成实现路径供团队讨论；
14	- 已有方案草稿需要补齐缺失章节、强化论证或压缩篇幅。
15
16	## 工作流程（逐步推进，不跳步）
17
18	### 1 先问清三个锚点
19
20	动笔前逐项确认，用户没说就用假设值并显式标注：
21
22	- 目标：这个方案上线后，用什么指标判断成功；
23	- 边界：明确不做什么，防止评审时范围膨胀；
24	- 约束：时间、人力、兼容性、合规等硬限制。
25
26	### 2 背景与目标章节
27
28	- 用两三句话讲清楚为什么现在做、不做会怎样；
29	- 目标写成可验证的陈述，避免「提升体验」这类无法判定的措辞。
30
31	### 3 方案对比与选型
32
33	- 至少给出两个候选方案，各列核心思路、改动面、优缺点；
34	- 明确写出选了哪个、为什么，淘汰项也要写理由——这是评审时最常被追问的部分；
35	- 只有一个可行方案时，写清「为什么没有别的选择」。
36
37	### 4 详细设计
38
39	- 接口：列出关键接口的签名、入参出参与错误语义，不追求穷举；
40	- 数据：表结构或模型变更，标注存量数据如何迁移；
41	- 流程：关键时序用编号步骤描述，异步与失败分支必须写；
42	- 兼容性：对调用方、下游和历史的破坏性影响逐条列出。
43
44	### 5 风险、灰度与回滚
45
46	- 每个风险写「触发条件 + 影响 + 缓解措施」三段式；
47	- 灰度方案写清放量顺序与观察指标；
48	- 回滚写清回滚动作、数据是否可逆、预计耗时——数据不可逆的回滚要在风险里标红。
49
50	## 输出模板
51
52	```markdown
53	# <方案名称>
54
55	## 1 背景与目标
56	（为什么做 + 成功指标 + 明确不做什么）
57
58	## 2 约束
59	（时间 / 人力 / 兼容性 / 合规等硬限制）
60
61	## 3 方案对比
62	\| 维度 \| 方案 A \| 方案 B \|
63	\|---\|---\|---\|
64	（核心思路 / 改动面 / 优缺点）
65
66	选型结论：选 X，理由 ……；淘汰 Y，理由 ……
67
68	## 4 详细设计
69	### 4.1 接口
70	### 4.2 数据模型与迁移
71	### 4.3 关键流程（含失败分支）
72	### 4.4 兼容性影响
73
74	## 5 风险与灰度
75	（风险：触发条件 + 影响 + 缓解；灰度：放量顺序 + 观察指标）
76
77	## 6 回滚预案
78	（动作 / 数据可逆性 / 耗时）
79	```
80
81	## 定稿前自查清单
82
83	- [ ] 三个锚点（目标 / 边界 / 约束）全部落实，假设值已标注；
84	- [ ] 有方案对比，淘汰项有理由；
85	- [ ] 每个异步流程都写了失败分支；
86	- [ ] 数据迁移与回滚的可逆性有明确结论；
87	- [ ] 没有「视情况而定」「后续再定」这类悬空表述——要么写死，要么进开放问题清单。
88
89	## 红线
90
91	- 不虚构数据指标、性能数字或「业界普遍做法」来支撑选型；
92	- 不省略风险章节——评审最容易通过的方案往往是最危险的方案；
93	- 不在方案里夹带未与用户确认的组织决策（谁负责、排期承诺），此类内容放「待确认」清单；
94	- 用户只想要提纲时，不强行展开成全文，按用户要的粒度输出。

文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。