实测 spec-kit：让 AI 写代码前先定验收

让 AI 写代码之前，先把「怎样才算做完」写清楚。作者在一台没有 Claude Code、也没有 Docker 的机器上试装 spec-kit，发现它首先提供的是一套写规格、消除歧义和检查计划的工作结构。

这次实测最有价值的部分，是把安装成功、文件生成和真正完成开发区分开了。对日常使用 AI 编程的程序员来说，可以借此检查：我们交给 agent 的任务，到底包含了多少可执行、可验收的信息。

安装成功，为什么还不能让 AI 开工

作者的机器已有 Python 3.11 和 uv，执行的是：

uv tool install specify-cli
specify --version

这里解决的是 CLI 安装和版本确认。注意第一行的包名是 specify-cli，第二行调用的命令是 specify。作者得到的版本为 specify 1.2.3，原文引用的 README 要求是 Python 3.11+ 和 uv。

接着运行 specify init se-demo --integration claude，初始化立即停止，提示 claude not found，并给出 Anthropic 的安装指引。

原因很直接：spec-kit 提供流程和文件，实际执行开发任务还需要所选 coding agent。CLI 装好了，不代表 Claude Code 也装好了。

作者在 specify init --help 中找到 --ignore-agent-tools，用它跳过检查，继续观察生成结构。这个参数只适合当前的文件检查目的，不能补上缺失的 agent。

因此，这次实验验证了安装、依赖检查和项目文件生成，没有验证完整的 AI 开发流水线。机器没有 Docker 是实验条件，原文没有据此证明其他使用场景都不需要 Docker。

生成的文件里，哪些真正影响开发

初始化后，主要内容分布在 .specify/ 和 .claude/skills/。

.specify/ 存放项目级流程资料。其中，memory/constitution.md 是一份 50 行的空白原则模板；templates/ 包含 spec、plan、tasks、checklist 和 constitution 模板；scripts/bash/ 有六个脚本，包括 create-new-feature.sh、setup-plan.sh、setup-tasks.sh 和 check-prerequisites.sh。

作者还特别纠正了目录位置：上游仓库的工作流定义是 workflows/speckit/workflow.yml，名称为 Full SDD Cycle，它不在 templates/ 里。integrations/ 则保存所选 agent 的 manifest，即描述这套集成如何配置的清单。

另一个实用文件是 .specify/init-options.json，它记录项目初始化选项：

{
  "ai": "claude",
  "ai_skills": true,
  "feature_numbering": "sequential",
  "integration": "claude",
  "script": "sh",
  "speckit_version": "1.2.3"
}

团队需要确认项目如何生成时，可以直接查看它。注意 integration 和 speckit_version：讨论命令是否可用，至少要先对齐这两项。

作者生成的 .claude/skills/ 包含十项能力：specify、plan、tasks、implement、clarify、analyze、checklist、constitution、converge 和 taskstoissues。

命名还有一个容易踩的坑。许多文章使用 /speckit.specify，但作者这次安装的 1.2.3 生成的是 speckit-specify、speckit-plan、speckit-tasks、speckit-implement 等带连字符的目录。其他 agent 的集成形式也可能不同。

先检查项目实际生成的 skill，再照着文章调用命令。

给 agent 的规格，怎样才算能执行

打开 .specify/templates/spec-template.md，作者发现三个必填部分。

第一部分是 User Scenarios & Testing (mandatory)，要求按 P1 到 P3 排列用户故事，并考虑 Edge Cases。它既要交代用户做什么，也要交代异常情况下应该发生什么。

第二部分是 Requirements (mandatory)，写清功能要求；涉及数据时，还需要描述关键数据实体。

第三部分是 Success Criteria (mandatory)，要求成功标准可以衡量。不能只写「体验更好」，需要说明凭什么判断任务已经完成。

这三部分分别约束优先级、行为和验收证据。尤其是 Testing 从规格阶段就出现，避免把「如何证明正确」留到代码写完之后。

作者将其与面向人的文档作了区分：人读文档时，可以结合背景理解动机；agent 执行任务时，更需要明确的边界。这个区分有用，但不必理解为 agent 不需要背景。背景解释选择，验收条件约束结果，两者可以同时保留。

plan 模板还包含 Constitution Check，要求检查技术计划是否违反 memory/constitution.md 中的项目原则。新项目里的 library-first、CLI interface 等只是示例，团队需要自己填写真正适用的规则。

空白模板不会自动变成有效约束。

作者据此提出一条合理顺序：先用 speckit-constitution 定原则，再通过 speckit-specify 写规格、speckit-clarify 消除歧义，然后进入 speckit-plan 和 speckit-tasks。实施前用 speckit-analyze 检查文档一致性，之后由 speckit-implement 开发、speckit-converge 收尾；需要时用 speckit-taskstoissues 转成 GitHub issue。

这是作者整理的建议顺序。原文没有展示完整执行记录，也没有证明 clarify、analyze、checklist 节省了多少时间。

我的判断

这篇最值得采纳的，是把「任务完成」提前定义。程序员经常给 AI 一段功能描述，却把异常行为、优先级和验收标准留在自己脑子里。spec-kit 的模板至少能把这些遗漏暴露出来。

不过，文章的证据主要停留在工具结构层面。它由 AI deepseek-v4.1-flash 经 ollama-cloud、通过 Hermes Agent 撰写，作者声明有人类控制和质量检查。可讨论的依据是文中报告的命令结果与文件检查，不能把它扩展成生产项目效果证明。

与 OpenSpec 的比较也应保留分寸。原文截至 2026 年 10 月 23 日记录 OpenSpec 有 72,780 颗星、采用 MIT 许可证，并称其最近更新于当天。这些是来源中的时间快照，星数不能证明开发效果。

作者认为 spec-kit 的 constitution、workflow 和脚本更完整，OpenSpec 更轻、更灵活。但文章没有给出同一任务下的对照实验。团队如果已有成熟需求文档、测试和评审流程，先补齐验收条件，也可能比立即引入整套工具更合适。

另外，「规格太长会让 agent 读不全，效果往往更差」属于作者经验，没有上下文长度、模型配置或对照数据。实际应检查内容是否相关、组织是否清楚，不能直接推导成规格越短越好。

能拿来做什么

• 挑一个小型前端功能，先手写优先级、异常情况和至少一条可衡量的成功标准。例如表单提交失败后保留已填内容，并展示可识别的错误状态，再让 agent 制订计划。
• 试用 spec-kit 时，先核对本机版本、--integration 和生成的 .claude/skills/。使用 --ignore-agent-tools 查看结构后，仍要补齐实际执行开发的 agent。
• 将团队已经认可的项目原则填入 constitution，再检查 plan 是否回应这些原则。没有明确规则时，先讨论规则，不要把模板存在当成检查已经完成。
• 在 AI 编程流程里留出 clarify 和 analyze 的位置，先解决歧义、核对规格与任务是否一致。可以从一个功能开始试验，再决定是否采用整套流程。