yzr95924 yzr-sys-design-doc
把"写系统设计文档"约束成结构一致、评审友好、可落地执行的产物：按改动规模路由 full / lite
两档模板——full 档产出设计文档 + 实施任务书（执行期活文档），lite 档产出单份设计说明。
章节结构、每节"写什么"与节内分工以 assets/ 模板文件为准；跨节原则的"为什么"以本文件
执行原则为 SSOT，模板不重复（唯一例外：assets/template-tasks.md 要脱离本 skill 给执行者
单读，纪律段故意自包含）。SKILL.md 承载执行原则、档位路由、工作流与质量自检。
输入 / 输出
- 输入：用户的自然语言需求（可能含系统现状、技术栈、约束、评审时间）；可选：代码仓路径 / 相关已有文档
- 输出：full 档产出两个本地 Markdown 文件——设计文档
<功能slug>-design.md（评审 artifact， 评审后保持稳定）+ 实施任务书<功能slug>-tasks.md（执行期活文档，进度 / 问题 / 设计变更在其中流转）； lite 档只产出<功能slug>-design.md。路径用户指定或当前工作目录；正文中文，技术术语保留英文
执行原则 / 边界
第一条是元原则，其余按文档生命周期排序：判档 → 需求层 → 方案层 → 落地层。
- 读者是评审者（元原则）：每节落笔前问"评审者读这节能做什么决定"——答不上来的节就是凑字数。 全部结构（现状先行 / 决策留痕 / "考虑过"留证）都服务于一件事：让评审者用最短的时间做出 "批 / 打回 / 补哪里"的判断。
- 体量匹配规模：小改动套 full 模板 = 评审者读十几个章节找一个字段变更；大改动用 lite = 漏影响面与回滚。按"档位路由"判，用户明示档位时听用户的。
- 现状先行：主场景是已有系统增改——文档必须先讲清"现在怎么做的"，再讲改动。 评审者最大的信息缺口是现状，不是方案；跳过现状直接写方案 = 评审会上从头口头补。
- 现状有出处：现状 / 既有行为的断言必须能指出依据——代码位置、配置项、线上数据、 用户口述（标"用户述"）。指不出依据的是猜想不是现状：进假设清单，不以事实口吻写出。 凭想象编现状 = 整份文档的地基是假的，后续设计全跟着错。
- 需求层先行（full 档）：背景与现状 / 目标与非目标 / 功能点拆解 / 功能规格与约束 / 场景拆解五节 是需求层，不依赖实现——写完这五节时应还没做任何技术选型，换一个实现方案这五节依然成立。 需求层章节里出现具体技术选型（"用 Redis 存…"）= 方案层内容越层，挪去详细设计。
- 全量拆解（full 档）：设计前先穷举——需求拆成功能点清单、问题拆成全量场景表（主流程 / 分支 / 异常）。 这两张表是完备性的对照基准：每个功能点 / 场景在方案里必须有落点，落点为空的行就是设计漏洞。 场景表同时是验收标准的来源。
- 可验证性：每条目标 / 规格 / 场景期望行为都要能回答"怎么算做到了"——写不出判定方法的条目 不合格（"提升体验"不可验证，"选券从 3 步到 0 步"可验证）。场景表既然是验收清单的来源， 每一行就必须能客观地判真 / 判假。
- 假设显式化：信息不足不对用户连环问——给合理假设、写成文档里的"假设"清单，评审时确认。 只有关键决策分叉（影响方案走向）才问用户。
- 量化且标口径：能用数字就不用形容词——"超卖率千分之三" > "经常超卖"，"P99 < 200ms" > "低延迟"。 形容词人人有自己的刻度，数字只有一个；估算允许粗糙，但不允许缺席。数字必须标口径 （实测 / 读码所得 / 估算 / 假设），估算写"估算"、假设进假设清单——编造的精确比承认的 未知更危险：评审者会拿未标注的估算当事实做容量与排期决定。模糊量词与开放结尾 （经常 / 大量 / 较高 / 基本 / 大概 / "等"）出现即改写：能改数字改数字，能枚举就枚举， 定不了的进假设清单。
- 口径一致：同一规则 / 数字 / 术语全文只有一个说法——规则在 §4 规格单点陈述，他处 引用不重抄；同一概念前后同名（别"冷静期"又叫"冻结期"）；跨节数字必须相同（§4 写 TTL 30 分钟，§7 就不能是 1 小时）。评审者抓到两处口径打架，会对全文真实性打折。
- 设计决策留痕：选型与取舍进"备选方案"节。方案被选中不是因为它显而易见，而是因为备选被 明确否决过——三个月后回看或新人接手时，这节是"当时为什么这么定"的唯一记录。 取舍散落在正文注脚里 = 没写。
- 工程回退与业务撤销分开：回滚节只写"上线后出线上问题怎么退"（开关 / 回滚版本 / 修复脚本）； "用户怎么撤销操作"是业务流程设计，属于方案设计节。lite 档最常漏的就是工程回退。
- 设计 SSOT、任务书活文档（full 档）：设计文档评审后保持稳定；任务书只做指针不复制设计， 执行反馈（进度 / 问题）只写任务书；设计要改先修订设计文档、再同步任务书—— 反向流动（绕过设计改实现）会让两份文档同时失效。
工作流 / 步骤
- 判档：按下"档位路由"表定 full / lite。
- 读模板：full →
assets/template-full.md；lite →assets/template-lite.md。 章节结构、每节"写什么 / 为什么"以模板文件为准。 - 补上下文：用户给了代码仓路径时，先读相关代码再写现状节；现状断言的依据与假设纪律 按执行原则「现状有出处 / 假设显式化」执行。
- 按模板写：章节顺序与命名不动；某节确实不适用时保留章节写"本期无 + 一句话原因"—— 评审者需要看到"考虑过"，静默删节让人分不清"没想过"还是"不需要"。
- 生成任务书（仅 full 档）：按
assets/template-tasks.md从功能点拆解与详细设计拆出任务， 产出<功能slug>-tasks.md初始版（状态全"未开始"）——它随后交给执行者（人或 agent）， 进度 / 问题 / 设计变更按任务书模板 §3 的循环纪律流转；lite 档跳过本步。 - 自检（交付前逐条对照）：
- 元信息块已填（状态默认"草稿"，日期填当天）
- 非目标非空（full 档）
- 功能点清单每条在详细设计有落点；场景表"设计落点"列无空行（full 档）
- 功能规格与约束节给出精确规则口径（数值 / 上限 / 默认策略 / 硬约束），不是泛泛一句"按需求实现"（full 档）
- 目标 / 规格 / 场景期望行为均可判定——每条写得出"怎么算做到了"（可验证性原则）
- 数字与现状断言带口径（实测 / 读码 / 估算 / 假设 / 用户口述）——无未标注来源的"精确"数字
- 无模糊量词与开放结尾（经常 / 大量 / 较高 / 基本 / 大概 / "等"），能枚举的都枚举了
- 同一规则 / 术语 / 数字跨节口径一致（规则以 §4 规格为单点，他处引用不重抄）（full 档）
- 除元信息"评审人：待定"外，全文无裸 TBD / 待补充——未决项集中在开放问题节（full 档）
- DFX 五个子项（性能 / 可靠性 / 安全 / 可服务性 / 可测试性）均显式回应，不适用项有依据（full 档）
- 备选方案至少 1 条且带否决理由（full 档）
- 回滚节写的是工程回退，不是业务流程撤销
- 开放问题节存在（写"无"也行，但要有这节表明想过）（full 档）
- 任务书（独立
<功能slug>-tasks.md）每任务带四根指针（功能点 / 设计落点 / 验收场景 / 依赖） 与状态字段，任务行不复制设计细节（full 档） - 影响面覆盖模板影响面节枚举的全部维度（full §7.4 / lite §3），无影响的维度写"无"+ 依据
- 有状态流转的对象画了状态机（不只文字描述）
档位路由
| 信号 | 档 |
|---|---|
| 新系统 / 跨服务 / 改核心链路（资金、库存、结算、账号主流程）/ 状态机重构 / 正式评审会 | full |
| 单服务内小改动 / 无复杂状态流转 / 用户说"小需求别搞复杂" | lite |
| 用户明示档位或规模 | 听用户的 |
| 拿不准 | 默认 full——评审场景漏章节的代价大于多写两节 |
参考样例
- "给后台订单列表加一个'按状态筛选'下拉，小需求别搞复杂" → lite：背景与目标 / 方案设计 / 影响面 / 回滚与预案 / 自测要点，不写容量评估与排期。
- "给支付链路加每日对账文件解析入库，月底评审" → full：全章节，解析状态机 + 对账差异表 DDL + 文件接口约定 + 存量数据处理 + 灰度回滚。