← LeaderboardThe Skill Leaderboard

technical-spec-template

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

Published by mohitagw15856 ↗mohitagw15856/pm-claude-skills

Try your first task

technical-spec-template

Start a fresh conversation. Replace the highlighted placeholders.

Use technical-spec-template to write a technical specification for [feature/system] based on [PRD/description]

Required inputs

  • [feature/system]
  • [PRD/description]

User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗

SKILL.md

name: technical-spec-templatelanguage: zhdescription: "撰写连接产品需求和工程实现的结构化技术规格文档。当撰写技术规格、工程规格、系统设计文档或 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 分以上才算可以交付。

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

质量检查

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

反模式

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

示例触发语

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