technical-spec-template

技术规格说明模板技能

编写工程师愿意阅读的技术规格说明——清晰地阐述问题，明确无歧义地列出需求，明确做出决策，并记录权衡取舍。

必要输入

如果用户未提供，请向用户询问以下信息：

• 功能或系统描述（需要编写规格说明的内容）
• 相关 PRD 或产品简报（如有）
• 工程评审人员（需要哪些人签字批准）
• 已知约束（技术限制、安全要求、性能目标）

何时编写技术规格说明

在以下情况下编写技术规格说明：

• 该功能需要修改 2 个或更多系统
• 需要做出重要的架构决策
• 不止一名工程师将参与实现
• 该功能涉及安全、隐私或合规性
• 预估工作量 >5 个故事点

对于简单的错误修复或 1–2 小时的改动，无需编写规格说明。

---

技术规格说明输出格式

技术规格说明 — [Feature Name]

作者： [Name] 状态： 草稿 | 评审中 | 已批准 | 已实现 创建日期： [Date] | 最后更新： [Date] 评审人员： [Eng Lead、Architect、PM，需要时包括 Security] 相关 PRD： [Link] | Jira Epic： [Link]

---

1. 问题陈述

[用 2–3 句话说明我们要解决什么问题，以及为什么现在要解决。此处不要描述解决方案。]

2. 目标与非目标

目标（范围内）：

• [具体、可衡量的结果]
• [具体、可衡量的结果]

非目标（明确不在范围内）：

• [本规格说明不涵盖的内容]
• [需要尽早澄清的常见误解]

3. 背景与上下文

[此前的方案、相关系统，或工程师理解决策空间所需的上下文。链接到先前的规格说明、ADR 或研究资料。]

4. 拟议解决方案

高层方案： [用 2–4 句话描述所选解决方案。为什么选择此方案而非其他方案？]

系统架构图： [描述或嵌入：涉及哪些服务、数据如何流动、调用哪些 API]

数据模型变更：

-- New tables or schema changes
[Include DDL or schema definition]

API 设计：

[Endpoint] [Method]
Request: { [fields and types] }
Response: { [fields and types] }
Error codes: [list]

关键实现细节：

• [重要的技术约束或方案]
• [边缘情况处理]
• [第三方依赖及其版本]

5. 考虑过的替代方案

选项	优点	缺点	拒绝原因
[替代方案 1]	[优点]	[缺点]	[未选择的原因]
[替代方案 2]	[优点]	[缺点]	[未选择的原因]

6. 安全与隐私考量

• 存储的数据：[涉及哪些个人身份信息或敏感数据]
• 身份验证：[如何控制访问权限]
• 授权：[需要哪些权限]
• 加密：[静态数据／传输中的数据加密要求]
• 合规性影响：[如适用，列出 GDPR、SOC2 等]

7. 性能与可扩展性

• 预期负载：[请求数／秒、数据量]
• 延迟要求：[P50／P95 目标]
• 缓存策略：[如适用]
• 数据库索引：[需要新增的索引]
• 已知瓶颈：[需要关注的环节]

8. 测试计划

• 单元测试：[需要覆盖的关键场景]
• 集成测试：[需要测试的系统边界]
• 负载测试：[如对性能要求较高]
• 边缘情况：[已知的棘手场景]
• 回滚计划：[出现问题时如何还原]

9. 发布计划

• 功能标志：[是／否 — 标志名称]
• 发布阶段：[各阶段的用户百分比]
• 监控：[需要设置的指标和警报]
• 推进发布的成功标准：[需要满足的条件]
• 回滚触发条件：[哪些情况会导致立即回滚]

10. 待解决问题

问题	负责人	截止日期	解决情况
[未解决的问题]	[Name]	[Date]	[待处理]

11. 实施时间表（粗略估算）

阶段	工作内容	预估工作量
[阶段 1]	[要实现的内容]	[X 天／点数]
[阶段 2]	[要实现的内容]	[X 天／点数]
总计		[X 个故事点]

---

指南

• 规范是一份决策记录，而不是任务清单——记录做出决策的原因
• 所有待解决问题都必须指定负责人和截止日期
• 对于涉及用户数据的功能，安全与隐私部分绝不能省略
• 建议采用异步评审：工程师先阅读，然后安排 30 分钟的同步会议来解决疑问
• 随着实现推进，持续更新规范——过时的规范比没有规范更糟糕

深入材料

此技能附带支持文件——请在这些文件可用时使用：

• references/spec-decisions.md — 规范的用途：决策、备选方案和影响范围。生成输出时请参考此文件；其中包含对上述方法摘要所做压缩的校准和判断。
• templates/spec-skeleton.md — 可填写的交付文档模板，内含质量检查项。用户想自行编写文档而非让系统生成时，请提供此模板。

质量检查

• 问题陈述不包含任何解决方案相关表述
• 非目标明确列出至少 2 项可能被误认为属于范围的内容
• 记录至少 2 种备选方案，并说明拒绝它们的原因
• 对于涉及用户数据的功能，已完成安全与隐私部分
• 所有待解决问题均指定了负责人和截止日期（不能写“待定”）

反模式

• 不要在问题陈述中加入解决方案相关表述——必须独立于拟议的解决方案来描述问题
• 不要省略考虑过的备选方案——只考虑一种方案的规范尚未得到恰当评估
• 不要将待解决问题留作“待定”，而不指定负责人和截止日期——未解决的问题都是阻塞项
• 对于涉及用户数据的任何功能，都不要跳过安全与隐私部分
• 不要将非目标部分留空——始终至少列出两项可能被误认为属于范围的内容