writing-design-docs

编写设计文档

生成一份结构化设计文档，记录你要构建什么、为什么构建，以及如何验证其正常运行。输出：docs/plans/YYYY-MM-DD-<topic>-design.md。此技能生成文档后即停止。

流程

digraph design_doc {
    "Explore codebase & context" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "User selects approach" [shape=diamond];
    "Draft each section" [shape=box];
    "Write EARS requirements" [shape=box];
    "Present to user for review" [shape=box];
    "User approves?" [shape=diamond];
    "Write to docs/plans/" [shape=box];
    "Done" [shape=doublecircle];

    "Explore codebase & context" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "User selects approach";
    "User selects approach" -> "Propose 2-3 approaches" [label="none fit"];
    "User selects approach" -> "Draft each section" [label="selected"];
    "Draft each section" -> "Write EARS requirements";
    "Write EARS requirements" -> "Present to user for review";
    "Present to user for review" -> "User approves?";
    "User approves?" -> "Draft each section" [label="revise"];
    "User approves?" -> "Write to docs/plans/" [label="yes"];
    "Write to docs/plans/" -> "Done";
}

提出方案

起草前，先探索解决方案空间。研究代码库和相关库，然后提出 2-3 种方案：

• 首先给出你的推荐方案，并说明原因
• 对每种方案：说明架构概要、优点、缺点和工作量估算
• 至少包含一个更简单／规模更小的方案，以及一个更稳健／更具扩展性的方案
• 让用户先选择，再确定设计方向

设计文档模板

共六个部分。根据复杂度调整深度，参见“缩放指南”。

1. 摘要

用 2-4 句话说明是什么以及为什么。繁忙的工程师仅阅读这部分，就应能理解项目。

2. 项目目标与非目标

目标： 要解决的问题。必须保持的不变量。要具体，例如“p99 低于 200ms”，而不是“速度快”。

非目标： 明确不在范围内的合理事项。不是对目标的否定，而是你选择不处理的事项。

3. 背景

• 触发因素：GitHub Issues、Slack 讨论串或其他触发因素
• 代码库：与此工作相关的现有文件夹、文件和设计文档
• 外部文档：第三方库文档的 URL
• 参考资料：为设计提供依据的博客文章、RFC 或原始资料
• 影响范围：将要修改的模块或目录

4. 系统设计

• 架构概览：组件如何协同工作。必要时添加图示。
• 新增或修改的接口：类／结构体定义、API 边界。描述形态，而非实现。
• 关键函数：重要函数及其预期行为、契约和不变量。
• 考虑过的替代方案：说明未采用其他方案的原因。

5. 所需库与工具

外部依赖：

包	版本	用途
name	^x.y.z	说明所需原因

内部模块：

模块	路径	用途
name	src/path/	说明其提供的功能

如果没有依赖，请写“无”，不要省略此部分。

6. 测试与验证

这是最重要的部分，内容应最详尽。

验收标准

每条标准都使用 EARS 格式。每条标准都必须可测试且含义明确。

边界情况

涵盖相关类别：并发／竞态条件、依赖故障、错误处理／恢复、边界条件、安全注意事项。

验证命令

列出用于证明正确性的具体命令。包括 lint 和格式检查。

EARS 速查表

模式	模板	示例
普遍适用	THE SYSTEM SHALL [行为]	THE SYSTEM SHALL 加密所有静态数据
事件驱动	WHEN [事件] THE SYSTEM SHALL [行为]	WHEN 请求超出速率限制 THE SYSTEM SHALL 返回 HTTP 429
状态驱动	WHILE [状态] THE SYSTEM SHALL [行为]	WHILE 熔断器处于开启状态 THE SYSTEM SHALL 返回缓存的响应
可选	WHERE [功能] THE SYSTEM SHALL [行为]	WHERE 启用了详细日志记录 THE SYSTEM SHALL 记录请求正文
禁止事项	THE SYSTEM SHALL NOT [行为]	THE SYSTEM SHALL NOT 向客户端暴露内部错误详情
复合条件	WHEN [a] AND [b] THE SYSTEM SHALL [行为]	WHEN 队列已满 AND 消息具有高优先级 THE SYSTEM SHALL 淘汰优先级最低的最旧消息

规则： 使用 SHALL，绝不使用“should”／“may”。每项要求都必须能独立测试。避免模糊表述，使用可衡量的标准。

扩展指南

部分	小型（约 150 字）	中型（约 400 字）	大型（约 800 字）
摘要	2 句话	3 句话	4 句话
目标／非目标	每项 2-3 个要点	每项 4-5 个要点	6 个以上要点，并包含不变量
背景	仅链接	链接 + 文件列表	链接 + 文件 + 影响
系统设计	1 个段落	接口 + 函数	图表 + 完整 API 范围
库	表格或“无”	表格 + 理由	表格 + 替代方案
测试	3-5 个 EARS	8-12 个 EARS + 边缘情况	15 个以上 EARS + 全面的边缘情况

常见错误

错误	修正方法
把测试当作事后补充	使用红／绿 TDD，并在规范中定义测试用例
目标含糊	加入具体数字：“将 p99 从 800ms 降至 200ms”
缺少非目标	未说明的范围 = 默认纳入范围
把实现当作设计	描述契约和行为，而不是代码
没有背景链接	链接到催化因素——未来的读者需要了解原因

示例

查看 examples/ 中按规模划分的示例：

• small-cli-flag.md — 添加 --verbose 标志（精简但完整）
• medium-api-endpoint.md — 带身份验证和速率限制的 REST API
• large-event-system.md — 带重试和 DLQ 的分布式事件管道