spec-writing

规格编写

概述

根据自然语言功能描述，创建清晰、完整且可测试的规格。规格聚焦用户价值和业务需求，避免涉及实现细节。

适用场景

• 创建新功能规格
• 完善现有规格
• 编写用户故事和验收标准
• 定义成功标准

不适用场景

• 生成实现任务——请使用 task-planning

核心原则

聚焦用户价值和业务需求，而非实现细节。除非绝对必要，否则不要在需求定义中指定技术选型。确保每项需求都可测试、可验证，并有可衡量的标准。尽量减少需要澄清的标记；根据行业标准做出合理假设，并明确记录。

规格结构

必需章节

1. 概述/背景：要解决什么问题？
2. 用户场景：谁会使用？如何使用？
3. 功能需求：必须具备哪些功能？
4. 成功标准：如何判断其是否有效？

可选章节

• 成功标准（对性能或安全性要求较高时）
• 边缘情况（需要特殊处理时）
• 依赖项（涉及外部系统时）
• 假设（信息不完整时做出决策的情况）

参见：modules/specification-structure.md，了解详细模板和指南

质量检查清单

• 不包含实现细节
• 需求可测试且明确无歧义
• 成功标准可衡量
• 用户场景涵盖主要流程
• 已识别边缘情况
• 范围界定清晰

成功标准快速参考

良好（以用户为中心、可衡量、不依赖技术）

• “用户可在 3 分钟内完成结账”
• “系统支持 10,000 名并发用户”
• “95% 的搜索可在 1 秒内返回结果”

不佳（聚焦实现、内部指标）

• “API 响应时间低于 200ms” -> 改为：“页面在 2 秒内加载完成”
• “Redis 缓存命中率高于 80%” -> 改为：“常用数据加载时没有明显延迟”
• “React 组件高效渲染” -> 改为：“UI 更新时没有明显的画面卡顿”

参见：modules/success-criteria-patterns.md，了解详细示例和转换流程

相关技能

• speckit-orchestrator：工作流协调
• task-planning：将规格转换为任务

故障排除

常见问题

如果规格过于含糊，请使用 success-criteria-patterns 模块来确保结果可衡量。如果规格中出现了实现细节，请对照“核心原则”进行检查，并重构内容，使其聚焦用户行为。

退出标准

• 规格文档包含全部 4 个必需章节：概述/背景、 用户场景、功能需求和成功标准
• 所有成功标准都以用户为中心且可衡量（例如：“用户可在 3 分钟内完成结账”），而非实现指标 （例如：“API 响应时间低于 200ms”）
• 通过质量检查清单：不包含实现细节、 需求明确无歧义、已识别边缘情况、范围界定清晰
• 除非规格明确标注为绝对必要的约束条件，否则需求中不出现技术选型
• 每项功能需求至少包含一个可测试的验收标准，且可从系统外部进行验证