# Yzr Sys Design Doc

> 当用户要为软件系统或功能编写正式系统设计文档（设计文档 / design doc / 技术方案 / 评审用 设计文档）时使用本 skill——主场景是基于已有系统增加或修改功能 / 特性（"给工单系统加审批流， 写个设计文档" / "结算要支持优惠券叠加，出个技术方案"），也覆盖全新系统设计与小改动的轻量 设计说明。按改动规模路由 full / lite 两档模板（assets/ 单文件跟踪），产出结构一致的中文 Markdown 本地文件（full 档 14 节：需求层 / 方案层 / 落地层 + DFX），并配套生成实施任务书 （独立 tasks 文件，供执行 agent 按任务实施、反馈进度与设计变更，形成设计—执行循环迭代）。 触发："帮我写个设计文档" / "下周评审要用的系统设计" / "把这个功能的技术方案整理成文档" / "write a design doc for X"。 不适用：产品需求文档（PRD）、API 参考文档、README、事后沉淀进 wiki 的文档；用户只要 代码实现、没要文档（不主动加文档）。

- Skill: `yzr95924/yzr-sys-design-doc` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add yzr95924/yzr-sys-design-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yzr95924/yzr-sys-design-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: yzr95924 (https://skillmd.com/u/yzr95924)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yzr95924/yzr-sys-design-doc

---


# 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 档）**：设计文档评审后保持稳定；任务书只做指针不复制设计，
  执行反馈（进度 / 问题）只写任务书；设计要改先修订设计文档、再同步任务书——
  反向流动（绕过设计改实现）会让两份文档同时失效。

## 工作流 / 步骤

1. **判档**：按下"档位路由"表定 full / lite。
2. **读模板**：full → `assets/template-full.md`；lite → `assets/template-lite.md`。
   章节结构、每节"写什么 / 为什么"以模板文件为准。
3. **补上下文**：用户给了代码仓路径时，先读相关代码再写现状节；现状断言的依据与假设纪律
   按执行原则「现状有出处 / 假设显式化」执行。
4. **按模板写**：章节顺序与命名不动；某节确实不适用时**保留章节写"本期无 + 一句话原因"**——
   评审者需要看到"考虑过"，静默删节让人分不清"没想过"还是"不需要"。
5. **生成任务书（仅 full 档）**：按 `assets/template-tasks.md` 从功能点拆解与详细设计拆出任务，
   产出 `<功能slug>-tasks.md` 初始版（状态全"未开始"）——它随后交给执行者（人或 agent），
   进度 / 问题 / 设计变更按任务书模板 §3 的循环纪律流转；lite 档跳过本步。
6. **自检**（交付前逐条对照）：
   - 元信息块已填（状态默认"草稿"，日期填当天）
   - 非目标非空（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 +
  文件接口约定 + 存量数据处理 + 灰度回滚。