夜雨聆风如何在不牺牲自动化效率的前提下，用 Spec 约束显著降低 AI 研发返工。
在 AI 编码进入团队主流程后，很多组织会经历一个看似矛盾的阶段：
小迭代任务完成度很高，速度感明显；
一到中大型改造，主链可跑通，但返工并没有按预期下降。
这时最容易得出的结论是“模型能力不够”，但这通常只说对了一半。真正的问题往往是：我们已经把 需求理解 做得很成熟，却还没有把 执行约束 升级到与 AI 协作匹配的层级。
1. 先给结论：Spec 在 AI 时代的价值，不是“写文档”，而是“编译约束”
很多团队把 Spec 理解成“更规范的 PRD/TRD 写作方式”。这个理解太轻了。
在 AI 研发语境里，Spec 的核心价值是三件事：
把“应该知道”变成“必须执行”；
把“看起来改完了”变成“有证据地覆盖完了”；
把“经验性复盘”变成“机制性门禁”。
换句话说，Spec 是 执行系统的一部分，而不是知识库的装饰层。
图示：问题到结果的两条路径
这张图先建立全局认知：问题不只是模型快慢，而是有没有把执行约束系统化。
2. 为什么 PRD/TRD 已经很全，仍然会出现覆盖漏洞
2.1 先说结论
PRD/TRD 讲清楚的是“要改什么”，但真正决定返工的是“有没有把所有该改的链路都改完”。
换句话说：
•文档完整，解决“知道做什么”；
•覆盖完整，解决“确保都做了”。
这次返工多，核心不是方向错，而是覆盖不完整。
2.2 本次真实问题对照表（已修复）
下面是Claude Code 在经过一轮的XXX工作流执行后，然后人工按照业务链路的审查发现的漏洞举例
本次真实问题 | 现场表现 | 对应的覆盖漏洞类型 | 事后看本可提前怎么发现 |
add/edit返回类型改了但回滚不干净 | 局部逻辑修回来，但返回链路仍有残留影响 | 语义一致性漏洞 | 做一次add/edit全链路回归（入参→校验→返回） |
warningMsg放错对象 | 前端该拦截没拦住，或提示位置不对 | 分支语义漏洞 | 明确“warning 挂载点”并做导入场景断言测试 |
独立流程漏了映射 | 主流程正常，特定子流程行为不一致 | 入口链路遗漏 | 入口清单强制包含“主链+支链”逐项勾检 |
3 个 Request DTO 漏字段 | 部分入口带不出字段，导致后续逻辑缺值 | 字段扇出遗漏 | 字段传播矩阵强制检查 Request 家族 |
2.3 为什么这些问题会同时出现
因为这类需求天然是“多入口 + 多语义 + 多出口”：
•多入口：add / edit / import ...
•多语义：有的场景该badRequest，有的场景该warningMsg；
•多出口：主表、history、导出、外部接口。
只要检查方式还是“改了哪些点”，而不是“数据流是否完整跑通”，就很容易出现：
•主链是对的；
•但支链、分支语义、对称链路漏一两个点。
2.4 用这次复盘沉淀一个可执行判断
以后遇到类似改造，判断“是否真的完成”不要只问“代码改没改”，至少再问三句：
4.这个字段在所有入口（Request/DTO）都打通了吗？
5.这个规则在所有业务子域（标准/委外/FLPO）语义一致吗？
6.这个改动在所有对称面（main/history/外部接口）都同步了吗？
这三句答不全，就不要宣布完成。
3. Vibe Coding 与 Spec 不是对立，而是互补
一个成熟团队不该在“自由生成”与“流程约束”之间二选一。
•Vibe Coding解决的是探索速度与表达效率；
•Spec约束解决的是方向稳定与覆盖完整。
如果只有 Vibe，没有 Spec，系统会很快但容易漂移；如果只有 Spec，没有生成效率，系统会稳但吞吐下降。
真正有效的模式是：
用 Vibe 提速，用 Spec 扣边界；用 AI 生成细节，用机制校验完整性。
4. OpenSpec 与 Spec-Kit：不要神化“选型”，要重视“分层”
社区常见说法是：Spec-Kit 偏 0→1，OpenSpec 偏轻量迭代。这个说法有参考价值，但在真实工程里不必僵化。
更实用的判断框架是：
•如果团队需要统一规范骨架、生命周期阶段、角色责任，优先引入流程性更强的框架（例如 Spec-Kit 思路）；
•如果团队已有工作流，希望增强增量变更的约束与追踪，优先引入轻量规格管理（例如 OpenSpec 思路）。
最优解通常不是替代关系，而是分层协同：
•上层：流程骨架（阶段、工件、门禁）；
•下层：迭代协议（变更、影响面、证据）。
图示：分层协同架构（不是二选一）
这张图对应本节主张：用流程骨架保秩序，用迭代约束保覆盖，最终反馈回 Spec。
5. 如何“加约束”但不“把效率还给人工”
很多团队一听“加强 Spec 约束”，马上陷入另一个极端：
•人先手工穷举所有类、DTO、SQL 触点；
•AI 只做机械改写。
这会直接损失自动化价值。
正确做法应该是：
7.AI先穷举影响面（入口链路、字段传播、出口触点）；
8.人类只做裁决（有没有漏域、语义是否正确、风险是否可接受）；
9.AI再提交证据（规则→代码位置→测试结果）。
一句话：不是把工作还给人，而是把“覆盖责任”还给机制。
图示：效率轨与稳定轨并行
这张图的重点是“并行”而非“取舍”：不是慢下来，而是更稳地快。
6. 面向 AI 代理的四层约束模型
L0 意图层（Intent）
定义“为什么改、验收结果是什么、哪些行为必须保持不变”。
L1 执行层（Execution）
让 AI 自动产出影响图，至少包括：
•入口流程；
•字段传播链；
•对外接口；
•对称域（main/history/export/print/push）。
L2 证据层（Evidence）
每条规则必须映射到：
•代码位置；
•测试或探针结果；
•未覆盖项与风险说明。
L3 门禁层（Gate）
自动执行覆盖探针，不满足条件不放行。
图示：一次需求从输入到放行的执行时序
这张时序图用于说明：为什么“有证据再提审”能显著降低评审往返成本。
7. 三个最实用的防漏工件
7.1 字段传播矩阵（Field Propagation Matrix）
YAMLfield: externalProject flow:inbound_request:- AddDTO- EditDTO- ImportDTO- ExternalApiDTOdomain:- ValidationService- MappingService- BO/DOpersistence:- main_table- history_table- mapper_sqloutbound:- export_dto- print_dto semantics:add_edit_fail: bad_requestimport_fail: warning_msg |
7.2 场景验证矩阵（Scenario Matrix）
维度 | 取值 |
用户 | 内部 / 外部 |
组织 | MI_PHONE / 非 MI_PHONE |
入口 | add / edit / import / FLPO / 委外 |
结果语义 | hard_error / soft_warning |
7.3 规则-证据映射表（Rule-to-Evidence）
规则ID | 规则描述 | 代码位置 | 测试/探针 | 状态 |
IMP-REV-002 | 外部用户导入反向映射失败走 warning | service/import/... | ImportFlowIT#warning | PASS |
ADD-REV-001 | add/edit 反向映射失败抛 badRequest | service/order/... | AddEditIT#reverse_fail | PASS |
这三个工件的价值在于：它们把“改造点描述”升级为“可验收合同”。
8. 与 RFLP 的协同实践：不推翻流程，只增强执行层
从使用经验看，RFLP 这类流程在工程规范和协作节奏上已经很成熟，尤其在常规迭代场景下表现稳定。它的下一步增强重点，不是改流程名字，而是补上AI 执行后的覆盖门禁。
建议把增强点放在三个位置：
10.TRD 之后：自动生成 Execution Spec；
11.代码审查前：生成 Coverage Probe 报告；
12.合并门禁时：检查 Rule-to-Evidence 是否完整。
这样不会显著增加人工成本，因为细节仍由 AI 生成，人类主要承担决策与风险裁决。
9. 两周试点计划（可直接执行）
第 1 周：先建约束，不动组织结构
•引入 Execution Spec 模板；
•引入字段传播矩阵与规则证据映射表；
•配置 3 类探针：入口探针、对称探针、语义探针。
第 2 周：跑真实需求并量化
跟踪四个指标：
•rework_rate：返工提交数 / 总提交数；
•coverage_gap：探针发现漏点数 / 规则数；
•first_pass_rate：一次评审通过率；
•human_intervention_time：人工纠偏时长。
若指标改善，再扩大自动化覆盖面；若未改善，再定位是模型问题、约束问题还是门禁阈值问题。
10. 结语：AI 交付能力，终将是“模型 × 约束”的乘积
AI 编程的竞争不会停留在“谁生成得更快”。
下一阶段真正决定差距的是：谁能把工程约束编译成代理可执行协议，让交付变得可预测、可证明、可复盘。
Vibe Coding 的价值是速度，Spec 的价值是稳定。
当二者协同，团队得到的不是“更慢的规范”或“更冒险的自动化”，而是：
把“快”变成“稳的快”，把“会写”变成“可交付”。
关键词：Spec Engineering、OpenSpec、Spec-Kit、Vibe Coding、AI Agent、RFLP、交付稳定性
