Spec Kit工作流：用需求规格化解决AI编程中的需求漂移问题

先说结论AI 写代码的效率从来不是瓶颈需求漂移和变更记录才是。很多团队用 AI 编程后出现一个典型现象——单次生成速度极快验收时却发现实现内容和预期对不上改一轮等于重写一轮。返工多的原因不是模型不够强而是输入侧的规格不够明确变更链路没有留下记录。这次我们来看一个可以落地的思路Spec Kit 工作流。它把 AI 编程过程拆成三段——Specify需求规格化、Plan制定实施计划、Tasks拆解执行任务目标就是让每次需求变化都留痕让 AI 生成的东西可验收、可回滚、可追溯。这篇文章会完整拆解这套工作流并给出可以直接套用的文档模板、提示词结构和任务清单格式。1. 核心能力速览Spec Kit 不是某个大模型也不是传统意义的 IDE 插件而是一套面向 AI 编程的工作流规范和一组合集工具。它解决的核心问题是AI 生成代码之前先让需求变得可描述、可拆分、可检查。为了快速判断这套东西适不适合你先给出一张能力速览表能力项说明项目类型AI 编程工作流规范 / 提示词模板集 / 任务管理约定核心阶段Specify需求规格化、Plan实施计划、Tasks任务拆解输入依赖自然语言需求描述、变更请求、验收标准输出产物需求规格文档、分阶段计划、可执行任务清单、变更记录适用编程工具Claude Code、Cursor、GitHub Copilot、通义灵码等支持长上下文和任务拆解的 AI 编程工具硬件门槛无特殊 GPU 需求纯文本工作流普通开发机即可是否支持 API不强制依赖 API可配合 AI 编程工具或大模型 API 使用是否支持批量任务支持Tasks 阶段天然适合批量拆解和逐项验证上手成本低核心是规范习惯不强制安装特定软件适合场景AI 辅助开发、需求频繁变更的项目、多人协作的 AI 编程流程从表格能看到这套工作流最值钱的地方不是自动化而是把“改代码”这个动作前面加了“记录变更原因”的环节。它适合那些正在用 AI 写代码、但觉得 AI 生成结果不稳定、频繁返工的团队和个人开发者。2. 适用场景与使用边界Spec Kit 工作流适合以下几类人使用 AI 编程工具后发现“生成很快但方向总是跑偏”的开发者。需要把需求交付给 AI 执行但经常出现理解偏差的项目负责人。在多人协作中希望让 AI 生成的代码可审查、可回溯的技术团队。做原型验证、内部工具开发、需求迭代频繁的小团队。它能解决的问题也很明确需求描述过于模糊AI 只能靠猜。需求变更后后续生成的任务没有同步更新导致代码逻辑前后矛盾。每一轮生成的代码没有记录当时的背景和验收标准返工时找不到依据。任务拆分过粗AI 一次性产出大量不可控代码出错后难以定位。不适用或需要谨慎使用的场景包括项目本身非常简单、需求固定、不需要频繁变更的脚本任务用这套流程反而增加成本。团队已经有一套成熟的变更管理流程比如 Jira 代码评审 严格测试流程需要评估是否值得叠加新层。所有需求都要求 AI 全自动完成、不需要人工审查的场景Spec Kit 的“记录”和“验收”环节会被跳过失去意义。合规和安全方面也需要提醒这套工作流本身不涉及隐私收集但如果你的项目涉及用户数据、人脸、声音、版权素材或者要对接生产系统需求规格文档里必须写清楚数据来源、授权方式和处理边界。Spec 和 Tasks 只是流程层最终能不能上线仍要以合法合规为前提。3. AI 生成代码返工多的根因分析先把问题拆开AI 写代码快为什么返工多3.1 需求描述是“口语化”的不是“可执行”的很多人给 AI 的指令是“帮我写一个用户登录功能。”这句话在人类同事那里对方会追问登录方式是什么手机号还是邮箱需不需要验证码密码忘了怎么办但 AI 不会主动追问它会选择一个“平均理解”来生成。Spec Kit 的第一步 Specify就是要解决这个差距把口语化描述转成结构化、可验收的需求规格。3.2 上下文窗口有限旧决策被新会话覆盖AI 编程工具虽然有长上下文但每次新会话、每次文件修改后历史决策会逐渐被稀释。第一轮设定好的技术方案到第三轮生成时可能已经被遗忘或改变。Plan 阶段的作用就是把技术方案固化成文档让每一轮新会话都从同一份 Plan 读取约束。3.3 需求变更没有记录代码却已经叠加最常见的返工场景是需求方说“这里改一下”开发者在 AI 工具里直接改改完后发现另一个功能受影响再让 AI 修修完又引入新问题。整个过程没有变更记录没有人知道代码为什么最终变成这个样子。Tasks 阶段如果每次都带编号和状态变更时不是直接删除重建而是挂一条“变更任务”问题就会可控得多。3.4 缺少验收标准AI 和自己都不知道“做完了”是什么样很多返工不是因为 AI 写得差而是验收的人和写的人不在同一标准上。Spec Kit 要求在写需求时同时定义验收标准AI 生成完任务清单后每一行都可以对应一条验收检查项。4. Spec Kit 工作流完整拆解Spec Kit 这个名字可以从两个层面理解一是“Specification Kit”一套把需求转成规格文档的工具和模板二是“Spec → Kit”即从规格一步步拆出可执行任务的过程。下面按三个核心阶段拆解。4.1 Specify需求规格化Specify 阶段要产出《需求规格说明书》。不要把这份文档写成小说用结构化格式。关键要素字段说明示例需求编号全局唯一方便后续追踪REQ-001需求概述一句话说清这个需求要解决什么问题用户可通过手机号验证码登录背景与动机为什么现在要做这个功能现有登录流程不支持移动端验证码业务规则不可绕过的硬性规则同一手机号 5 分钟内最多发送 3 条验证码交互流程用户在界面上的操作路径输入手机号 → 点击获取验证码 → 输入验证码 → 点击登录数据要求涉及哪些字段、存储要求新增 user_login_log 表记录登录 IP 和时间和设备验收标准可验证的完成条件验证码输入错误时提示“验证码错误”连续错误 5 次锁定 15 分钟边界与异常要考虑的异常场景手机号格式错误、验证码过期、网络超时明确不做的事项防止 AI 过度设计本轮不做第三方账号绑定不做扫码登录下面是一份可以直接复制使用的 Markdown 模板# 需求规格说明书 ## 需求编号 REQ-001 ## 需求概述 [一句话描述功能目标] ## 背景与动机 [为什么现在要做这个功能来自哪个反馈渠道] ## 业务规则 - [规则1] - [规则2] ## 交互流程 1. [步骤1] 2. [步骤2] ## 数据要求 - 新增表 / 修改字段[说明] - 存储和保留周期[说明] ## 验收标准 - [ ] [可勾选的验收点1] - [ ] [可勾选的验收点2] ## 边界与异常 - [异常场景1及处理方式] - [异常场景2及处理方式] ## 明确不做的事项 - [范围外内容1] - [范围外内容2] ## 变更记录 | 版本 | 日期 | 变更内容 | 变更原因 | 负责人 | | --- | --- | --- | --- | --- | | v0.1 | [日期] | 初稿 | - | [作者] |Specify 阶段操作建议交付给 AI 之前先用这份文档模板人工或半自动走一遍。不需要写得像需求文档那么长重点是“业务规则”和“验收标准”两条不能缺。4.2 Plan制定实施计划拿到需求规格后不要直接让 AI 写代码而是先让它产出实施计划。Plan 阶段要明确技术选型用什么框架、什么存储、什么第三方依赖。模块划分需求涉及哪些模块模块间的依赖关系。接口设计对外提供什么 API请求和返回结构是什么。数据库变更涉及哪些表结构修改是否要迁移脚本。风险点哪些地方容易出错哪些地方依赖其他团队。实施顺序先做什么、后做什么哪些任务可以并行。一份好的 Plan 应该让任何一个开发者在没有看完整需求文档的情况下也能按计划推进。示例# 实施计划 ## 技术选型 - 后端框架FastAPI 3.0 - 数据库MySQL 8.0新增 user_login_log 表 - 缓存Redis用于存储验证码TTL 5 分钟 - 短信服务测试环境使用 Mock 客户端线上接入云厂商短信 API ## 模块划分 | 模块 | 说明 | 依赖 | | --- | --- | --- | | 登录接口 | 处理手机号验证码登录 | 短信模块、验证码模块 | | 验证码模块 | 生成、校验、限制发送频率 | Redis | | 日志模块 | 记录登录行为和 IP | 无 | ## API 设计 - POST /api/v1/auth/send-code - 请求{ phone: 13800138000 } - 响应{ code: 0, message: ok } - POST /api/v1/auth/login - 请求{ phone: 13800138000, code: 123456 } - 响应{ token: xxx, expires_in: 7200 } ## 数据库变更 - 新增 user_login_log 表 - id BIGINT 主键 - phone VARCHAR(20) - ip VARCHAR(64) - login_time DATETIME - 不需要修改现有用户表 ## 风险点 - 验证码模块需要处理 Redis 不可用时的降级逻辑 - 短信发送频率控制要放在服务端不能只靠前端限制 ## 实施顺序 1. 先实现验证码模块 2. 再实现登录接口 3. 最后实现日志模块 4. 联调测试4.3 Tasks任务拆解与执行Plan 是“做什么、怎么做”Tasks 是“具体哪一步做什么”。每个 Task 要满足三条标准足够小一个 Task 能在一次代码提交里完成。可验收完成后有明确的判断标准。有依赖关系能看出前置任务是什么能不能并行。Task 清单示例# 任务清单 ## Task 1创建验证码存储工具类 - [ ] 实现 Redis 封装key 规则为 sms:code:{phone} - [ ] 支持设置过期时间默认 5 分钟 - [ ] 支持校验接口校验成功后删除 key - 依赖无 - 验收能调用 set_code、verify_code、delete_code 三个方法并跑通单元测试 ## Task 2实现发送验证码接口 - [ ] 校验手机号格式 - [ ] 检查同手机号发送频率5 分钟内最多 3 次 - [ ] 调用短信服务发送验证码 - 依赖Task 1 - 验收调用接口后Redis 中有验证码记录同号第 4 次请求返回频率超限错误 ## Task 3实现登录接口 - [ ] 校验验证码 - [ ] 校验通过后生成登录 token - [ ] 写入登录日志 - 依赖Task 1、Task 2 - 验收正确验证码可登录错误验证码返回“验证码错误”登录日志有新增记录5. 从需求评估到执行的完整流程把四个环节串起来看完整流程是这样的需求评估 ↓ 编写 Spec需求规格说明 ↓ AI 生成 Plan实施计划 ↓ 人工审核 Plan ↓ 拆分 Tasks任务清单 ↓ 按 Task 逐个执行并验证 ↓ 需求变更 → 回到 Spec 更新变更记录 → 重新生成受影响 Task5.1 需求评估阶段做什么需求评估不是正式写 Spec而是快速判断“这个需求值不值得进入流程”。你可以在接到需求后先回答三个问题需求是否明确如果不明确缺哪些信息。需求是否涉及现有系统的数据结构和接口变更如果涉及影响面多大。需求是否需要多轮迭代如果只需要一次修改是否可以直接走轻量流程。评估完成后再决定是走完整 Spec Kit 流程还是简化处理。不要为了用工作流而用工作流。5.2 用提示词让 AI 参与 Spec 生成在实际操作中你可以让 AI 辅助生成 Spec而不是从头手写。提示词模板如下请基于以下需求描述帮我生成一份需求规格说明使用 Markdown 格式。要求包含需求编号、需求概述、背景与动机、业务规则、交互流程、数据要求、验收标准、边界与异常、明确不做的事项。如果有信息缺失请标注“待确认”不要自行假设。 需求描述 [在这里粘贴原始需求文本]5.3 用提示词让 AI 生成 PlanSpec 确定后让 AI 生成实施计划以下是一份需求规格说明。请基于它生成实施计划包含技术选型、模块划分、接口设计、数据库变更、风险点、实施顺序。请用表格和列表组织不要输出长篇散文。如果技术选型需要假设请列出假设条件并标注“由开发人员确认”。 需求规格 [粘贴需求规格内容]5.4 用提示词拆分 TasksPlan 审核通过后再拆 Tasks基于下面的实施计划拆分为可执行任务清单。每个任务要包含任务编号、具体工作项、依赖关系、验收标准。任务粒度要小到可以在一次代码提交内完成。 实施计划 [粘贴计划内容]这里有一个很关键的习惯不要一次性让 AI 生成全部代码而是让它按 Task 逐个执行。每完成一个 Task把产物回到任务清单中打钩再进入下一个。6. 让每次需求变化都有记录Spec Kit 工作流的核心价值到这里才真正展开需求变化时的变更管理和追踪。6.1 变更记录写在哪里每一个需求的变更第一落点必须是 Spec 文档里的“变更记录”表格。不要只在代码里改也不要只在新提示词里改。## 变更记录 | 版本 | 日期 | 变更内容 | 变更原因 | 负责人 | | --- | --- | --- | --- | --- | | v0.1 | 2025-06-10 | 初稿 | - | 张三 | | v0.2 | 2025-06-12 | 登录方式增加“邮箱验证码” | 产品侧用户反馈部分用户不使用手机号 | 张三 | | v0.3 | 2025-06-15 | 将验证码有效期从 10 分钟改为 5 分钟 | 安全团队风险提示 | 李四 |6.2 变更如何流转到 Plan 和 Tasks变更记录更新后不是直接跳到最后去改代码而是按顺序走一遍更新 Spec 中受影响的业务规则和验收标准。检查 Plan 中受影响的模块、接口或数据库设计。找到 Tasks 清单中所有受影响的完成项更新状态为“已变更”。新增一到两个“变更实施任务”而不是在旧任务上直接改。执行新增任务完成后回到验收标准确认。这套流程看起来多了一步但它保证了如果变更后出现线上问题你能清楚查到是哪一个变更、在什么时候、因为什么原因引入的。6.3 变更追踪的落地文件建议如果不想引入重型的项目管理工具用 Git 仓库加 Markdown 文档就足够。目录结构建议project/ ├── specs/ │ ├── REQ-001-login-spec.md │ └── REQ-002-export-spec.md ├── plans/ │ └── REQ-001-login-plan.md ├── tasks/ │ └── REQ-001-login-tasks.md └── changelogs/ └── 2025-06-changelog.md把 Spec、Plan、Tasks 和变更记录分开存放配合 Git 提交历史使用每次需求变更都能回溯到最初的决策背景。7. Spec Kit 与 AI 编程工具的协同示例下面用实际的操作序列演示这套工作流在 AI 编程工具里怎么落地。假设场景要新增一个“用户反馈提交”功能。第一步编写需求规格初始版本用户可以通过页面表单提交反馈反馈内容包括类型、标题、详细描述。 提交成功后用户能看到提示并将反馈写入数据库。把这些内容按第 4.1 节的模板整理成 spec 文档。第二步把 spec 交给 AI 编程工具生成 plan以下是用户反馈提交功能的需求规格请生成实施计划重点说明技术选型、表结构设计、接口设计和实施顺序。第三步拿到 plan 后人工确认反馈表字段是否覆盖全部需求是否要限制用户重复提交频率是否需要后台管理入口。如果缺失条件回到 spec 补充再重新生成 plan。第四步拆 tasks 并逐个执行请把计划拆成 tasks。每个 task 包含完成项、依赖、验收标准。不要一次性生成全部代码等我确认一个 task 后再继续下一个。实际操作流程如下让 AI 生成第一个 task 代码。本地运行或查看差异。确认符合验收标准后要求 AI 进入下一个 task。当需求变更时比如增加“反馈类型必须包含业务线”操作顺序更新 spec 的业务规则。在变更记录中新增一行。让 AI 列出受影响的 plan 和 task。新增变更 task 并执行。8. 常见问题与排查方法在使用 Spec Kit 工作流的过程中比较常见的问题如下表问题现象可能原因排查方式解决方案AI 生成的 Plan 与需求规格不一致Spec 中业务规则太模糊或 Plan 生成本身有假设对照 Spec 的验收标准逐条核查 Plan在 Plan 提示词中要求“如有假设标注待确认”任务拆解过粗一个 Task 对应几千行代码提示词没有明确任务粒度检查 Tasks 清单中验收标准是否可勾选在提示词中要求“一个 Task 在一次代码提交内完成”需求变更后 AI 生成代码逻辑自相矛盾直接让 AI 改代码没有更新 Spec 和 Plan查看变更记录和受影响 Task 列表先更新 Spec再重新生成受影响部分的 Plan 和 Task团队成员不在同一套 Track 模式中只有一个人在用 Spec Kit其他人按旧方式开发检查文档目录和 Git 提交信息推广统一的 specs/plans/tasks 目录约定写入的变更记录没人看文档写完后没有后续流程衔接检查变更记录是否被评审或关联到 PR在 Merge Request 中添加变更记录链接要求关联 spec简单需求走完整流程太繁琐没有区分轻量流程和完整流程检查需求是否需要多轮变更对于一次性修改可只写核心规则和验收标准历史 Spec 不维护代码改了文档没更新对比最新代码与 spec 文档在 PR 规范中要求同步更新 spec 文档9. 最佳实践与使用建议9.1 第一次使用先跑一个小需求不要一上来就把整套流程用在大型重构项目上。挑一个中等复杂度的需求比如一个登录、一个导出功能跑通一遍。重点观察的是这套流程带来的额外时间成本能不能被减少的返工时间覆盖。9.2 Spec、Plan、Tasks 的修改权限要分级建议把哪个级别的文档允许 AI 自动修改写清楚Spec默认人工维护AI 只能提出修改建议。PlanAI 可以在人工确认后修改。TasksAI 可以自动更新但每次更新要在变更记录里留痕。这个分级能避免 AI 自作主张修改需求边界。9.3 建立“验收标准优先”的检查习惯在让 AI 开始写代码前强制要求自己先写出验收标准哪怕只是一个勾选清单。AI 生成的代码是否合格以验收清单为唯一准绳不依赖“感觉”。9.4 用 Git 提交信息关联 Spec 编号提交代码时在 commit message 中带上需求编号后续定位 bug 时可以直接反查需求变更历史。git commit -m feat: 实现验证码登录接口关联 REQ-001 Task 39.5 定期复盘哪些 Spec 引起的返工最多记录返工原因需求本身就是模糊的技术方案选错了变更范围没有控制好验收走查不到位。如果某个原因反复出现针对它调整流程。Spec Kit 不是静止的模板它应该根据团队数据持续迭代。10. 总结与后续扩展Spec Kit 工作流的本质是在 AI 编程的高效输出和人类需求的可控性之间加一层缓冲。它没有复杂的技术实现核心是三个动作把需求写清楚、把计划定下来、把任务拆到位。最先应该验证的是 4.1 节的《需求规格说明书》模板直接拿它替换你平时给 AI 发的一段话需求。如果你的 AI 编程工具支持自定义指令或 Agent 配置可以考虑把 Spec 模板和 Plan 提示词固化到配置里让每次新会话都自动带出这套规范。最容易踩的坑是“流程做得很重但文档写完没人用”。如果团队没有习惯在 PR 和 commit 里引用 Spec 编号这套流程会很快形同虚设。建议从个人项目或小团队做起用至少两周时间验证它对返工率的实际影响。下一步可以继续扩展的方向包括把 Spec Kit 和项目已有的代码评审、测试覆盖、持续集成流程打通根据 AI 编程工具的特性调整 Plan 的提示词当积累足够多的历史 Spec 后还可以让模型基于历史规格生成更准确的新需求草稿。对于正在用 AI 写代码但频繁返工的团队建议收藏备用。先用一个小需求跑通再决定要不要推广到全部项目。