GitHub Spec Kit 146k stars：为什么 Agent 写代码前要先写规格？

GitHub Spec Kit 在 2026-11-03 发布 v1.3.0。这个 2025 年 8 月才创建的项目，已经拿到 146,675 stars、13,148 forks 和 207 个未关闭 issue/PR。它不是新的编程 Agent，而是一套让 Agent 按“规格 → 计划 → 任务 → 实现 → 收敛”工作的开源流程工具。

它真正反常识的地方不是“让 Agent 多写文档”，而是把规格当成可执行工件：spec 定义要做什么，plan 定义怎么做，tasks 定义按什么顺序做，最后用 converge 检查代码有没有漏掉规格。代码生成越来越便宜，验证却越来越贵，这才是 Spec Kit 被大量关注的原因。

发布日期：2026-11-04 ｜关键词：GitHub Spec Kit、SDD、规格驱动开发、AI 编程｜约 2,000 字

一、Spec Kit 是什么：给 Agent 的流程层，不是另一个 Agent

官方对 Spec Kit 的定义很克制：一个开源工具包，给 AI 编程 Agent 提供结构化流程、可复用模板和可记录的结果。它不训练模型，不提供 IDE，也不替代 Claude Code、Codex、Cursor 这类客户端；它做的是把 Agent 的工作从聊天窗口搬到仓库里的 Markdown 工件。

官方文档首页列出 38 个集成、157 个社区扩展、33 个预设和 270 多位贡献者。项目采用 MIT 许可证，要求 Python 3.11+，通过 specify CLI 初始化。最新 v1.3.0 的核心仍然是 SDD（Spec-Driven Development，规格驱动开发）；bug fixing 和 idea assessment 是可选扩展，不是每个功能都必须走的流程。

它是什么	它不是什么
给 Agent 的流程工具包	新的编程 Agent
仓库里的 Markdown 工件	模型或 IDE
可切换 38 个集成的流程层	Copilot 专属功能
MIT 开源项目	付费 SaaS

Spec Kit 不是让 Agent 先写一份 PRD：PRD 描述产品意图，spec 还要落到验收标准、边界和非目标，再由 plan、tasks 接住。它加的是一条可检查的流水线，不是一份文档。

二、为什么现在要“先写规格”：Agent 把瓶颈推到了评审

过去的流程是 prompt → code。Agent 写得越快，评审越容易变成逆向工程：reviewer 看到一大段 diff，却不知道作者原本想解决什么问题，只能从代码反推意图。代码越便宜，这种反推越贵。

规格的作用，是给 Agent 和 reviewer 一份共同参照。它至少要说清四件事：要解决什么问题、什么算完成、什么明确不做、哪些边界不能碰。没有这四件事，Agent 很容易出现三种返工：做错、做多、做完无法验证。

官方文档把 SDD 的核心概括为“意图驱动、丰富规格、多步细化”，并有一句很关键的话：规格不再是写完就丢的脚手架，而是可以直接驱动实现的工件。这里的“可执行”不是把 spec 当代码编译，而是它能继续生成 plan、tasks，并反过来用于 converge 检查。

多 Agent 和长任务还有一个现实问题：聊天记录会丢、会截断、会在交接时失真，仓库里的 spec 不会。它可 diff、可 review、可归档。

三、9 个步骤里，真正有价值的是 3 个卡点

Spec Kit 的完整流程有 9 个命令：

/speckit.constitution
/speckit.specify
/speckit.clarify
/speckit.plan
/speckit.checklist
/speckit.tasks
/speckit.analyze
/speckit.implement
/speckit.converge

但官方明确说，只有 /speckit.specify 是 /speckit.plan 之前必须的；clarify、checklist、analyze 都是质量门，不是打卡任务。真正值得先用的，是这三个卡点：

卡点	作用	防止什么
clarify	最多问 5 个针对性的问题，把答案写回 spec	在歧义上做设计
checklist	给需求做“单元测试”，检查完整、清晰、一致	规格没写完就开工
analyze	只读检查 spec、plan、tasks 是否互相矛盾	任务没有需求、计划违背规格

checklist 还有一个容易被忽略的设计：自定义 checklist 由 reviewer 负责，[x] 表示“需求质量已确认”，不表示“实现完成”；/speckit.implement 可以读取勾选状态并在未完成时询问，但不能替 reviewer 改标记。这个约束很关键，它防止 Agent 自己写规格、自己检查、自己宣布通过。

/speckit.converge 只做追加：把代码和 spec、plan、tasks 对照，发现缺口就往 tasks.md 追加任务，再 implement、再 converge，直到 Converged。它不是自动保证正确，而是把“还差什么”变成可重复清单。

四、constitution 和三个核心工件：各管什么

Spec Kit 把不同问题拆给不同工件，避免一份文档承担所有职责：

工件	回答的问题	不该放什么
constitution	项目原则和底线	具体功能细节
spec.md	做什么、为什么、验收标准	技术栈
plan.md	怎么做、架构和约束	需求变更
tasks.md	按什么顺序做、哪些可并行	新产品需求

这个拆分的好处是评审对象变清楚了。产品同学可以看 spec，技术负责人可以看 plan，执行者可以看 tasks；任何一层出问题，都能回到对应工件修，而不是在一段聊天记录里翻找。constitution 只需在项目开始时建一次，原则变了再更新；后面每个功能重复 specify 到 converge。

五、它和 plan mode、AGENTS.md、PRD 到底有什么区别

这几个东西经常被混为一谈，但职责不同：

对象	作用	生命周期	和 Spec Kit 的关系
Prompt	一次性请求	会话	是 spec 的输入
Plan mode	当前任务的临时计划	会话/任务	可以固化成 plan.md
AGENTS.md	Agent 的长期行为规则	长期	规定“怎么做事”，不规定“这次做什么”
PRD	产品意图	版本	可能是 spec 的上游
spec.md	可执行的功能契约	功能周期	Spec Kit 的核心

所以 AGENTS.md 和 spec 不是二选一。AGENTS.md 可以规定“所有功能必须先有 spec、必须跑测试”，spec 则说明“这个功能具体要什么”。一个管常驻规则，一个管本次合同。

Spec Kit 也没有解决所有问题。官方文档明确说，它不规定需求变化后 spec、plan、tasks 该如何保存或修改；这是团队自己的需求变更治理。工具给你流程，不给你组织能力。

六、谁适合用，谁不适合

适合	不适合
多 Agent 协作、长任务、审查成本高	一行修复、一次性脚本
需要审计、合规、交接	需求还在探索，暂时写不出验收标准
既有系统改造、跨团队功能	团队不愿意 review 规格
需要可复现的 Agent 交付	把 spec 当形式，让 Agent 自写自审

一个判断标准很简单：如果“写错方向”的代价，明显高于“写一份短 spec”的成本，就值得用；如果任务小到一句话能说清，Spec Kit 反而会增加流程负担。

146k stars 说明关注度，不等于生产采用率；207 个未关闭 issue/PR、13k forks 说明它活跃，也还在快速变化。落地前先拿一个低风险功能试点，别一上来就全组织推广。

七、最小落地：别一上来跑满 9 步

第一次用，建议只跑五步：constitution、specify、plan、tasks、implement。先把“意图 → 计划 → 任务 → 代码”跑通，再按风险加质量门。

具体可以这样做：

一个功能一份 spec，控制在 1–2 页，写清目标、非目标、验收标准和边界；
spec 先走一次 code review，再让 Agent 写代码；
需求有歧义时加 clarify，高风险变更加 checklist 和 analyze；
大功能用 converge 收尾，小修小补不必强上；
试点时统计 review 评论数、返工次数、从 spec 到 merge 的周期，而不是只看“生成了多少代码”。

既有项目也可以先用一个功能或 bug fix 试，不必补全历史规格；1.3.0 的 bug fixing 扩展就是先评估原因、再做限定修复、最后验证原始症状。

Spec Kit 的工件是 Markdown，最自然的做法是和代码一起放仓库、一起 review。跨团队协作或需要审计时，可以再加一层归档：把 spec.md、plan.md、tasks.md 和 converge 结果按功能版本放到七牛云对象存储 Kodo，这样 review 时不仅能看到最终代码，还能看到当时的约束和验收标准；如果 Agent 需要隔离执行，再把运行环境放到七牛云 QVM。

单人项目把工件留在仓库就够了；只有多人协作、合规留存或长周期项目，才需要把“为什么这么写”和“怎么验证”变成可追溯记录。

八、结论：Spec Kit 火，不是因为大家爱写文档

Spec Kit 的真正价值，是把“让 Agent 写代码”拆成一条可检查的链：意图 → 规格 → 计划 → 任务 → 实现 → 收敛。它不保证代码正确，也不替代测试和 review；它只是让错误更早暴露，让评审有参照物，让多 Agent 交接有共同语言。

当代码生成越来越便宜，团队的竞争力会更多落在两件事上：能不能说清楚要什么，能不能验证做对了。Spec Kit 的 146k stars 可能会波动，但这两个问题不会消失。

FAQ

Spec Kit 是 GitHub 官方产品吗？ 它放在 GitHub 官方组织下，采用 MIT 许可证，官方文档把它定位为开源工具包；它不是需要单独付费的 GitHub 产品，也不只服务 GitHub Copilot。

支持 Claude Code、Codex、Cursor 吗？ 官方文档列出 38 个集成，包含 Copilot、Claude、Codex、Cursor、Gemini、Kimi、ZCode 等。命令拼写会随 Agent 变化，例如 Copilot 默认用 /speckit-*，Codex 用 $speckit-*。

只能用于新项目吗？ 不是。官方有 existing projects 指南；既有代码建议从一个功能或一个 bug fix 开始，不要一次性补全历史规格。

能保证代码质量吗？ 不能。它让需求更清楚、冲突更早暴露、实现可收敛，但测试、代码 review、安全扫描仍然不可少。