从 Prompt 到可执行规格：认识 GitHub Spec Kit

从 Prompt 到可执行规格：认识 GitHub Spec Kit

过去一年，几乎所有写代码的人都试过同一种工作方式。在对话框里描述想要的东西，AI 生成代码，跑起来，发现不对，再用自然语言纠正，再生成，再纠正。做一个小工具或者原型时，这个循环快得让人上瘾，可一旦功能上了规模，问题就开始出现。AI 给出的实现和你脑子里的需求之间始终隔着一层猜测，它猜中了皆大欢喜，猜偏了就要在代码里一点点返工。更麻烦的是，整个过程没有留下任何可以审查的中间产物，你手里最终只有代码，以及一段已经滚得很长、谁也不想再读的对话记录。

GitHub 开源的 Spec Kit 给出了另一种答案。它不直接回答"怎么让 AI 把代码写得更好"，而是先解决一个更上游的问题，怎么把人的意图变成一份精确、完整、可以被 AI 反复执行的规格。2026 年 8 月，项目在首个提交一周年时发布了 1.0.0 版本，命令体系、扩展机制和离线部署方案都已成型，社区贡献的扩展和预设数以百计。

一、直接让 Prompt 变成代码，问题出在哪

把一句话需求直接交给 AI 生成代码，本质上是一次没有中间检查点的翻译。意图在你脑子里，代码是 AI 给的最终译文，中间没有任何可以停下来核对的地方。传统软件工程里，这两者之间本来存在一层中间产物，需求文档、设计文档、任务拆解，它们的作用不是走流程，而是让模糊的意图在变成代码之前先被人审视一遍。AI 编码工具把写代码的成本压到极低之后，很多人连这层中间产物也一并丢掉了，结果就是所有的歧义、遗漏和自相矛盾，全部推迟到代码阶段才暴露。

第一个典型症状是需求漂移。你说"做一个任务看板"，AI 自行决定了列的数量、拖拽规则、权限模型，这些决定散落在十几个文件里。等你发现它理解错了，纠正的成本已经很高，因为错误的假设已经变成了数据模型和 API。第二个症状是不可复现，同一句 prompt 在新的会话里再问一次，得到的可能是另一套实现，你无法解释为什么线上版本长这样，也无法让另一个 agent 基于同样的意图重新生成。第三个症状是验收无据可依，功能做完之后，"做完了"的标准是 AI 自己说的，你只能靠手动点一遍来确认，漏测一个边界条件，bug 就流到了线上。

这些问题的根源不是模型不够聪明，而是流程里缺少一个可审查、可版本化、可重复执行的事实来源。代码一旦成为唯一的事实来源，每次改需求都等于让 AI 在已有代码上再赌一次。Spec Kit 把这个顺序倒了过来，先让规格成为事实来源，代码只是规格在某个技术栈下的一次生成结果。生成得不满意，可以调整规格后重新生成，而不是在代码里和 AI 拉锯。

二、Spec Kit 是什么

Spec Kit 是 GitHub 官方维护的开源工具套件，仓库在 github.com/github/spec-kit，核心由两部分组成。一个是名为 specify 的命令行工具，负责在项目里初始化目录、模板和 agent 集成，另一个是一组交给 AI 编码助手执行的斜杠命令，负责把自然语言需求逐步加工成规格、方案、任务和代码。它本身不绑定任何一个 AI 助手，官方文档站目前列出了 38 个集成，Copilot、Claude、Gemini、Codex、Cursor、Zed、Kiro 等都在其中，没有列出的工具也可以用 generic 集成兜底。一个项目同一时间只启用一个集成，但随时可以用命令切换，生成的文件格式不依赖特定厂商。

它背后的核心思想叫规范驱动开发，英文是 Spec-Driven Development，简称 SDD。这个词在官方文档 spec-driven.md 里讲得很直白，过去几十年代码是王，规格只是编码开始前搭好、随后就丢弃的脚手架。SDD 把这个权力结构倒过来，规格不再服务于代码，而是代码服务于规格。PRD 不是指导实现的参考材料，而是生成实现的源头，技术方案不是写给人看完就归档的文档，而是能产出代码的精确定义。规格和实现之间那条长期存在的鸿沟，不是靠更详细的文档去填平，而是靠让规格及其实现计划变得可执行来消除，中间不再有翻译损耗，只有一次又一次的变换。

需要强调的是，Spec Kit 不是一个帮你写文档的模板包，也不是又一个 agent 框架。它做的事情很克制，规定一套文件的格式和生成顺序，然后让你手头的 AI 助手按顺序执行。真正做理解和生成工作的还是你选择的模型，Spec Kit 提供的是护栏、模板、检查点和闭环。这也决定了它的效果上限仍然取决于模型能力和人写需求的水平，它不能把一个含糊的想法自动变成正确的产品，但它能保证含糊在最早的环节暴露，而不是混进代码里。

三、装上它，项目里多了什么

安装 specify 需要先有 uv，这是 Astral 出品的 Python 包管理器，Spec Kit 用它分发命令行工具。下面两条命令完成安装和项目初始化。

# 从 PyPI 安装 specify-cli，也可以从 GitHub 的 release tag 安装指定版本
uv tool install specify-cli

# 初始化项目，init 会交互式地让你选择使用哪个 AI 助手
specify init taskify
# 已经在项目目录里时可以用 specify init .
# CI 或 agent 流水线加上 --non-interactive，避免卡在选择界面

初始化时通过 --integration 参数可以直接指定助手，比如 --integration copilot，不指定则进入交互选择。初始化脚本提供 Bash、PowerShell 和 Python 三种变体，Windows、macOS 和 Linux 都支持，交互模式下会让你选，非交互模式按操作系统默认。这一点对 Windows 用户比较友好，不需要额外装 WSL。

初始化完成后，项目里会多出两类东西。一类是 .specify/ 目录，存放模板、脚本、扩展和项目状态，另一类是对应 agent 的命令文件，比如 Copilot 或 Claude 的命令目录，里面是 /speckit.* 这组命令的提示词定义。之后每个特性还会在 specs/ 下得到一个独立目录，规格、方案、任务全部以 Markdown 形式落在里面，可以直接进 Git，走分支和评审。

这里有一个容易误解的设计，Spec Kit 用 .specify/feature.json 记录当前正在工作的特性目录，命令靠这个状态文件判断该操作哪份规格，而不是靠当前 Git 分支，所以即使项目不用 Git 也能跑完整流程。编号分支，比如 001-feature-name 这种，是可选的 git 扩展提供的能力，装上之后它会帮你按序号管理特性分支，但切换分支本身不会改变当前特性，改的还是状态文件。这个设计把规格管理和版本控制解耦了，对已经有代码库的项目很重要，后面讲存量接入时还会提到。

命令的具体写法随 agent 不同略有差异。多数工具里是 /speckit.specify 这种斜杠形式，Codex、ZCode 等以 skills 模式运行的工具用 $speckit-specify，Kimi 用 /skill:speckit-specify，Copilot CLI 则通过 /agents 选择对应 agent 或在提示词里直接调用。下文统一用斜杠形式举例，步骤在所有集成里是一样的。

四、九个命令，把一句话打磨成可交付实现

Spec Kit 的核心流程有九个命令，但不是每次都必须全跑。官方给了两条路径，小特性走短路径，specify、plan、tasks、implement、converge 五步即可，生产级特性走完整路径，在中间插入 clarify、checklist、analyze 三个质量门，再加上一次性的 constitution。这一节按完整路径讲，因为只有看清质量门的位置，才能理解它和一把梭哈生成代码的区别。

constitution → specify → clarify → plan → checklist
     → tasks → analyze → implement → converge

4.1 constitution，先立项目规矩

/speckit.constitution 用来建立项目的治理原则，每个项目只需要在开头跑一次，原则变化时再更新。它产出的 constitution 是后续所有阶段的评判依据，方案设计、任务拆解都会对照它检查。

/speckit.constitution Taskify 是一个安全优先的应用，
所有用户输入必须校验，采用微服务架构，代码必须有完整文档

这一步看似形式主义，实际作用是把团队里那些口口相传的约定固化成 agent 每次都会读到的上下文。没有它，"我们这里所有接口都要鉴权"这种约束只能靠你在每个 prompt 里重复，漏一次就破一次。

4.2 specify 和 clarify，把需求逼问到没有歧义

/speckit.specify 是整个流程的入口，输入是一段自然语言描述，只讲做什么和为什么，不讲技术栈。为了连贯地看完整条链路，下面沿用官方快速入门里的例子 Taskify，一个团队效率平台，后面的 plan 和 tasks 也都围绕同一个项目展开。

/speckit.specify 开发 Taskify，一个团队效率平台，
预置用户可以创建项目、分配任务、评论，并在看板列之间拖动任务，
列包括待办、进行中、评审中、完成。预置五个用户，
一个产品经理四个工程师，三个示例项目，第一期不做登录

这个命令会基于 spec 模板生成 spec.md，模板的结构值得细看，因为它决定了"规格"这个词在 Spec Kit 里到底意味着什么。它不是一段散文式的需求描述，而是一组有编号、可追踪的条目。用户故事按 P1、P2、P3 排优先级，每个故事必须能独立测试、独立部署，只实现 P1 也应该是一个能交付价值的 MVP。每个故事下面挂 Given/When/Then 格式的验收场景，还有专门的边界情况小节。功能需求编号为 FR-001、FR-002，成功标准编号为 SC-001 并且必须可度量，比如"用户能在两分钟内完成账号创建"，而不是"体验流畅"。关键实体单独列出属性和关系，假设条件也要显式写出来。

模板里有一个很能体现设计意图的写法。当需求描述缺少关键信息时，agent 被要求显式标注 [NEEDS CLARIFICATION: 认证方式未指定，邮箱密码、SSO 还是 OAuth]，而不是自己悄悄选一个。歧义被留在纸面上，而不是被埋进实现里。

/speckit.clarify 就是用来消灭这些标记的。它会针对规格中描述不充分的部分最多提出五个有针对性的问题，把你的回答合并回 spec.md，可以反复跑，每次聚焦一个领域。

/speckit.clarify 聚焦任务卡片行为，状态变更、评论权限和用户分配

先澄清再规划，避免在模糊的地基上做设计。如果后面的 analyze 又发现需求缺口，还可以退回来重跑这一步。这种允许回退的设计贯穿始终，流程不是单向瀑布，任何阶段发现问题都回到拥有该问题的那一步去修。

4.3 plan，把业务规格翻译成技术方案

规格稳定之后，/speckit.plan 负责回答怎么做。还是 Taskify 这个例子，技术栈、架构、约束都在这一步提供，它们被刻意排除在 specify 阶段之外，保证同一份业务规格可以搭配不同技术方案。

/speckit.plan 使用 .NET Aspire 加 Postgres，前端用 Blazor Server，
看板支持拖拽和实时更新，项目、任务和通知暴露 REST API

这一步不只产出一个 plan.md。围绕方案它还会生成一组设计文件，research.md 记录技术选型的调研和对比，比如 WebSocket 库之间的取舍，data-model.md 定义数据模型，contracts/ 目录下放 API 契约和事件定义，quickstart.md 沉淀关键的验证场景。每个技术决策都要求写明理由并能追溯到具体需求，这样规格变更时，受影响的技术决策是可以被定位的，而不是靠人回忆。

4.4 checklist 和 analyze，给自然语言做质量检查

代码有单元测试，规格没有，这是传统文档最大的质量盲区。Spec Kit 用两个命令补上这件事。/speckit.checklist 为当前特性生成一份定制化的质量清单，官方把它形容为"给需求写单元测试"，检查的是规格本身是否完整、清晰、一致，比如"每一列的拖拽规则是否都定义了"、"被分配任务的用户被删除时行为是什么"。清单是评审人拥有的文件，勾上 [x] 代表评审人确认这条需求质量达标，不代表实现完成，agent 在实现阶段会把勾选状态当作一道门，有未勾选项会先询问，不允许悄悄自我批准。

/speckit.analyze 则在任务拆完之后、动手实现之前运行，跨 spec.md、plan.md、tasks.md 做一致性和覆盖度分析，找出没有对应需求的任务、与规格矛盾的方案决策、仍然含糊的条目。它是只读的，只出报告不改文件，发现问题就回到对应的上游步骤修源头，修完重跑，直到报告干净。这两步把检查时机压到了代码生成之前，此时改一个 Markdown 条目和生成完再改三个代码文件，成本差一个数量级。

4.5 tasks 和 implement，按依赖顺序施工

/speckit.tasks 读取方案和设计文件，生成依赖有序的 tasks.md。任务的组织方式不是平铺的清单，而是分阶段，先是 Setup 阶段完成脚手架，再是 Foundational 阶段处理阻塞性的基础能力，然后每个用户故事对应一个阶段并按优先级排列，最后是 Polish 阶段处理横切关注点。可以并行的任务会标上 [P] 并给出安全的并行分组，测试任务默认放在所属用户故事的阶段内，不单独成段。

/speckit.implement 按 tasks.md 施工，尊重阶段顺序和并行标记。小特性可以一次跑完，大特性建议按阶段执行，避免一次塞爆 agent 的上下文。

/speckit.implement 只实现 Setup 和 Foundational 阶段，
项目脚手架和项目、任务数据模型及基础 CRUD，先不要做用户故事功能

每个阶段跑完先验证再继续，这和人写代码的节奏是一致的。另外，implement 之前会读 checklist 的勾选状态作为门，但它对清单文件只读，不会替你打勾，质量确认的权力始终留在人手里。

4.6 converge，让实现向规格收敛

最后一个命令 /speckit.converge 是整个闭环的关键。它对照规格、方案和任务检查代码库，确认没有遗漏。它的写入行为被限制得非常严格，只追加，绝不修改或删除代码，唯一可能的写操作是往 tasks.md 追加新任务。检查结果只有两种，没有缺口时输出 ✅ Converged，任务文件一个字节都不动，可以进入评审或开 PR。发现缺口时，它把缺口作为新任务追加到文件的收敛小节，然后你再跑一次 implement 补完，再跑 converge。每一轮发现的问题都会更少，循环直到报告收敛。

这个设计解决了 AI 编码里最让人不放心的问题，你怎么知道它真的做完了。答案不是相信它说"我完成了"，而是让一个独立的检查步骤拿规格逐条比对代码，缺什么补什么，直到比对通过。规格、方案、任务、代码由此形成一个有反馈的闭环，而不是一条生成完就结束的直线。

走完一遍之后，specs/ 目录里留下的是一整套可以进版本库、可以评审、可以在需求变化时修改后重新驱动生成的文件。代码不再是唯一的资产，规格才是，代码随时可以从规格重新表达出来。

五、这和"先写 PRD 再让 AI 写代码"有什么不同

读到这里可能会有一个疑问，这套东西听起来就是把传统的需求文档、设计文档、任务清单重新捡回来，只不过让 AI 来写。表面上确实如此，真正的区别在于这些文件的性质。

传统 PRD 写完之后只有人会看，没有任何工具会读着它去写代码或检查代码。项目一忙起来，代码改了文档没改，两边说的话很快就对不上了，而且对不上之后也没有任何东西能把它们拉回一致，只能靠开发者自觉更新文档。Spec Kit 产出的文件是给人和 agent 共同读的，格式里的编号、引用和阶段结构让后面的命令能直接读取前面步骤的产出，需求条目能追溯到任务，任务能对照到代码，converge 还能反向检查代码是否兑现了规格。文档不再是写完即弃的脚手架，而是持续参与生成循环的输入。

第二个区别是质量保证的位置。传统流程里评审发生在代码阶段，看到的是已经成型的实现，此时发现需求理解错误，返工代价很大。Spec Kit 把检查拆成 clarify、checklist、analyze 三道门，提前到规格和方案阶段，analyze 甚至是只读的纯分析。这时候一行代码都还没写，发现问题只需要改几行 Markdown，所以可以放心地多改几轮，把问题消灭在动代码之前。

第三个区别是并行探索的成本。同一份 spec.md 可以搭配不同的 plan 生成多套实现，分别优化性能、可维护性、用户体验或成本，这在官方文档里叫分支探索。传统模式下重做一版意味着重写代码，而在 SDD 里重做一版主要是换一份 plan 再生成，业务意图不需要重新表达。需求变更也走同样的路径，改的是规格源头，受影响的方案和任务由命令重新推导，而不是在代码库里全局搜索然后祈祷没有漏网之鱼。

还有一个容易被忽略的点是团队协作形态。规格是 Markdown 文件，天然可以走分支、评审、合并，产品经理改验收标准，架构师调整方案，都在同一套文件上协作，agent 负责把评审后的意图变成实现。官方甚至用 Spec Kit 开发 Spec Kit 自己，重要特性都要求贡献者走一遍这套命令，仓库里的评估工作流会用当前代码初始化 Copilot 再跑完整流程，自己做的工具自己先用。

六、扩展机制与适用边界

核心流程之外，Spec Kit 从 1.0 版本开始把扩展性做成了体系，理解这套机制有助于判断它能不能落进自己的团队。定制能力分四层，解决的问题各不相同。

扩展，英文 extension，用来增加核心流程没有的能力。官方内置了两个可选扩展值得单独说。bug 扩展给修 bug 这件事加上 assess、fix、test 三步，先评估问题、验证诊断，再动手修，最后测试，每个 bug 在 .specify/bugs/ 下有独立目录，避免 agent 看到报错就直接改代码。assess 扩展则面向想法评估，一个新功能要不要做，先经过 intake、research、define、shape、decide 五步，产出 go、needs-clarification 或 kill 的结论，判了 go 再移交给 specify。社区扩展已经有一百多个，Jira 集成、代码审查、V 模型测试追溯、架构合规守卫这类都能找到。

预设，英文 preset，不增加能力，只改变工作方式，覆盖核心和扩展的模板与命令。比如把规格模板改成带监管追溯字段的合规格式，强制方案里包含安全审查关卡，或者把整套术语本地化成另一种语言。多个预设可以按优先级叠加。再往上是 workflow，把多个命令、shell 步骤和人工检查点编排成可重复的流程，支持条件、循环、扇出扇入和断点续跑。bundle 则面向团队角色，把一组扩展、预设和 workflow 锁定版本打包，产品经理或安全研究员需要的整套配置一条命令装好。模板在运行时按项目本地覆盖、预设、扩展、核心默认的优先级解析，所以任何一层都可以被团队自己的约定替换，甚至连 SDD 流程本身都能整个换掉，社区里已经出现了 AIDE、Canon、Product Forge 等替代流程，最极端的例子是一个用 Spec Kit 写长篇小说的预设。

对企业环境，它支持离线运行，可以部署在防火墙后面，甚至是完全不连外网的物理隔离内网，扩展目录也可以自建自托管，团队只暴露经过审查的集成和扩展。这解释了为什么它不只是个人玩具。

边界同样要说清楚。第一，它高度依赖模型能力，规格解读、方案生成、一致性分析都是模型在做，弱模型跑这套流程只会得到形式完整但内容空洞的文件，工具本身不提供智能。第二，不是所有改动都值得走全套流程，官方明确说小修复可以走普通的 issue、PR、评审流程，短路径的存在也是这个原因，给一个按钮改个文案跑九步纯属负担。第三，规格的质量仍然取决于人，模板能写出结构化的需求，但写不出正确的产品判断，NEEDS CLARIFICATION 标出来之后，回答问题的还是你。第四，已有代码库的项目接入要有节奏，官方的存量接入指南建议把工具升级和规格文件演进分开，先让新特性走流程，不要试图给遗留代码补全套规格，那会是一场灾难。最后，converge 的检查本质上还是模型对照文本做判断，它能显著降低遗漏，但不能替代真正的测试和评审，quickstart 里生成的验证场景需要你落成自动化测试才有长期价值。

七、专栏预告

工具的文档读完和在真实项目里用顺，中间隔着大量具体的坑。接下来的专栏《从 Prompt 到可执行规格：Spec Kit 实战》会带着一个真实项目从头走一遍，把文档里没展开的细节和实际使用中的判断摊开来讲。

专栏分四个篇章。第一篇章"为什么需要规格驱动"先把认知问题讲透，AI 会写代码之后项目为什么仍然失控，Spec Kit 在其中扮演什么角色，以及 specification 和传统 PRD 到底差在哪。本文作为前导已经触及了这一篇章的核心问题，专栏里会结合真实案例展开得更细。

第二篇章"跑通核心工作流"是专栏的主体，按顺序走完整条链路。从用 constitution 给 AI 编程立法开始，然后是写出真正可执行的 feature spec，用 clarify 拦住 AI 偷偷替你做的产品决定，再从 what 走到 how 生成技术计划，把方案切成可交付的任务切片，在写代码前用 analyze 发现规格、方案、任务三份文档互相打架的地方，最后用 implement 和 converge 让代码真正向规格收敛。重点不是复述命令，而是看每一步真实产出的文件长什么样，哪些地方会卡住，判断失误时怎么退回来。

第三篇章"用于真实工程，而非 Demo"回答工具怎么进得了生产环境，如何把 Spec Kit 接入已有代码库，规格写完之后要不要一直维护、怎么维护，monorepo 和多人协作下任务怎么和 GitHub Issues 对齐。第四篇章"定制与方法论反思"则往回收一层，extension、preset、bundle 分别解决什么问题、该怎么选，什么项目根本不值得跑完整流程，以及工具落地之后团队的协作和治理会发生什么变化。

八、总结

这篇文章解决的是一个认识问题。直接让 prompt 变成代码，省掉的不是文档，而是意图被审查和固化的机会，由此带来的需求漂移、不可复现和验收缺失，会在项目变大之后连本带利地还回来。Spec Kit 的做法是用 specify 命令行和九个 agent 命令，把自然语言意图经过立规矩、写规格、做澄清、定方案、列清单、拆任务、一致性分析、实现和收敛检查，变成一套可版本化、可复现、可再生成的 Markdown 文件，让规格而不是代码成为事实来源。它不替代模型，也不替代人的判断，它提供的是顺序、护栏和闭环。

下一步就是动手。建议你先找一个真实的小需求，用短路径完整跑一次 specify、plan、tasks、implement、converge，感受一下 converge 报告里第一次出现缺口时的那种踏实感。想系统跟着真实项目走完全程，可以从专栏第一篇章"为什么需要规格驱动"进入，再随第二篇章一步步跑通核心工作流。