GitHub Spec Kit：把 AI 编程从“直接生成代码”变成可执行的规格驱动流程

当你让 AI 编程代理开发一个“小型需求管理工具”时，最初的需求可能只是“支持新增、编辑和筛选任务”。但开发过程中，需求很容易变成“增加标签、支持离线、允许多人协作、保留历史记录”。如果每次都直接把新想法发给聊天机器人，代理往往会修改已有代码、引入新的假设，最后留下大量需要人工返工的实现。

GitHub Spec Kit 试图解决的，正是这种“代码生成速度很快，但需求和实现逐渐失控”的问题。它把 AI 编程从一次性生成代码，转变为先定义规格，再制定技术方案、拆分任务，最后逐项实现和验证的流程。

GitHub Spec Kit 是什么

GitHub Spec Kit 是一个开源的规格驱动开发工具包，目标是让开发者在使用 AI 编程代理时，先明确“要构建什么、为什么构建”，再进入技术实现阶段。项目本身提供 Python CLI，并通过项目目录中的规格、计划和任务文件，保存开发过程中的关键决策。

它并不是一个新的大语言模型，也不是只能配合某个 IDE 使用的代码补全插件。更准确地说，Spec Kit 是一层工作流和项目约束：

• 用自然语言描述需求和用户目标；
• 将需求整理成可检查的规格；
• 根据选定的技术栈生成实现计划；
• 把计划拆成有依赖关系的开发任务；
• 让 AI 编程代理逐项完成实现；
• 由开发者在规格、计划、代码和测试之间进行复查。

项目仓库强调了对多种 AI 编程代理的支持，相关资料提到可配合 30 多种代理使用。不过，具体支持范围会随版本、代理配置方式和社区集成变化，不能简单理解为所有代理都具备完全相同的能力。

官方仓库：

<https://github.com/github/spec-kit/>

它和直接向聊天机器人提问有什么区别

直接提问的方式并没有错。对于一个很小、边界清晰的任务，例如“为这个函数补一个单元测试”，直接让代理修改代码通常更快。

问题出现在需求具有以下特征时：

• 需求会持续变化；
• 需要多人协作；
• 涉及多个模块或数据模型；
• 需要保留决策过程；
• 不能接受代理自行猜测关键业务规则；
• 代码需要分阶段交付和复查。

直接对话通常以当前上下文为中心。你可以要求代理“增加标签功能”，但代理可能不知道：

• 标签是否允许重名；
• 删除标签后，历史任务如何处理；
• 离线状态下是否可以创建标签；
• API、数据库和前端是否需要同时调整；
• 旧数据是否需要迁移；
• 哪些行为必须通过测试固定下来。

Spec Kit 的差异，是把这些问题从聊天上下文中提取出来，放入可以提交到 Git 的项目文档中。后续代理不只是读取上一轮对话，而是读取项目中的规格、约束和任务清单。

这种方式不能保证 AI 一定写出正确代码，但能让错误更早暴露。你可以先审查需求，再审查计划，最后审查实现，而不是等代理生成数千行代码后才发现方向错了。

从规格到代码的基本流程

Spec Kit 的核心流程可以理解为四个阶段：规格、计划、任务和实施。实际命令名称可能因版本和 AI 编程代理而不同，下面使用资料中常见的命令形式说明。

1. 先描述“做什么”和“为什么做”

通常从 speckit.specify 开始。这个阶段重点不是决定使用哪一个框架，而是描述用户需要什么，以及什么结果才算完成。

例如，不要只写：

增加一个任务筛选页面。

可以写成：

用户可以按照状态、标签和创建时间筛选任务。筛选条件刷新页面后仍然保留；没有匹配结果时显示空状态；筛选操作不应修改任务数据。

一份更有用的规格，通常至少包含：

• 用户或使用者是谁；
• 要解决的具体问题；
• 主要使用场景；
• 输入、输出和状态变化；
• 正常路径；
• 异常路径；
• 验收标准；
• 明确不包含的内容。

这一步的价值，在于把模糊的“做一个功能”变成可以讨论和验证的行为描述。

如果规格中出现“应该更快”“操作要简单”之类的表述，还需要继续追问。它们可以作为方向，但不能直接作为可执行的验收标准。

2. 审查并修改规格

不要把 AI 生成的规格直接当成最终需求。规格阶段的人工审查，通常比代码阶段发现问题更便宜。

可以重点检查：

• AI 是否擅自增加了没有提出的功能；
• 需求之间是否互相矛盾；
• 边界条件是否足够明确；
• 验收标准是否可以通过测试验证；
• 是否遗漏了权限、数据迁移或错误处理；
• 是否把技术方案误写成了产品需求。

如果项目有长期约束，可以将团队约定、代码质量要求或架构原则放入项目记忆文件中。这样，后续生成计划和任务时，代理可以参考这些约束，而不是每次从零猜测。

3. 根据技术栈生成实现计划

确认规格后，再使用 speckit.plan 生成技术实现计划。

这一阶段才适合讨论：

• 使用哪种语言和框架；
• 数据模型如何变化；
• API 如何设计；
• 前端和后端如何分工；
• 是否需要数据库迁移；
• 如何兼容已有数据；
• 测试放在哪个层次；
• 哪些内容可以并行开发。

这和一开始就告诉 AI“请用某框架写出来”不同。技术栈仍然重要，但它不应该掩盖需求本身。

计划生成后，开发者需要检查它是否真的落实了规格。例如，规格要求“刷新页面后保留筛选条件”，计划中就应该出现状态持久化、URL 参数或其他明确方案，而不是只写“完成筛选页面”。

4. 把计划拆成可执行任务

接下来使用 speckit.tasks 将计划拆成任务清单。

好的任务应该具备以下特点：

• 范围足够小，完成后容易检查；
• 能指出涉及的文件或模块；
• 有清晰的完成条件；
• 标明前置依赖；
• 不把多个无关问题混成一个任务；
• 可以对应到规格中的一个或多个验收标准。

例如，“完成标签功能”过于宽泛，可以拆成：

1. 增加标签数据模型和数据库迁移；
2. 增加标签创建和删除接口；
3. 增加任务与标签的关联操作；
4. 增加按标签筛选的查询逻辑；
5. 增加接口层测试；
6. 增加前端筛选状态和空结果展示；
7. 运行全量测试并检查旧数据兼容性。

拆分之后，AI 代理不必一次性理解整个项目。它可以按照依赖顺序逐项工作，开发者也能更快定位某个任务引入的问题。

5. 逐项实施并验证

最后进入实现阶段。代理可以根据任务清单完成代码修改，但开发者仍需要控制节奏。

比较稳妥的做法是：

1. 先让代理读取规格、计划和任务；
2. 一次处理一个较小任务或一组强相关任务；
3. 查看代码差异；
4. 运行对应测试；
5. 检查任务是否真正满足验收标准；
6. 再进入下一个任务。

GitHub 对这一工作方式的介绍强调，开发者审查的是聚焦于具体问题的变更，而不是一次性审查大量代码。这也是规格驱动流程相较于“直接生成整个项目”的实际优势。

Python CLI 的基本使用方式

Spec Kit 提供 Python CLI，用于初始化项目、生成工作流文件以及检查本地环境。由于命令参数和代理集成会随版本变化，安装前应以官方仓库当前文档和 --help 输出为准。

一种常见的安装方式是使用 uv：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

安装后，可以先确认 CLI 是否可用：

specify --help
specify check

specify check 这类检查命令的目的，是确认本地 CLI、Git 和相关代理集成是否处于可用状态。不同代理可能还需要额外安装自己的命令行工具、登录账号或配置 API 访问权限。

在一个新目录中初始化项目时，可以使用类似下面的形式：

mkdir task-board
cd task-board

specify init . --ai <你的代理名称>

<你的代理名称> 需要替换为实际支持的 AI 编程代理标识。不要直接照抄某个旧版本教程中的名称；如果不确定，可以先查看：

specify init --help

初始化后，项目中通常会出现 Spec Kit 使用的工作目录、模板或代理指令文件。它们的作用不是替代源代码，而是让规格、计划、任务和项目约束成为仓库的一部分。

如果是已有项目，初始化前应先确认：

• 当前目录已经是正确的 Git 仓库；
• 工作区中没有未提交的重要修改；
• 初始化操作不会覆盖已有配置；
• 团队是否同意把规格文件提交到版本库；
• 代理是否能访问必要的源代码和测试文件。

一个小型项目实践

假设要为个人使用的任务看板增加“离线快速记录”功能。最初的描述可能只有一句话：

没有网络时也能新增任务，恢复网络后自动同步。

这句话看似清楚，实际上包含许多未决问题：

• 离线任务保存在哪里；
• 临时 ID 如何生成；
• 用户是否可以在同步前编辑任务；
• 同一任务重复提交时如何去重；
• 服务端和本地同时修改时如何处理；
• 同步失败后是否自动重试；
• 用户是否能看到同步状态。

使用规格驱动流程时，可以先把范围收窄。例如，第一版只支持“离线新增”，不处理复杂的双向冲突：

用户在没有网络时可以创建任务。
任务先保存在本地。
网络恢复后，客户端按创建顺序提交未同步任务。
服务端成功接收后，本地任务标记为已同步。
提交失败时保留任务，并显示待同步状态。
本版本不处理同一任务在多个设备上的并发修改。

这份规格比“支持离线同步”更适合让 AI 继续工作，因为它明确了第一版的边界。

接着，计划可以进一步说明：

• 本地使用现有存储机制，不引入新的数据库；
• 为任务增加本地同步状态；
• 网络请求失败时不删除本地记录；
• 启动应用和网络状态恢复时触发同步；
• 为重复提交设计稳定的客户端标识；
• 增加离线创建、恢复同步和同步失败测试。

最后，任务清单可以拆成：

1. 为任务结构增加本地同步状态；
2. 实现离线创建路径；
3. 实现待同步任务查询；
4. 实现同步接口调用；
5. 处理成功、失败和重复提交；
6. 增加状态提示；
7. 增加相关测试；
8. 运行现有测试并检查旧任务兼容性。

此时，AI 代理的工作范围就不再是“自由发挥地实现离线同步”，而是根据一组已经讨论过的约束逐项修改代码。

与多种 AI 编程代理配合时要注意什么

Spec Kit 的一个重要卖点是代理兼容性。它不是把所有能力绑定在单一模型上，而是通过项目文件、提示词模板和工作流命令，让不同的 AI 编程代理参与相似的规格驱动流程。

但“支持某个代理”不等于“所有体验完全一致”。实际差异可能来自：

• 代理是否能读写本地文件；
• 是否支持项目级指令文件；
• 是否能运行终端命令；
• 是否会自动执行测试；
• 是否支持多轮任务状态；
• 使用的是云端模型还是本地模型；
• 代理对上下文长度和代码仓库规模的限制。

因此，迁移代理时，优先检查三件事：

1. 代理是否能读取规格、计划和任务文件；
2. 代理是否有权限修改代码并运行测试；
3. 代理是否理解当前项目的指令和约束文件。

如果代理不支持某个斜杠命令，也不代表整个流程无法使用。可以把规格、计划和任务文件直接提供给代理，让它按照文件内容执行。命令是工作流入口，真正重要的是这些可审查的项目文档。

规格驱动流程的优势

更早发现需求错误

直接生成代码时，需求错误往往要等到页面、接口和数据库都改完后才会暴露。先审查规格，可以在实现之前发现遗漏和矛盾。

降低上下文依赖

聊天记录会被截断、切换代理后也不容易完整保留。规格和任务文件进入 Git 后，新的对话可以从项目状态继续，而不必依赖某一次聊天中的隐含信息。

适合团队协作

团队成员可以分别审查规格、技术计划和代码变更。产品人员关注行为和边界，开发者关注架构和实现，测试人员关注验收标准，讨论对象更明确。

便于遗留代码改造

在遗留项目中，直接让 AI“重构这个模块”风险很高。可以先要求代理梳理现有行为，再编写改造规格和兼容性要求，随后拆分成较小任务。这样更容易保留已有行为，也方便每一步回滚。

让代码审查更聚焦

任务清单如果拆分合理，每次代码变更都会有对应的目标。审查者可以问“这个改动是否满足任务和验收标准”，而不是笼统地判断“这段 AI 生成的代码看起来是否合理”。

它的限制和使用成本

Spec Kit 并不会自动消除 AI 编程的主要风险。

写规格本身需要时间

如果需求变化频繁，规格文件也需要维护。一个过于详细、但很快过时的规格，可能反而增加负担。

更实际的做法是区分稳定约束和临时想法：

• 产品目标、数据约束和安全要求可以长期保留；
• 实验性功能只记录当前版本需要的范围；
• 需求改变后，同时更新规格、计划和任务；
• 不要为了形式完整而描述与当前目标无关的内容。

代理仍然可能误解规格

自然语言规格不是形式化证明。AI 可能忽略一个边界条件，也可能在实现时采用与计划不同的方案。因此，规格、代码和测试之间仍然需要人工核对。

代理兼容性并不等于无配置

不同代理的命令、权限、登录方式和项目指令支持各不相同。初始化成功后，还需要用一个很小的任务验证：代理能否读取文件、修改代码、执行测试并返回清晰的结果。

生成结果必须人工验证

至少应检查：

• 代码差异是否只涉及当前任务；
• 是否破坏已有接口；
• 是否引入不必要的依赖；
• 测试是否覆盖真实验收标准；
• 错误处理是否符合规格；
• 数据迁移和旧版本兼容性是否安全；
• 代理是否修改了不应修改的配置或安全设置。

测试通过也不代表需求一定正确。测试本身可能遗漏了问题，或者只验证了实现细节而没有验证用户行为。

常见排错思路

初始化命令失败

先运行：

specify --help
specify init --help

然后确认：

• Python 和 CLI 是否来自预期环境；
• uv 是否安装并能正常运行；
• 当前目录是否有写入权限；
• Git 是否可用；
• 使用的代理标识是否属于当前版本支持范围。

如果是通过 Git 地址安装，网络、代理或仓库访问权限也可能导致安装失败。

代理找不到规格文件

检查初始化是否在正确的项目根目录执行，并确认规格文件确实已经写入 Git 工作区。对于已有项目，尤其要避免在子目录中初始化后，又从仓库根目录启动代理。

还应检查代理的项目级指令文件是否被正确加载。有些代理只会自动读取特定文件名，不能假设所有代理都能识别同样的配置。

代理跳过计划直接改代码

这通常是工作方式没有被明确约束，或者当前任务描述过于宽泛。可以要求代理先输出：

1. 对规格的理解；
2. 将要修改的文件；
3. 实现步骤；
4. 测试方案。

确认后再允许它执行修改。对于重要项目，不要让代理在一次请求中同时生成规格、计划、代码和测试。

测试通过但功能仍然不对

回到规格检查验收标准，而不是只看测试数量。重点确认测试是否覆盖：

• 空数据；
• 错误输入；
• 权限边界；
• 网络失败；
• 重复操作；
• 旧数据；
• 状态恢复；
• 用户真正看到的结果。

如果验收标准本身写得过于模糊，应先修改规格，再要求代理补充实现或测试。

适合哪些人使用

Spec Kit 更适合以下场景：

• AI 生成代码已经多次返工；
• 需求会持续变化，但又需要保留决策过程；
• 个人项目逐渐变大，开始出现模块和版本管理问题；
• 团队希望统一 AI 编程的协作方式；
• 需要改造遗留代码，又不想让代理一次性重写；
• 项目需要较明确的验收标准和审查节点。

如果只是修改一个函数、生成一段脚本，或者验证一个很小的技术想法，完整的规格流程可能显得过重。此时可以只借鉴其中的部分方法，例如先写几条验收标准，再让代理实现。

是否值得采用

GitHub Spec Kit 的价值不在于让 AI 生成更多代码，而在于让开发者更早、更具体地约束 AI 要解决的问题。它把需求、架构、任务和验证连接起来，降低了“代理看似完成了功能，但实际上偏离目标”的概率。

对于个人项目，可以从一个小功能开始，不必一开始就为整个仓库建立复杂流程。对于团队项目，应先约定规格文件的维护方式、审查责任和任务拆分粒度。对于遗留代码，则应优先用它记录现有行为和改造边界，而不是直接让代理重写模块。

搜索资料中提到，Spec Kit 的 v0.8.7 于 2026 年 5 月发布，并支持 30 多种 AI 编程代理；这类版本和兼容性信息会持续变化，实际安装时应以 GitHub 仓库 的当前文档、发行记录和 CLI 帮助为准。无论使用哪个版本，最重要的边界都没有改变：规格不能代替产品判断，计划不能代替架构审查，测试也不能代替人工验证。它真正提供的是一套让 AI 编程过程更容易复查和协作的结构。