GitHub Spec-Kit 实战：用规范驱动让 AI 编码从碰运气变可复现

1. 从“氛围编程”到规范驱动：AI编码正在经历什么

“氛围编程”这个词最近半年在开发者圈子里被反复提起，说的是一种很典型的状态：你打开AI编码助手，用自然语言描述一个需求，AI噼里啪啦生成一大段代码，你看了一眼觉得“差不多是那个意思”，复制粘贴进去，跑一下，报错，再让AI改，再跑，再改。整个过程靠的是一种“感觉”——感觉AI理解了我的意图，感觉这段代码应该能跑，感觉改完这次应该没问题。

这种工作方式在快速原型阶段确实爽，但一旦项目进入多人协作、长期维护、需求频繁变更的阶段，问题就暴露得非常彻底。AI生成的代码风格不统一、命名随意、边界条件处理缺失、测试覆盖为零，更致命的是——你根本不知道AI为什么这么写，下次换个对话窗口，同样的需求它可能给你完全不同的实现。

GitHub Spec-Kit 就是冲着这个问题来的。它做的事情说起来很简单：在AI编码之前，先让AI帮你把“规范”写出来，然后让AI严格按照这份规范去生成代码。听起来像是多了一步，但实际用下来，这一步恰恰是把AI编码从“碰运气”变成“可复现”的关键。

这篇文章我会从实际使用的角度，把Spec-Kit的工作机制、安装配置、核心命令、实战流程、常见坑点全部拆开讲一遍。不管你是刚接触AI编码的新手，还是已经在项目里重度使用AI助手的老手，应该都能从中找到可以直接抄作业的东西。

2. Spec-Kit到底解决了什么问题：AI编码的四个结构性缺陷

2.1 缺陷一：需求理解的“黑箱化”

你用自然语言跟AI说“帮我写一个用户登录接口”，AI会给你生成一段代码。但这段代码背后隐含了无数个决策：用什么框架？密码怎么加密？token怎么生成？错误码怎么定义？这些决策AI替你做了，但你不知道它为什么这么选。

Spec-Kit的做法是强制把这些决策显性化。它要求你先写一份spec（规范文档），里面明确列出功能需求、技术约束、验收标准。这份spec不是给人类看的文档，而是给AI看的“合同”——AI必须按照合同办事，不能自由发挥。

2.2 缺陷二：代码风格的“随机漂移”

同一个项目里，今天让AI写一个service，它用class；明天让AI写另一个service，它用function。今天用camelCase，明天用snake_case。这种漂移在单人项目里还能忍，在多人协作里就是灾难。

Spec-Kit通过constitution（宪法）机制来解决这个问题。你可以在项目根目录放一份constitution文件，里面定义代码风格、命名规范、目录结构、技术栈选型等硬性约束。每次AI生成代码前都会先读这份宪法，确保输出符合项目统一标准。

2.3 缺陷三：任务拆解的“随意性”

直接让AI写一个大功能，它往往会给你一个巨大的、难以review的代码块。Spec-Kit引入了plan（计划）和tasks（任务列表）两个中间层。plan负责把spec拆解成技术方案，tasks负责把技术方案拆解成可执行的小任务。每个任务都是独立的、可验证的、粒度足够小的。

这样做的好处是：你可以逐个任务review AI的输出，发现问题及时纠正，而不是等到整个功能写完才发现方向错了。

2.4 缺陷四：验证环节的“缺失”

“氛围编程”最大的问题是：AI说写完了，你就信了。Spec-Kit在流程里强制加入了验证环节。每个任务完成后，AI需要自己跑测试、检查验收标准、确认没有偏离spec。如果验证不通过，它会自动回到上一个环节重新调整。

这四个缺陷对应的是Spec-Kit的四个核心概念：spec（规范）、constitution（宪法）、plan（计划）、tasks（任务）。理解这四个概念，就理解了Spec-Kit的全部设计哲学。

3. 安装与初始化：把Spec-Kit接进你的工作流

3.1 环境准备与安装方式选择

Spec-Kit本质上是一个CLI工具，通过它你可以初始化项目结构、生成规范模板、驱动AI按流程工作。安装方式有几种，我推荐用uv或者pipx来装，避免污染全局Python环境。

# 方式一：用uv安装（推荐，速度快） uv tool install specify-cli --from git+https://github.com/github/spec-kit.git # 方式二：用pipx安装 pipx install git+https://github.com/github/spec-kit.git # 方式三：直接用pip（不推荐，但能用） pip install git+https://github.com/github/spec-kit.git

装完之后验证一下：

specify --version

如果能看到版本号输出，说明安装成功。这里有个小坑：如果你之前装过旧版本，建议先卸载再重装，因为Spec-Kit的模板结构在早期版本里变动比较大。

3.2 初始化项目：specify init做了什么

进入你的项目目录，执行：

specify init .

这个命令会在当前目录下创建一套Spec-Kit的标准结构。核心目录包括：

• .specify/：存放模板、脚本、配置
• specs/：存放每个功能的规范文档
• memory/：存放constitution等长期约束

初始化完成后，你会看到.specify/templates/下面有几个关键模板文件：

这些模板不是摆设，它们是AI生成内容时的“骨架”。你填得越细，AI输出越可控。

3.3 选择AI助手：不同工具的适配差异

Spec-Kit本身不绑定特定的AI编码工具，它通过生成结构化的prompt来驱动AI工作。目前适配比较好的有Claude Code、GitHub Copilot、Cursor等。

我实测下来，Claude Code对Spec-Kit的流程支持最完整，因为它可以直接读取项目文件、执行命令、修改代码。Copilot在IDE里的体验更顺滑，但对多文件操作的支持稍弱。Cursor介于两者之间。

不管你用哪个工具，核心逻辑是一样的：Spec-Kit生成结构化的指令文件，你把这些文件喂给AI，AI按照指令执行。

4. 核心工作流拆解：spec、plan、tasks、implement四步走

4.1 第一步：写spec——把“我想要”变成“必须满足”

Spec-Kit的工作流从/specify命令开始。在AI助手的对话窗口里输入：

/specify 用户登录功能，支持邮箱密码登录，需要JWT token，密码用bcrypt加密

AI会基于这个描述，结合spec-template.md，生成一份完整的规范文档。这份文档通常包含：

• 功能描述：这个功能是干什么的
• 用户故事：谁在什么场景下使用
• 验收标准：怎么算做完了
• 边界条件：异常情况怎么处理
• 非功能性需求：性能、安全、兼容性要求

这里的关键是：不要跳过验收标准。很多人写spec的时候只写“用户能登录”，但“能登录”是个模糊概念。Spec-Kit会逼你写清楚：登录成功返回什么？失败返回什么？token过期怎么处理？密码错误几次锁定？

我自己的习惯是，在spec阶段就把所有能想到的异常场景列出来。比如：

## 验收标准 - [ ] 正确邮箱密码登录，返回200和JWT token - [ ] 错误密码登录，返回401和错误信息 - [ ] 不存在的邮箱登录，返回401（不暴露邮箱是否存在） - [ ] 连续5次密码错误，账号锁定15分钟 - [ ] token有效期24小时，过期后返回401

这些验收标准后面会直接变成测试用例，AI在implement阶段会逐条验证。

4.2 第二步：写plan——技术方案不能由AI拍脑袋

spec写完之后，执行：

/plan

AI会读取spec，结合constitution里的技术约束，生成一份技术方案。这份方案会明确：

• 用什么语言、框架、库
• 数据库表结构怎么设计
• API接口怎么定义
• 目录结构怎么组织
• 关键算法或逻辑怎么实现

这一步的价值在于：把技术决策从AI的“默认偏好”变成你的“主动选择”。如果你不写plan，AI会自己选一个它觉得合适的方案。但AI的选择未必符合你的项目现状。

举个例子：你的项目已经在用PostgreSQL，但AI可能给你生成MySQL的建表语句。你的项目用FastAPI，但AI可能给你生成Flask的代码。plan阶段就是纠正这些偏差的地方。

我通常会在plan阶段做几件事：

1. 检查AI选的技术栈是否和现有项目一致
2. 检查数据库设计是否合理（索引、外键、字段类型）
3. 检查API设计是否符合RESTful规范
4. 检查是否有安全漏洞（SQL注入、XSS、CSRF）

如果发现问题，直接改plan文档，然后让AI重新生成。

4.3 第三步：写tasks——把大功能拆成可验证的小任务

plan确认后，执行：

/tasks

AI会把技术方案拆解成一个个独立的任务。每个任务都有明确的输入、输出、验收标准。典型的tasks列表长这样：

## 任务列表 1. [ ] 创建User模型和数据库迁移 2. [ ] 实现密码加密工具函数 3. [ ] 实现JWT token生成和验证工具 4. [ ] 实现登录API接口 5. [ ] 实现登录失败次数限制逻辑 6. [ ] 编写单元测试 7. [ ] 编写集成测试

每个任务都是可以独立完成和验证的。你可以让AI逐个任务执行，每完成一个就review一次。这样做的好处是：问题暴露得早，修复成本低。

4.4 第四步：implement——AI按任务执行，你按标准验收

任务列表确认后，执行：

/implement

AI会按照tasks列表逐个执行。每完成一个任务，它会：

1. 生成代码
2. 运行测试
3. 检查验收标准
4. 如果通过，标记任务完成
5. 如果不通过，自动修复或请求你介入

这个阶段你不需要盯着AI写每一行代码，但你需要定期检查AI的输出是否符合预期。我的习惯是每完成2-3个任务就review一次，避免AI在错误的方向上越走越远。

5. constitution机制：给AI立规矩的正确姿势

5.1 constitution应该写什么

constitution是Spec-Kit里最容易被忽视但最重要的部分。它相当于项目的“宪法”，定义了AI必须遵守的硬性约束。一份好的constitution应该包含：

# 项目宪法 ## 技术栈 - 语言：Python 3.11+ - 框架：FastAPI - 数据库：PostgreSQL 15 - ORM：SQLAlchemy 2.0 - 测试：pytest ## 代码风格 - 遵循PEP 8 - 函数和变量用snake_case - 类名用PascalCase - 常量用UPPER_CASE - 每个函数必须有docstring ## 目录结构 - src/ 存放源代码 - tests/ 存放测试 - migrations/ 存放数据库迁移 - docs/ 存放文档 ## 安全约束 - 密码必须用bcrypt加密 - 所有API必须验证JWT token - 禁止在代码里硬编码密钥 - 所有数据库查询必须参数化 ## 禁止事项 - 禁止使用eval() - 禁止使用pickle反序列化用户输入 - 禁止在日志里输出密码和token

5.2 constitution的执行力度

Spec-Kit会在每次生成代码前读取constitution，并在prompt里明确要求AI遵守。但AI不是100%可靠的，有时候它还是会“忘记”某些约束。所以你需要定期检查AI的输出，发现违规就手动纠正，并把违规案例补充到constitution里。

我自己的经验是：constitution不是一次写完就完事的，它应该随着项目发展不断迭代。每次发现AI犯了新错误，就把对应的约束加进去。慢慢地，AI的输出会越来越符合项目规范。

5.3 一个容易被忽略的细节：constitution的粒度

constitution写得太粗，AI会自由发挥；写得太细，又会限制AI的创造力。我的建议是：只约束那些“必须统一”的东西，其他交给AI判断。

比如：

• 必须统一：命名规范、目录结构、安全约束、技术栈
• 可以灵活：具体算法实现、变量命名细节、注释风格

这样既保证了项目一致性，又不会让AI变成只会照本宣科的机器。

6. 实战踩坑记录：我在Spec-Kit上遇到的五个真实问题

6.1 坑一：spec写得太模糊，AI输出完全跑偏

第一次用Spec-Kit的时候，我写了一个spec：“实现一个文件上传功能”。结果AI给我生成了一个支持多文件、断点续传、分片上传、云存储的完整方案。代码量巨大，依赖一堆我没用过的库。

问题出在spec太模糊。AI不知道我的实际需求是什么，只能按“最完整”的方案来生成。后来我改成：“实现单文件上传，最大10MB，存储到本地磁盘，返回文件URL”，AI的输出就精准多了。

教训：spec要具体到让AI没有发挥空间。

6.2 坑二：plan阶段没检查，implement阶段返工

有一次plan阶段AI选了Redis来做session存储，但我项目里根本没装Redis。我没仔细看plan就直接implement，结果AI生成的代码依赖Redis，跑不起来。回头改plan，重新生成tasks，重新implement，浪费了大半天。

教训：plan阶段必须逐行检查，确认技术选型和现有项目兼容。

6.3 坑三：tasks粒度太粗，review困难

AI默认生成的tasks有时候粒度很粗，比如“实现用户模块”这种任务，AI会一次性生成几百行代码。review的时候根本看不过来，只能大概扫一眼，结果漏掉了几个边界条件没处理。

后来我学会手动拆分tasks，把“实现用户模块”拆成“创建User模型”“实现注册接口”“实现登录接口”“实现密码重置接口”等。每个任务代码量控制在100行以内，review起来轻松很多。

教训：tasks粒度控制在“一个任务不超过200行代码”比较合适。

6.4 坑四：constitution更新后，旧代码不兼容

项目进行到一半，我往constitution里加了一条“所有API必须返回统一格式的JSON响应”。结果新生成的代码符合这个约束，但旧代码还是老格式。导致前端调用不同接口要处理不同的响应结构。

教训：constitution变更要考虑存量代码的兼容性，要么统一重构，要么在constitution里注明“仅适用于新代码”。

6.5 坑五：AI在implement阶段“偷懒”

有时候AI在implement阶段会跳过某些任务，或者把多个任务合并成一个。比如tasks列表里有“编写单元测试”和“编写集成测试”两个任务，AI可能只写了一个测试文件就标记两个任务都完成了。

教训：implement阶段要定期检查任务完成情况，发现AI偷懒就手动纠正。

7. 把Spec-Kit用出效果的几个关键习惯

7.1 习惯一：spec阶段多花时间，后面省时间

很多人用Spec-Kit觉得麻烦，就是因为spec阶段要写很多东西。但我的经验是：spec阶段每多花10分钟，implement阶段能省1小时。因为spec写得越清楚，AI返工的概率越低。

我通常会在spec阶段做这几件事：

• 把所有验收标准列出来
• 把所有异常场景列出来
• 把所有边界条件列出来
• 把所有非功能性需求列出来

这些内容看起来多，但写起来其实很快，而且后面会直接变成测试用例。

7.2 习惯二：plan阶段做技术评审

plan阶段是技术决策的关键节点。我通常会在这个阶段做一次“技术评审”，检查：

• 技术选型是否和现有项目一致
• 数据库设计是否合理
• API设计是否符合规范
• 是否有安全隐患
• 是否有性能瓶颈

如果发现问题，直接改plan文档，然后重新生成tasks。

7.3 习惯三：tasks阶段手动调整粒度

AI生成的tasks粒度不一定合适。我通常会手动调整，确保每个任务：

• 代码量在200行以内
• 有明确的验收标准
• 可以独立测试
• 不依赖其他未完成的任务

7.4 习惯四：implement阶段分批review

不要等所有任务都完成才review。我通常每完成2-3个任务就review一次，发现问题及时纠正。这样AI不会在错误的方向上越走越远。

7.5 习惯五：持续迭代constitution

constitution不是一次写完就完事的。每次发现AI犯了新错误，就把对应的约束加进去。慢慢地，AI的输出会越来越符合项目规范。

8. 关于Spec-Kit的一些冷思考

Spec-Kit不是银弹。它解决的是AI编码的“可控性”问题，但代价是增加了前期的工作量。如果你的项目是一次性的、不需要维护的、单人使用的，那Spec-Kit可能反而拖慢你的速度。

但如果你在做的是一个长期项目、多人协作、需要持续迭代的产品，那Spec-Kit的价值就非常明显了。它让AI编码从“碰运气”变成“可复现”，从“个人艺术”变成“团队工程”。

我自己的体会是：Spec-Kit最大的价值不是让AI写出更好的代码，而是让AI写出更符合你预期的代码。它把AI的“自由发挥”限制在一个可控的范围内，让你对最终产出有更强的掌控感。

还有一个容易被忽略的点：Spec-Kit生成的spec、plan、tasks文档本身就是很好的项目文档。新人接手项目的时候，看这些文档就能快速理解功能需求和技术方案，比看代码快多了。

最后分享一个小技巧：如果你觉得Spec-Kit的完整流程太重，可以只取其中一部分。比如只用spec和plan，不用tasks和implement。或者只用constitution来约束AI的输出风格。Spec-Kit的各个模块是解耦的，你可以按需取用。

我在实际使用中，最常用的组合是“constitution + spec + plan”，tasks和implement只在复杂功能上才走完整流程。这样既保证了代码质量，又不会让流程变得太笨重。