规划功能或系统设计时，用结构化技术规格文档覆盖需求、架构…

在规划新功能、记录系统设计或编写架构决策记录时，快速产出一份完整、可评审的技术规格说明书。

适用场景

解决思路

1. 按模板创建规格文档，包含 Metadata 元数据区：Status（Draft | In Review | Approved）、Author、Reviewers、Last Updated。
2. 撰写 Executive Summary：用 2-3 句话说明解决什么问题、提出什么方案。
3. 撰写 Background & Context：列出当前痛点、为什么现在做、相关工作。
4. 定义 Goals：Primary Goals 用可衡量的目标逐条列出；Non-Goals 明确写出本规格不覆盖的内容。
5. 用表格列出 Functional Requirements，每行包含 ID、Requirement、Priority（如 FR-1、P0/P1）。
6. 列出 Non-Functional Requirements：性能（如响应时间 < 200ms）、可扩展性（如支持 10K 并发用户）、可用性（如 99.9% uptime）、安全要求。
7. 编写 Technical Design：包含 Architecture（图示或描述）、API Design（请求/响应示例，如 POST /api/v1/resource）、Database Schema（SQL 建表语句）。
8. 编写 Implementation Plan 表格：按 Phase、Timeline、Deliverables 分阶段列出交付物。
9. 定义 Testing Strategy：单元测试覆盖率（如 80%）、集成测试覆盖 API 端点、E2E 测试覆盖关键流程。
10. 用表格列出 Risks & Mitigations：每行包含 Risk、Probability、Impact、Mitigation。
11. 定义 Success Criteria 检查清单：所有 P0 需求实现、测试通过、性能达标、文档完成。
12. 需要更完整版本时参考 references/template.md，其中包含完整元数据区、成功指标表、架构图、详细 API 设计、安全威胁分析、监控与可观测性、风险评估矩阵、发布与回滚计划、依赖跟踪、Open Questions 等章节。
13. 遵循 Do 清单：包含可衡量的验收标准、添加架构图、定义明确的 API 契约、量化性能目标、记录风险与缓解措施、实现前取得干系人评审、包含安全考量、定义回滚流程。
14. 避免 Don't 清单：不要使用模糊需求（如 fast、scalable）、不要跳过非功能性需求、不要忽略安全考量、不要不探索备选方案、不要省略测试策略、不要遗漏依赖与风险。

适用边界 · 注意事项

• 需求尚未明确、还在早期探索阶段时，过早写详细规格会浪费精力
• 只需一次性小改动或原型验证、无需跨团队评审时，完整规格文档过重
• 没有干系人可参与评审时，规格文档难以发挥对齐作用