---

name: technical-spec-template language: zh description: "撰写连接产品需求和工程实现的结构化技术规格文档。当撰写技术规格、工程规格、系统设计文档或 API 规格时使用。产出完整的规格：问题陈述、建议方案、数据模型、API 设计、考虑过的备选方案、安全考量、测试计划和上线策略。"

technical-spec-template 的简体中文翻译，英文版本为规范版本。

技术规格模板

写出工程师真正会读的技术规格：清楚的问题框定、没有歧义的需求、明确的决策，以及记录下来的取舍。

所需输入

如未提供，请向用户询问：

• 功能或系统描述（要写规格的是什么）
• 相关的 PRD 或产品说明（如有）
• 工程评审人（需要谁签字确认）
• 已知约束（技术限制、安全要求、性能目标）

什么时候写技术规格

在以下情况写技术规格：

• 功能需要改动 2 个以上系统
• 有重大的架构决策要做
• 不止一名工程师参与实现
• 功能涉及安全、隐私或合规
• 估计工作量超过 5 个故事点

修复简单缺陷或 1 到 2 小时的改动，跳过规格。

---

技术规格输出格式

技术规格：[功能名称]

作者： [姓名] 状态： 草稿 | 评审中 | 已批准 | 已实现 创建： [日期] | 最后更新： [日期] 评审人： [技术负责人、架构师、产品经理，需要时加安全] 相关 PRD： [链接] | Jira 史诗： [链接]

---

1. 问题陈述

[2 到 3 句。我们在解决什么问题，为什么是现在？这里不出现方案用语。]

2. 目标与非目标

目标（在范围内）：

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

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

• [这份规格不包括什么]
• [需要尽早否定的常见假设]

3. 背景

[工程师理解决策空间所需的任何已有方案、相关系统或背景。链接到以前的规格、ADR 或研究。]

4. 建议方案

整体思路： [2 到 4 句描述选定的方案。为什么选这个而不是备选方案？]

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

数据模型变更：

-- 新表或表结构变更
[写出 DDL 或表结构定义]

API 设计：

[接口] [方法]
请求：{ [字段及类型] }
响应：{ [字段及类型] }
错误码：[列表]

关键实现细节：

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

5. 考虑过的备选方案

选项	优点	缺点	为什么否决
[备选 1]	[好处]	[缺点]	[没选的原因]
[备选 2]	[好处]	[缺点]	[没选的原因]

6. 安全与隐私考量

• 存储的数据：[涉及哪些个人信息或敏感数据]
• 认证：[如何控制访问]
• 授权：[需要什么权限]
• 加密：[存储和传输的要求]
• 合规影响：[GDPR、SOC2、个人信息保护法等，如相关]

7. 性能与可扩展性

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

8. 测试计划

• 单元测试：[要覆盖的关键场景]
• 集成测试：[要测试的系统边界]
• 压力测试：[如果性能关键]
• 边界情况：[已知的棘手场景]
• 回滚计划：[出问题时如何回退]

9. 上线计划

• 功能开关：[是 / 否，开关名称]
• 上线阶段：[每个阶段的用户比例]
• 监控：[要设置的指标和告警]
• 推进上线的成功标准：[什么条件必须成立]
• 回滚触发条件：[什么情况会立即回滚]

10. 待定问题

问题	负责人	截止日期	结论
[未解决的问题]	[姓名]	[日期]	[待定]

11. 实施时间表（粗略）

阶段	工作	估计工作量
[阶段 1]	[要做什么]	[X 天 / 点]
[阶段 2]	[要做什么]	[X 天 / 点]
合计		[X 个故事点]

---

指南

• 规格是决策记录，不是任务清单：记录为什么做出这些决策
• 所有待定问题都必须有负责人和截止日期
• 涉及用户数据的功能，安全与隐私部分永远不是可选的
• 建议异步评审：工程师先读，然后开 30 分钟同步会解决问题
• 随实现进展更新规格：过时的规格比没有规格更糟

延伸材料

这个技能附带支持文件，可用时请使用：

• references/spec-decisions.md：规格是用来做什么的：决策、备选方案和影响范围。在产出时应用它；它包含上面方法摘要压缩掉的校准和判断。
• templates/spec-skeleton.md：可填写的成果模板，质量关卡写在里面。当用户想自己完成文档而不是生成时提供。

评分量表（0 到 40）

交付前给这个技能的任何产出打分；32 分以上才算可以交付。

维度	0	5	10
问题框定	问题陈述只是换个说法的方案（"我们需要一个队列"），或缺失；没有非目标	写了问题，但混入了方案用语；有非目标但很笼统（"不在范围内：其他一切"）	用用户或业务语言并带数字描述问题，独立于任何方案；目标可衡量；至少 2 个能否定真实范围假设的非目标
决策记录	只有一个方案，没有备选：是设计描述，不是决策记录	有备选方案表，但是稻草人（只有缺点、没人支持的选项）；否决理由是喜好而不是证据	至少 2 个真正的备选方案，优点写得诚实，否决理由基于证据，有分歧时记录了反对意见，有争议的决定写明重新评估的条件
安全与隐私深度	在涉及用户数据的功能上跳过或写"不适用"	套话式回答（存储和传输加密），没有分析这个功能具体的数据暴露	列举了涉及的数据，点出设计中最大的隐私风险，具体处理了认证、授权和合规，未解决的风险明确作为批准的前提
运营就绪	没有测试计划、上线计划或回滚触发条件；没有待定问题或全是"待定"	简要写了测试和上线，但回滚只是没测试过的意图；部分待定问题缺负责人或日期	测试覆盖棘手的边界情况，上线分阶段并有推进标准，回滚触发条件具体（且不会让数据处于中间状态），每个待定问题都有具名负责人和截止日期

质量检查

• 问题陈述不含方案用语
• 非目标明确列出至少 2 件可能被默认在范围内的事
• 至少记录了 2 个备选方案及否决理由
• 涉及用户数据的功能都完成了安全与隐私部分
• 所有待定问题都有具名负责人和截止日期（不是"待定"）

反模式

• 不要在问题陈述中加入方案用语：问题必须独立于建议的方案来描述
• 不要省略考虑过的备选方案：只考虑一种方案的规格没有经过恰当评估
• 不要把待定问题写成没有具名负责人和截止日期的"待定"：未解决的问题就是阻碍
• 涉及用户数据的功能不要跳过安全与隐私部分
• 不要让非目标部分为空：总是列出至少两件可能被默认在范围内的事

示例触发语

• “写一份技术方案。”
• “给这个功能写工程规格。”
• “写系统设计文档。”
• “写 API 规格说明。”