Spec Coding 规范驱动编程实战：从 Vibe Coding 到 AI 代码规范

你好，我是小 G。拖了蛮久，来填坑了。
Spec Coding 很早之前就有群友提到说发起写一下。确实还蛮告急的，工作中能用到，口试也开始问了。

这里以我想的一个真实工作场景的例子作为开场。
上周和同事谈天，他问我还在折腾 Spec Coding 干嘛。原话大概是：“Claude Code 都能自己写代码了，你花时间写规范不是多此一举？”
我当时没忍住怼了一句：“AI 写出来的屎山代码，你来维护？”
他愣了一下。
说实话我明确他的想法。AI 写代码确实快，扔一句需求已往，几秒钟一个函数就出来了，跑起来还挺像那么回事。Demo、脚本、一次性页面，这么搞没弊端。
但标题是——你把这套玩法搬到一个多人协作、要恒久维护的项目里，过两周再返来看那段代码，你大概率不想碰，也不敢碰。
由于需求里没写清的部门，AI 自己脑补了；界限条件你没提，它按“常见写法”猜了一个；你们团队的错误码格式、权限校验约定，AI 一个都不知道。它只是按照练习数据里出现频率最高的方案，给你拼了一段“看起来能跑”的代码。
这篇文章聊 Spec Coding 的核心思绪，内容不少，发起收藏。通过本文你将搞懂：

• Vibe Coding 和 Spec Coding 的实际差异，以及什么时间该用哪个
  
• 完备的 Spec Coding 落地流程，从写需求到让 AI 按规矩实验
  
• Spec 在主流 AI IDE（Cursor、Claude Code、Copilot 等）里怎么配、怎么管、怎么防止 AI 越界
  

Vibe Coding 不是不能用

Vibe Coding（氛围编程），凭感觉走。给 AI 一句暗昧的意图，它就直接开始输出代码。
Karpathy 最早提这个词时，说的也是那种把需求丢给 AI、顺着感觉不停调解、乃至临时不太管代码细节的写法。
Vibe Coding 不是原罪。下面这些场景，用它反而很符合：

• 验证一个想法，先写个 Demo 看看结果
  
• 写一次性脚本，跑完就扔
  
• 做内部小工具，影响面很小
  
• AI 写完后，有完备测试兜底，而且不直接袒露给外部用户
  

这些环境下，硬写一大堆 Spec 反而是浪费时间。
真正的标题是：许多人验证完想法之后，顺手就把 Vibe 出来的代码推上了生产。
这就不一样了。
Demo 阶段你可以靠感觉走，由于错了就改，坏了就删。生产代码不可，它反面会接数据库、接付出、接用户数据、接别人的维护本钱。你本日省下来的半小时，大概会变成反面几天的排查时间。
我的判定尺度就一条： 这段代码要活多久？

• 两天就扬弃的脚本，Vibe 够了。写 Spec 反而拖服从。
  
• 3-5 天这种中央地带，可以写轻量 Spec。不消睁开完备筹划，只写关键束缚和验收尺度，半小时差不多能搞定。
  
• 凌驾一周的代码，只要须要别人维护、涉及数据恒久化、接入外部接口，就别裸 Vibe。至少要把束缚、界限和验收尺度写清晰。
  

而且，许多时间搭配轻量级 Spec 也没标题，不须要太枯燥。
轻量 Spec 可以简单到这种水平：

1. ## 任务目标
3. 实现一个订单导出接口，支持按时间范围导出 CSV。
5. ## 关键约束
7. - 单次导出最多 5000 条
8. - 时间范围不能超过 31 天
9. - 必须校验用户权限，只能导出当前租户的数据
10. - 查询必须命中 order_tenant_time_idx 联合索引
11. - 导出失败要记录失败原因，不能只返回 unknown error
13. ## 验收标准
15. - 正常导出 CSV，字段顺序符合产品约定
16. - 超过 5000 条时返回明确错误
17. - 越权租户数据不能被导出
18. - 单元测试覆盖空时间、越界时间、无权限、无数据四种场景

复制代码

Spec Coding 到底是什么

Spec Coding，直译过来叫规范驱动编程。简单来说就是：先把规范写清晰，再让 AI 干活。
寻常让 AI 写代码，许多人会直接丢一句：

帮我做一个用户体系。

AI 固然能写，而且看起来还挺像那么回事。但标题也在这里：你没告诉它用户体系到底长什么样，它就只能自己猜。
用户怎么注册？邮箱能不能重复？暗码怎么存？接口失败时返回什么格式？哪些功能这期不做？管理员有没有禁用用户的本领？这些东西如果一开始没写清晰，AI 不会停下来反问你，它大概率会先补一套自己以为公道的方案。
Spec Coding 做的事故，就是把这些规则提前写下来。
这里的 Spec 不是任意写两句需求，而是一份 AI 能照着实验的技能约定。接口、数据布局、错误码、界限条件、安全要求、技能栈限定，乃至哪些使用不答应碰，都要写在内里。
它和 Vibe Coding 的差异，也就在这。
Vibe Coding 更像是你给 AI 一个大方向，然后让它自由发挥。代码天生出来以后，你再去验收、改 bug、补细节。短平快的小脚本这么干没啥标题，乃至很爽。
但项目稍微复杂一点，就轻易失事。等你发现 AI 明确错了，代码已经写了一堆。你转头查，也很难说清晰到底是需求没表明确，还是 AI 自己乱发挥。
简单总结下 Spec Coding 和 Vibe Coding 的差异：AI 的举动是由你界说的，还是由它猜的？
四步落地

一样寻常会把 Spec Coding 拆成四步：Specify、Plan、Tasks、Implement。
阶段干什么产出关键动作Specify产物界说requirements.md明确功能、用户、痛点，定“做什么”Plan技能规划design.md定技能栈、架构、左券，定“怎么做”Tasks使命拆解tasks.md拆成原子使命，写验收尺度ImplementAI 实验-AI 按 Spec 干活，人验收明确起来实在很简单，核心就是先写清晰要做什么，再写清晰怎么做，然后拆使命，末了交给 AI 实验。

Specify：先搞清晰做什么

第一步是 Specify，产出一样寻常是 requirements.md，大概叫 spec.md。
这一步有点像写 PRD，但面向的使用者是 AI。
以是，它不能只写方向，得把界限也写出来。
好比你写一句：

做一个用户体系。

人看着没标题，AI 看了就开始猜了：用户怎么注册？邮箱能不能重复？暗码有啥要求？第三方登录做不做？管理员能不能禁人？被禁了数据怎么办？
你不写，它就自己定。
更稳一点的写法是：

支持邮箱注册和登录；邮箱必须唯一；暗码长度至少 8 位；暂不支持第三方登录；管理员可以禁用用户；用户被禁用后不能登录，但汗青数据保存。

这句话让 AI 知道哪些能做，哪些不能做，哪些界限不能碰。
Plan：敲定技能方案

第二步是 Plan，一样寻常会落到 design.md 或 plan.md 里。
这一步许多人会跳过，以为反正 AI 会写代码，让它自己发挥就行。
然后标题就来了。
你没说用哪个 Java 版本，它大概给你写 Java 8 的代码；你没说 Spring Boot 版本，它大概按旧写法来；你没说错误码格式，它就每个接口返回一套；你没说分层方式，它大概 Controller 里直接写业务逻辑；你没说表字段怎么定名，它也会按自己的风俗来。
以是 design.md 不消写得特别重，但几个关键束缚得先定下来。
好比先写成如许就够用：

1. ## 技术栈
3. - 语言: Java 21 (LTS)
4. - 框架: Spring Boot 3.2.x
5. - 数据库: PostgreSQL 16
6. - 缓存: Redis 7.x
8. ## 架构设计
10. - 分层: Controller → Service → Repository
11. - 通信: REST API + gRPC（内部服务）
12. - 部署: Docker + Kubernetes
14. ## 接口约定
16. - API 规范: OpenAPI 3.0
17. - 错误码: 统一格式 {"code": "USER_NOT_FOUND", "message": "..."}
18. - 日志格式: JSON，必须包含 trace_id

复制代码

你大概会想：这不就是筹划文档吗？
确实有点像。
但区别在于，传统筹划文档重要是给人看的。人看完知道大方向，剩下许多细节可以靠团队风俗补上。好比暗码不能明文存、错误码要同一、日记里要带 trace_id，这些东西在成熟团队里通常不消反复夸大。
AI 不一样。
你没写，它就猜。猜对了还好，猜错了就得你返来返工。
拿暗码存储举个例子。你只写一句“登录要安全”，对人来说可可以或许了，但对 AI 来说太宽了。它大概知道不能明文存暗码，也大概给你整一个看着像安全、实际不应用的方案。
更稳的做法是把规则写死：

1. 密码使用 bcrypt 哈希存储。
2. bcrypt cost 默认设置为 12，可根据服务器性能在 10-14 之间调整。
3. bcrypt 自带随机盐，数据库只保存哈希值，不保存明文密码。

复制代码

这段看着有点细，但它把“安全”这个大词拆成了 AI 能实验的几条详细规则。
错误处置惩罚也一样。别写“接口失败时返回友爱提示”，这句话根本没束缚力。AI 大概这个接口返回 error，谁人接口返回 message，另有的地方直接抛非常。
直接写清晰：

1. {
2.   "code": "USER_NOT_FOUND",
3.   "message": "用户不存在",
4.   "trace_id": "xxx"
5. }

复制代码

再补一段状态码约定：

1. 参数错误返回 400。
2. 未登录返回 401。
3. 无权限返回 403。
4. 资源不存在返回 404。
5. 邮箱重复、用户名重复这类冲突返回 409。

复制代码

如许 AI 至少知道该往哪个方向写。
说到底，design.md 重要是为了淘汰 AI 自己补设定。你把技能栈、接口格式、错误码、日记、并发、安全这些规则提前写好，反面让 AI 写代码时，它就不太轻易跑偏。
Tasks：使命要小到能验收

第三步是 Tasks，一样寻常会写到 tasks.md 里。
这里不要一上来就让 AI “完成用户模块”。这个范围太大了。注册、登录、查询、禁用、权限、参数校验、非常处置惩罚、单位测试，全都塞在一个使命里，AI 很轻易写着写着漏东西。末了你看代码时，还得一项一项往回补。
但也别拆得太碎。创建 UserDTO、添加 email 字段、写一个空的 Service 方法——这种使命看起来很细，实际会把人折腾死。你维护使命列表的时间，大概比让 AI 写代码还长。
我比力喜欢的粒度是：一个 Task 对应一个 API、一张表的核心使用，大概一个能独立验收的小功能。
好比用户注册接口，可以这么写：

1. ### Task-001: 用户注册接口
3. 描述：实现用户注册，包含参数校验、密码加密和用户入库。
5. 验收标准：
7. - [ ] POST /api/v1/users 成功时返回 201
8. - [ ] 密码使用 bcrypt 加密后存储
9. - [ ] 邮箱唯一，重复注册返回 409
10. - [ ] 返回体必须包含 user_id、email、created_at
11. - [ ] 分支覆盖率（branch coverage）不低于 80%
13. 预估工时：2h

复制代码

这里真正值钱的是验收尺度。“包管安全”“代码优雅”“性能要好”——这种话写了跟没写差不多，AI 不知道你心田的安全到底指什么，优雅要优雅到什么水平。
但暗码用 bcrypt，重复邮箱返回 409，返回体里有 user_id、email、created_at，分支覆盖率不低于 80%——这些东西都能跑测试验证，不消靠感觉。
覆盖率阈值别机器套。纯逻辑模块做到 80% 以上通常公道；如果涉及大量外部依靠、异步流程和复杂 mock，可以放宽到 60-70%，把重点放在关键分支组合有没有覆盖。
Implement：让 AI 干活

提示词不消搞得很玄学，直接把相干 Spec 塞进去就行：

1. 请根据以下 Spec 实现 Task-001。
3. 需求说明：
4. [粘贴 requirements.md 相关段落]
6. 技术约束：
7. [粘贴 design.md 相关段落]
9. 任务验收标准：
10. [粘贴 tasks.md 里的 Task-001]

复制代码

这里有个坑：不要把全部 Spec 一股脑塞进上下文。
单次会话里，我会优先放三类内容：

• 全局束缚，好比代码风格、错误码格式、日记规范；
  
• 当前使命的需求分析；
  
• 当前使命的验收尺度。
  

其他内容按需补，不要为了“完备”把全部文档都贴进去。
一样寻常来说，单次输入控制在 3000-8000 tokens 会更稳一点，大抵相称于 1-2 份 Spec 文档，再加 1-2 个相干代码文件。凌驾这个范围，就拆会话。
别指望模子在一个特别长的上下文里什么都顾得上。上下文越长，关键信息越大概被淹在中央，末了反而遗漏最告急的束缚。
我自己会服从三条原则：
第一，约定写进文档，不要只写在谈天里。谈天纪录下次很大概接不上，文档才是可以复用的上下文。
第二，验收尺度能量化就量化。“高性能”没法验收，QPS > 1000、P95 < 200 ms、branch coverage >= 80% 才华验收。
第三，Spec 要进 Git，跟代码一起走。代码变了，Spec 也要改。否则反面继承让 AI 开辟，它拿到的就是一份逾期分析。
这一步走通后，AI 不会突然变智慧，但乱猜的空间会小许多。
接下来另有个很实际的标题：这些 Spec 到底放那边，怎么让工具每次都读到？
Spec 在 AI IDE 里怎么落地

写完 Spec 之后，有个标题经常被忽略：这些文件到底放那边？怎么让 AI 自动读到？
主流工具都有自己的规范文件机制：
工具规范文件位置作用域加载方式Cursor.cursor/rules/*.mdc（新版）或 .cursorrules（旧版）项目级 / 全局新版支持 frontmatter，可设 Always apply 或按文件 glob 自动附加Claude CodeCLAUDE.md（根目次和子目次均可）项目级 / 目次级进入目次自动加载GitHub Copilot.github/copilot-instructions.md堆栈级自动注入每次哀求Windsurf.windsurfrules项目级自动加载AiderCONVENTIONS.md（堆栈根目次）项目级通过 --read CONVENTIONS.md，或在 .aider.conf.yml 里用 read: 自动加载到这里，另一个标题也会冒出来：Cursor、Claude Code、Copilot 这些是一样寻常写代码的入口，那 Superpowers、Spec-Kit、Open Spec、Kiro、BMAD-METHOD 这些专门围绕 Spec Coding 的工具，到底该怎么选？

这个标题睁开会比力长，我预备放到下一篇单独聊。这里先把 Spec 怎么写、怎么放、怎么管住 AI 说清晰。
知道放哪之后，另有一个标题：哪些 Spec 每次都注入，哪些按需带上？
实际使用中，我一样寻常分成两层。
险些每个会话都要带上的（必须注入）：

• 技能栈：版本和关键库写明，好比 Go 1.21 + Gin + GORM + PostgreSQL 14。别让 AI 自己猜版本号。
  
• 代码风格：贴一段 150-200 行的示例代码，展示定名、错误处置惩罚、表明、返回格式。别只写抽象原则，一段参考实现比十条规则管用。
  
• 界限条件：用三色标签（反面会说）划清晰什么能做、什么要问、什么绝不能碰。
  

这些放工具的 always-on 规则文件里，每次会话自动注入。
当前使命相干时才带的（按需注入）：

• 项目愿景：一两句话说清为啥做这个项目，好比“把用户服务从单体拆出来，用 Go 重写，API 兼容”。新使命开始时带一次就行。
  
• 下令清单：列出 build、test、run 下令，好比 make build、go test ./...。有执使用命时带上。
  
• 目次布局：树状图说清代码、测试、文档分别放哪。涉及新增文件时才须要。
  
• Git 规范：分支名、commit message、PR 要求。涉及 Git 使用时带上。
  

这么分的缘故原由很直接：全局束缚险些每次都要服从，值得常驻。其他的按使命加，制止上下文里堆太多不相干的内容。Spec 塞越多，AI 反而越轻易遗漏真正告急的那几条。
三色标签：AI 夺目什么、不夺目什么

AI 碰到拿禁绝的使用时，到底该自己决定还是停下来问你？
三种颜色，三种权限。

• ✅ Always（自动实验）：代码查抄、测试、格式化这些，AI 自己拍板就行。好比提交前自动跑 make lint。
  
• ⚠️ Ask first（需确认）：大概影响其他模块的变动，AI 出方案等你审。改数据库索引、改 API 路由这种就属于这类。
  
• 🚫 Never（绝对克制）：直连生产库、提交密钥、删线上数据。AI 碰到就必须停，报错。
  

落地的时间有几件事轻易忽略。
刚开始宁严勿松。 Ask First 多放点，跑一周后看哪些使用 AI 每次都做对了，再放到 Always。
规则必须写详细。 “告急变动需确认”这句话 AI 没法实验，它不知道什么算“告急”。得写成“修改已有 API 的 URL 路径需确认”。“警惕使用数据库”也不可，要写“ALTER TABLE 使用需确认”。
Never 规则不能只靠 AI 自觉。 只在文档里写“克制直连生产库”，并不能真的拦住它。AI 不会自动查抄自己的输出是否违规。Never 规则须要多层防线：

• Spec 声明：影响 AI 天生倾向，但拦不住
  
• 设置模板：.env.example 里不放真实密钥，AI 就没东西可复制
  
• Pre-commit hook：正则扫密钥硬编码、生产环境毗连串，提交时自动拦截
  
• AI IDE 设置：.cursorignore 制止 Cursor 读取 .env.production 之类的文件
  

越告急的 Never 规则，越要推进到 CI 层做硬性查抄。停在“文档里有写”这一步，早晚失事。
每周转头看一次。AI 是不是动不动就停下来问？那 Ask First 里有些使用可以放行了。AI 有没有偷偷干不应干的事？有就补 Never。项目里有没有冒出新的敏感使用？加进去。
项目大了，Spec 怎么管

小项目 Spec 少，手动往上下文里丢就行。模块多了之后全塞上下文就废了，AI 看着一堆和当前使命无关的束缚，反而更轻易跑偏。
按规模选计谋。

Spec 管理计谋：分层过滤 + 精准召回
10 个模块以内：分文件存储

按范畴拆就行：

1. specs/
2. ├── global/              # 全局约束
3. │   ├── conventions.md   # 代码规范
4. │   └── architecture.md  # 架构概览
5. ├── backend/             # 后端规格
6. │   ├── api/
7. │   ├── service/
8. │   └── persistence/
9. ├── frontend/            # 前端规格
10. └── shared/              # 共享契约
11.     └── dto.md

复制代码

每次只把当前使命相干的两三个文件丢进去，别贪多。
10-30 个模块：择要索引

手动挑文件开始累了，就让 AI 先天生一份目次加关键词索引：

1. ## Spec 索引
3. - [数据库设计](specs/db/schema.md) - 关键词: PostgreSQL, 索引优化
4. - [用户 API](specs/backend/api/user.md) - 关键词: REST, JWT, 鉴权
5. - [订单服务](specs/backend/service/order.md) - 关键词: 事务, 幂等

复制代码

须要细节时让 AI 自动来要，不消全量灌进去。
30 个模块以上：RAG 向量检索

手动选文件不实际了，得上 RAG。Embedding 模子选 text-embedding-3-small/large，向量库看规模：Chroma 得当本地，Pinecone 得当云端，Milvus 得当企业级。Chunk 计谋按语义单位切，一个 Task 或一个 API 界说为一个 chunk，默认控制在 512-1024 tokens 之间。Top-K 召回 3-5 条，加相似度阈值 > 0.7。
但十个模块的项目搞向量库，纯属给自己找事。什么时间人工选上下文开始痛楚了，什么时间再上。
不分规模都管用的一条：单会话单使命

1. Session 1: 数据库设计
2. ├── 输入: global/conventions.md + backend/db/
3. ├── 输出: 完成实体设计
4. └── 关闭会话
6. Session 2: API 实现
7. ├── 输入: Session 1 产出 + backend/api/
8. ├── 输出: 完成 Controller
9. └── 关闭会话

复制代码

上下文干净，AI 就不会被前面使命的边角料带跑。这条比什么花哨的检索计谋都管用。
范畴知识为什么这么告急

AI 练习数据再多，也不知道你项目里那些特定的规则，你得自动告诉它。
举个例子：你做了一个商城项目，此中有一个规则是优惠券和秒杀不能叠加。这个规则你不写进 Spec，AI 很大概就把两个扣头都算上了。代码能跑，测试也大概过，但业务直接错了。
这类知识一样寻常可以分成几种：

• 业务规则：优惠券和秒杀不能叠加，同一用户天天只能领取一次夸奖
  
• 技能束缚：订单分页必须走指定团结索引；深分页（> 100 页）改用游标，克制全表扫描
  
• 汗青债务：第三方上传接口只支持 5 MB，凌驾就会报错，以是代码里要提前校验
  
• 性能基线：单表查询控制在 50 ms 内；关键接口凌驾 200 ms 要思量降级或兜底
  

这些东西是 AI 写代码时的界限。
如今许多 Spec-Driven Development 的思绪就是把 Spec 从“写给人看的文档”变成“束缚 AI 天生代码的规则”。
不要以为 Spec 只是前期用用，后续实现、校验和维护时都须要。
不外，只把规则写进去还不敷，最好再加一段自检清单。由于 AI 很轻易写完功能就竣事，不会自动转头确认这些隐含束缚。
完成自检清单

使命写完之后，不要让 AI 直接说一句“已完成”。
至少让它按清单自己过一遍。好比完成 Task-001 后，必须逐项确认：
<ul ><li > 全部 API 错误返回都符合同一格式<li > 数据库查询掷中了指定团结索引<li > 优惠券和秒杀的互斥逻辑已精确实现<li > 单位测试覆盖了空值、越界、并发等界限场景<li > 分支覆盖率（branch coverage）>= 80%<li > 圈复杂度 = 80%[/code]模板二：Gherkin 风格，得当 BDD

1. git commit -m "[code] implement user registration API"
2. git commit -m "[test] add unit tests for user registration"
3. git commit -m "[review] fix null check in email validation"

复制代码

模板三：Checklist 风格，得当代码检察
[code]## Code Review Checklist### 功能性- [ ] 实现符合 Spec 形貌- [ ] 界限条件已处置惩罚：空值、越界、并发- [ ] 错误处置惩罚美满### 质量- [ ] 函数长度