Spec Kit：从可测试意图到可追踪验收
Spec Kit 快速上手：写出可测试的需求，而不是更多模糊文字
用小型阅读列表练习验收场景、明确未知项，并在实现前检查规格、计划和任务是否一致。
你将学会
- 先描述能被观察的结果
- 不要让未决问题偷偷变成架构
- 实现前先检查一致性
开始前需要
- 了解基本需求、Git 与测试
- 分清本地开发和应用部署
追踪小功能从意图到证据的过程，区分流程约定与已验证行为。
先看结论
- 验收场景必须有可观察结果。
- 影响范围的未知选择不能伪装成技术默认值。
- 先理解分析发现，再批准修复。
先描述能被观察的结果
使用可丢弃的练习项目和仅包含公开示例标题的合成阅读列表。第一个旅程是保存条目，并在应用重启后仍能看到它。同时说明重复条目与无效输入应该怎样处理，不要因为熟悉某个框架就过早在需求中指定数据库。
模板把用户故事、功能需求和成功标准分开。一个验收场景需要初始状态、操作和可观察结果。“保存要可靠”过于模糊；“保存一个有效条目并重启后，该条目只出现一次”才给审阅者提供了具体检查依据。
不要让未决问题偷偷变成架构
明确记录列表是设备本地保存，还是跨账户共享等未知项。这会影响隐私、同步和部署要求。如果不同选择会明显改变产品，应在技术计划前澄清；生成出来的假设不等于用户已经作出决定。
在选择的集成里，使用已安装的项目原则、规格、必要时澄清、计划和任务指令。不同集成的调用形式可能不同，不要把陌生的斜杠指令直接粘进操作系统终端。本篇解释流程，但不声称已经运行真实助手会话。
实现前先检查一致性
analyze 用于任务生成后比较 spec.md、plan.md 和 tasks.md。重点寻找没有任务覆盖的需求、目的不明的任务、相互矛盾的存储选择，以及无法测试的验收标准。报告应该指出具体文档位置并解释不一致，而不是只给一个分数。
先审阅报告，再授权修改。核心分析约定要求只读，但指令同时描述扩展钩子并调用前置检查脚本，周边机制仍需单独检查副作用。生成建议报告不等于批准其中全部修复措施。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
写一个保存并重启的场景。
- 2
决定重复行为并记录未知项。
- 3
把需求对应到计划选择和任务。
- 4
实现前检查三份文档是否一致。
可复制示例
{
"合成练习": true,
"初始状态": "一个有效的公开示例条目",
"操作": "保存并重启",
"预期": "条目恰好出现一次",
"未知项": "设备本地还是跨账户共享",
"已授权实现": false
}常见问题
规格里应该立即选择数据库吗？
如果它不是既定约束，技术选择通常放在计划中。
analyze 会自动应用建议吗？
核心约定要求只读报告和单独批准修复；扩展与辅助脚本需要另外检查。
资料来源
- Spec Kit / templates/spec-template.md来源核查 2026-09-14
- Spec Kit / templates/commands/analyze.md来源核查 2026-09-14
- Spec Kit / README.md来源核查 2026-09-14