Spec Coding能省21小时不返工,但90%团队用错场景反而拖慢开发
过去三个月,三个采用AI自动补全的团队,有两个因为需求理解偏差返工超过40%。问题不在AI写代码的能力,而在人类没说清楚“到底要什么”。当开发者直接让AI“写个用户登录功能”,得到的可能是带社交绑定、短信验证、多因子认证的复杂实现——而你本只需要一个邮箱密码表单。这种“氛围编码”(Vibe Coding)在快速原型阶段尚可容忍,但一旦进入多人协作或长期维护,模糊意图带来的技术债务会迅速失控。Spec Coding(规范驱动开发)正是为解决这一矛盾而生:先用结构化文档明确需求边界、验收标准与约束条件,再让AI在契约框架内执行。它不是否定AI效率,而是通过前置思考,把“盲目打字员”转化为“靠谱合作者”。
01Spec Coding 到底要求写什么?何时写?AI如何参与?
Spec Coding 的核心不是写传统PRD,而是创建AI可解析的“执行契约”。主流实践(如GitHub SpecKit、OpenSpec)将其拆解为三层文档:
项目宪法(Constitution):定义不可违背的底线原则,如“禁止直接操作数据库”“所有API必须带版本号”。这相当于给AI划定红线,防止其在重构时越界。
功能规范(Specification):聚焦“What”和“Why”,而非“How”。例如,“用户能通过邮箱订阅Newsletter,重复提交返回400错误”,而非“用Express写POST接口”。
原子任务(Tasks):将规范拆解为5–10分钟可完成的子任务,每个任务附带验收Checklist,如“创建subscribers表(含email唯一索引)”“实现/api/subscribe POST处理器”。
AI全程参与但不主导:人类用/speckit.specify指令生成初稿,审核后触发/speckit.plan制定技术方案,再由/speckit.tasks拆解任务,最终/speckit.implement按任务逐个编码。每一步都设人工审查点,确保AI始终锚定真实意图。
项目宪法(Constitution):定义不可违背的底线原则,如“禁止直接操作数据库”“所有API必须带版本号”。这相当于给AI划定红线,防止其在重构时越界。
功能规范(Specification):聚焦“What”和“Why”,而非“How”。例如,“用户能通过邮箱订阅Newsletter,重复提交返回400错误”,而非“用Express写POST接口”。
原子任务(Tasks):将规范拆解为5–10分钟可完成的子任务,每个任务附带验收Checklist,如“创建subscribers表(含email唯一索引)”“实现/api/subscribe POST处理器”。
AI全程参与但不主导:人类用/speckit.specify指令生成初稿,审核后触发/speckit.plan制定技术方案,再由/speckit.tasks拆解任务,最终/speckit.implement按任务逐个编码。每一步都设人工审查点,确保AI始终锚定真实意图。
| 对比维度 | 传统开发 / Vibe Coding | Spec Coding |
|---|---|---|
| 需求变更响应 | 依赖口头同步或零散文档,易遗漏上下文,返工率高 | 变更先更新spec.md,AI自动同步至后续任务,影响范围清晰 |
| 协作成本 | 新成员需阅读大量代码才能理解模块职责 | specs/目录即单一真相源,文档与代码强绑定 |
| AI辅助效果 | 提示词越写越长,仍难避免幻觉(如擅自引入新依赖) | AI在spec约束下生成代码,偏差率降至5%以下 |
| 隐性要求 | 无强制规范,依赖个人经验 | 需团队共识文档结构、评审流程,并集成到CI/CD(如golden test验证) |
Spec Coding 与传统开发在关键维度上的差异
02收益与风险:什么情况下它反而会拖慢你?
支持者称其为“准时下班的秘密武器”:阿里团队实测用户权限模块开发从30小时压缩至9.1小时,核心在于前期“多花6小时想清楚”,换来后期“省21小时不返工”。GitHub数据亦显示,采用Spec Coding的PR驳回率下降40%。但硬币的另一面同样尖锐:一位独立开发者直言,新项目前提高度不稳定(产品方向、MVP范围频繁变动),导致Spec快速过时,批量制造“负资产”——旧spec、旧任务、旧架构持续污染AI上下文,使后续生成基于错误前提。
Spec Coding 适用性争议
适合确定性高的场景
企业级系统:需求边界清晰,长期维护成本敏感
团队协作:新人通过specs/目录快速对齐上下文
合规项目:审计要求可追溯的需求-代码链路


不适合探索性项目
MVP验证:产品方向未定,过早文档化浪费精力
创意型应用:交互逻辑需快速试错,规范束缚迭代
小型脚本:文档成本远超编码本身
更隐蔽的风险在于工具成熟度。实测显示,当前AI在理解项目规则(如uni-app约定)、复用既有机制(如登录校验)等方面仅达三四成水平,需人工介入30+轮调试。这意味着Spec Coding并非“一键躺平”,而是将工作重心从“写代码”转向“审文档+陪跑AI”。对初级开发者而言,写出无歧义的spec本身已是挑战。
03决策指南:你的团队该采纳吗?
不必全盘照搬,可依据三个变量灵活选择:
项目复杂度:若涉及多模块耦合、严格SLA或合规要求,推荐完整Spec流程;若为单页应用或内部工具,可简化为“约束先行”——仅编写CLAUDE.md明确技术栈与禁区。
团队成熟度:有文档文化且熟悉TDD的团队可快速上手;若习惯“先跑起来再说”,建议从渐进式Spec切入——每次AI出错即沉淀一条规则到.specs/目录。
AI工具链:若已使用Cursor/Claude Code等支持/specify指令的工具,可直接集成SpecKit;否则优先配置项目说明文件(如.github/copilot-instructions.md),低成本建立AI工作约定。
项目复杂度:若涉及多模块耦合、严格SLA或合规要求,推荐完整Spec流程;若为单页应用或内部工具,可简化为“约束先行”——仅编写CLAUDE.md明确技术栈与禁区。
团队成熟度:有文档文化且熟悉TDD的团队可快速上手;若习惯“先跑起来再说”,建议从渐进式Spec切入——每次AI出错即沉淀一条规则到.specs/目录。
AI工具链:若已使用Cursor/Claude Code等支持/specify指令的工具,可直接集成SpecKit;否则优先配置项目说明文件(如.github/copilot-instructions.md),低成本建立AI工作约定。
最后两条避坑提示:
1. 警惕过度文档化:Spec应随项目演进增量完善,而非一次性写完。OpenSpec的“提案-归档”机制值得借鉴——每个变更独立proposal.md,评审通过后才转入specs/。
2. 严防AI幻觉放大:规范中禁用模糊表述(如“高性能”“用户体验好”),改用可验证标准(如“API响应<200ms”“支持1000并发”)。发现Bug时,坚持“先修文档再修代码”,从源头修正错误契约。
1. 警惕过度文档化:Spec应随项目演进增量完善,而非一次性写完。OpenSpec的“提案-归档”机制值得借鉴——每个变更独立proposal.md,评审通过后才转入specs/。
2. 严防AI幻觉放大:规范中禁用模糊表述(如“高性能”“用户体验好”),改用可验证标准(如“API响应<200ms”“支持1000并发”)。发现Bug时,坚持“先修文档再修代码”,从源头修正错误契约。
当前文章无评论,是时候发表评论了