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 githttps://github.com/github/spec-kit.git # 方式二用pipx安装 pipx install githttps://github.com/github/spec-kit.git # 方式三直接用pip不推荐但能用 pip install githttps://github.com/github/spec-kit.git装完之后验证一下specify --version如果能看到版本号输出说明安装成功。这里有个小坑如果你之前装过旧版本建议先卸载再重装因为Spec-Kit的模板结构在早期版本里变动比较大。3.2 初始化项目specify init做了什么进入你的项目目录执行specify init .这个命令会在当前目录下创建一套Spec-Kit的标准结构。核心目录包括.specify/存放模板、脚本、配置specs/存放每个功能的规范文档memory/存放constitution等长期约束初始化完成后你会看到.specify/templates/下面有几个关键模板文件模板文件用途spec-template.md功能规范模板plan-template.md技术方案模板tasks-template.md任务拆解模板constitution-template.md项目宪法模板这些模板不是摆设它们是AI生成内容时的“骨架”。你填得越细AI输出越可控。3.3 选择AI助手不同工具的适配差异Spec-Kit本身不绑定特定的AI编码工具它通过生成结构化的prompt来驱动AI工作。目前适配比较好的有Claude Code、GitHub Copilot、Cursor等。我实测下来Claude Code对Spec-Kit的流程支持最完整因为它可以直接读取项目文件、执行命令、修改代码。Copilot在IDE里的体验更顺滑但对多文件操作的支持稍弱。Cursor介于两者之间。不管你用哪个工具核心逻辑是一样的Spec-Kit生成结构化的指令文件你把这些文件喂给AIAI按照指令执行。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写完之后执行/planAI会读取spec结合constitution里的技术约束生成一份技术方案。这份方案会明确用什么语言、框架、库数据库表结构怎么设计API接口怎么定义目录结构怎么组织关键算法或逻辑怎么实现这一步的价值在于把技术决策从AI的“默认偏好”变成你的“主动选择”。如果你不写planAI会自己选一个它觉得合适的方案。但AI的选择未必符合你的项目现状。举个例子你的项目已经在用PostgreSQL但AI可能给你生成MySQL的建表语句。你的项目用FastAPI但AI可能给你生成Flask的代码。plan阶段就是纠正这些偏差的地方。我通常会在plan阶段做几件事检查AI选的技术栈是否和现有项目一致检查数据库设计是否合理索引、外键、字段类型检查API设计是否符合RESTful规范检查是否有安全漏洞SQL注入、XSS、CSRF如果发现问题直接改plan文档然后让AI重新生成。4.3 第三步写tasks——把大功能拆成可验证的小任务plan确认后执行/tasksAI会把技术方案拆解成一个个独立的任务。每个任务都有明确的输入、输出、验收标准。典型的tasks列表长这样## 任务列表 1. [ ] 创建User模型和数据库迁移 2. [ ] 实现密码加密工具函数 3. [ ] 实现JWT token生成和验证工具 4. [ ] 实现登录API接口 5. [ ] 实现登录失败次数限制逻辑 6. [ ] 编写单元测试 7. [ ] 编写集成测试每个任务都是可以独立完成和验证的。你可以让AI逐个任务执行每完成一个就review一次。这样做的好处是问题暴露得早修复成本低。4.4 第四步implement——AI按任务执行你按标准验收任务列表确认后执行/implementAI会按照tasks列表逐个执行。每完成一个任务它会生成代码运行测试检查验收标准如果通过标记任务完成如果不通过自动修复或请求你介入这个阶段你不需要盯着AI写每一行代码但你需要定期检查AI的输出是否符合预期。我的习惯是每完成2-3个任务就review一次避免AI在错误的方向上越走越远。5. constitution机制给AI立规矩的正确姿势5.1 constitution应该写什么constitution是Spec-Kit里最容易被忽视但最重要的部分。它相当于项目的“宪法”定义了AI必须遵守的硬性约束。一份好的constitution应该包含# 项目宪法 ## 技术栈 - 语言Python 3.11 - 框架FastAPI - 数据库PostgreSQL 15 - ORMSQLAlchemy 2.0 - 测试pytest ## 代码风格 - 遵循PEP 8 - 函数和变量用snake_case - 类名用PascalCase - 常量用UPPER_CASE - 每个函数必须有docstring ## 目录结构 - src/ 存放源代码 - tests/ 存放测试 - migrations/ 存放数据库迁移 - docs/ 存放文档 ## 安全约束 - 密码必须用bcrypt加密 - 所有API必须验证JWT token - 禁止在代码里硬编码密钥 - 所有数据库查询必须参数化 ## 禁止事项 - 禁止使用eval() - 禁止使用pickle反序列化用户输入 - 禁止在日志里输出密码和token5.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 习惯五持续迭代constitutionconstitution不是一次写完就完事的。每次发现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只在复杂功能上才走完整流程。这样既保证了代码质量又不会让流程变得太笨重。