AI Coding 提效的天花板是信任，不是速度 —— 一个工业级 Harness 的落地复盘

真正的瓶颈：不是 AI 写得慢，是 AI 写完不敢上线

本文素材来自一支风险敏感业务团队（资金链路 + 状态机 + 多领域规则）2026 年的内部工程复盘，公开版本保留方法论与架构骨架、隐去内部专有系统名、规则代号与具体度量数字。重点不是"他们用了哪个工具"，而是"他们对 AI Coding 的失败模式给出了什么结构化的回应"。

一个反直觉的观察

当一支团队把 AI 代码率从「占比 30%」推到「占比 95%」之后，他们没有得到对应的提效曲线。复盘后他们看到的现象是：

AI 编码阶段省下来的时间，几乎被代码审查阶段的反复返工抵消掉了。返工率高达 30%。问题不是 AI 写得慢，是 AI 写完不放心上线。

更关键的发现：返工的根因不在代码质量本身，而在约束没说清、没传递、没验证。AI 在约束缺失的地方，会用训练数据里的"普遍模式"自动填充 —— 而这些"普遍模式"恰恰不适用于他们这种特殊领域：

• "退款金额不能超过原始支付总额" —— 通用场景下 AI 会假设成立，但在部分退款 + 优惠券抵扣的真实业务里成立不了。
• "金额必须用 BigDecimal" —— AI 经常默认用 Double，跑得通但精度会出问题。
• "状态机转换必须满足 X 前置条件" —— AI 在长对话里会"忘记"早期给出的约束。

三个架构级转变

团队对失败模式的归纳，最后浓缩成三个转向 —— 每一个都是从"事后补救"换成"系统级前置"：

这三句话背后有一个共同的洞察：AI Coding 的风险防控不能依赖 AI 本身，而要依赖外部系统。

类比一下自动驾驶：你不会指望司机实时纠正自己的判断错误，而会依赖传感器 + 规则引擎 + 安全气囊组成的多层防护。AI Coding 的逻辑是一样的 —— 提效靠 AI，但防错靠 Harness。

四要素 × 两层防御：把约束做成可验证的物理对象

四要素：约束的物理载体

团队把 Harness Engineering 的理念落地为四个互相咬合的核心要素 —— 不是文档清单，是有结构、可索引、能被流程消费的物理对象：

需求输入 → [Wiki 提供上下文] → [Rules 注入约束] → [Skills 执行流程] → [Changes 记录轨迹]
              ↑                  ↑                    ↑                    ↑
        "系统长这样"        "这些红线不能碰"       "按这个流程做"      "做了什么一目了然"

① Rules · 不可妥协的红线

规则是 Harness 的"宪法" —— 不随需求变化的稳定约束（Invariant Constraints），数百条规则按严重等级分层。所有 Skill 的检查逻辑、门禁的准出条件、验证契约的判定标准，全部来源于 Rules：

这个等级表里最重要的不是"L0 / L1 / L2"，而是"处置语义"分层：L0 是机器可判定的硬卡点；L1 需要人工介入；L2 / L3 是可降级的建议。让自动化和人工审查各司其职 —— 机器负责确定性判定，人负责模糊性判断。

⚙️ 一条规则只要"不能被机械化执行"，在 Agent 流程里就是无效约束。规则不是越多越好。

② Skills · 可复用的标准化流程

Skills 是 Harness 的"执行引擎"。覆盖从需求到发布的完整链路，每个 Skill 封装一个完整的质量保障流程：

关键在 Skill 之间的数据流 —— 不是简单的调用链，而是结构化产物的"接力赛"：

• 需求风险识别 产出风险标签 → 注入技术方案的风险感知
• 技术方案 产出约束清单（双格式）→ 供任务拆解绑定
• 任务拆解 产出约束索引表 → 供代码审查逐条验证
• 代码审查 产出约束合规报告 → 供发布风险评估聚合决策
• 发布风险评估 产出 Go/No-Go 决策 → 最终门禁判定

每一步约束都在"增值"而不是"传递" —— 每个阶段都为约束增加新维度，最后形成一条可追溯的数据闭环。

③ Wiki · AI 的业务上下文

Wiki 告诉 AI "系统长什么样"，而非让 AI 从代码里反向猜测。包含链路梳理、数据模型、业务流程、技术规范四类知识。和 AGENTS.md 的"地图而非手册"理念一致 —— 顶层索引（100 行内）+ 按需加载详细文档，避免上下文窗口过载。

三件事的分工很清楚：Rules 告诉 AI"不能做什么"，Skills 告诉 AI"按什么流程做"，Wiki 告诉 AI"系统是什么样" —— 三者共同构成 AI 的完整上下文。

④ Changes · 全链路可追溯

每个需求从分析到部署的全过程文档，构成完整追溯链：需求追溯（任务 → PRD 编号）/ 约束追溯（约束 → 任务绑定 → 代码实现）/ 变更追溯（文件 → 变更类型 → 关联任务）/ 决策追溯（设计决策 → 多要素记录卡）。

四条追溯链交织成一张完整的变更网络：从任何节点（需求 / 约束 / 文件 / 决策）出发，都能追踪到所有关联节点。这不是"事后补文档"，而是"流程中自动记录"。

两层防御：约束的运行机制

四要素是"弹药"，两层防御才是"作战体系" —— 它决定约束如何被注入、传递和验证：

这里有一个关键的工程取舍：中间不设"编码时约束层"。因为 AI 编码时根本无法可靠地实时执行约束 —— 上下文截断、约束遗忘、优先级覆盖是固有缺陷。所以团队的选择是：把"约束执行"从不可靠的实时检查，换成可靠的批量验证。

这和传统软件工程"编译时检查 vs 运行时检查"的取舍是同一个味道 —— 在 AI 场景下，"编码后验证"比"编码时实时检查"更可靠。

验证契约：让"约束覆盖率"从空话变成可追踪的数字

什么是验证契约

验证契约（Verification Contract）的核心思想是：每条约束都必须有一个明确的验证方式 —— 怎么验证、什么时候验证、谁来验证、预期结果是什么。没有验证方式的约束就是"无效约束"，因为它无法被机械化检查。

每条约束都会被结构化为一份"契约"，字段如下：

这本质上是契约式设计（Design by Contract）在 AI Coding 场景的落地。传统契约式设计定义的是模块间的契约；这里定义的是"约束定义方"和"约束验证方"之间的契约 —— 定义方承诺约束可验证，验证方承诺逐条核对。

约束的完整生命周期

一条约束从诞生到被验证，经历四个阶段，没有任何一个阶段允许"丢"：

关键创新是阶段 ① 的"约束直出双格式"：每条约束同时输出 Human 可读格式（自然语言）和结构化 JSON 格式（含 ID、等级、验证方式、预期结果等 10 个字段）。这种双格式设计确保约束从"文档"到"可执行检查项"的无损传递 —— 下游模块直接消费 JSON，不依赖人去重新理解文档。

度量指标：从空话到数字

有了验证契约，"约束覆盖率 ≥ 95%" 这种过去听起来像空话的指标，第一次变成了可度量、可追踪的数字：

这是从"希望 AI 遵守约束"到"验证 AI 遵守了约束"的范式转变 —— 也是整套 Harness 最核心的"信任工程"。

三道门禁：质量关卡，不是橡皮图章

3 道门禁全程卡点

团队的设计原则是"不信任、要验证"。三道门禁分别守在三个关键卡口，每一道都是自动化判定 + 模式感知：

每道门禁守的角度都不一样：

• G1 验证"输入是否完备" —— 约束是否都提取了、技术方案是否覆盖了关键风险、资金安全是否评估了。
• G2 验证"输出是否合规" —— 代码是否满足了所有约束、是否有 AI 幻觉、约束覆盖率是否达标。
• G3 验证"发布是否安全" —— 影响范围是否可控、风险是否在可接受范围内。

三道门都是自动化判定，不是人工审批 —— 这是关键。AI 一天可以生成数千行代码，但人审一天只能扫数百行；如果门禁是人工的，门禁就会成为瓶颈，最终被绕过。让机器根据规则和评分公式自动判定，每条代码都过全量检查，而不是抽检。

统一评分公式

整个 Harness 用同一套评分语义在三道门之间做一致性判定：

方式一：Score = 100 - (L0 × 10) - (L1 × 5) - (L2 × 2) - (L3 × 0.5)
方式二：Score = SUM(weight × result) / SUM(weight) × 100

评分公式的核心思想是问题越严重，扣分越重 —— 一个 L0 扣 10 分、一个 L3 只扣 0.5 分。这不是简单加权，而是反映了不同等级问题的"修复成本和风险量级"差异。

变更规模自适应：门禁不能扼杀效率

团队对一个常见担忧"门禁太重会扼杀效率"给出了一个简单回答 —— 变更规模自适应：

这设计成立的关键是资金安全 L0 不可申诉 —— 不管在哪一档变更里，资金类 L0 都不可降级、不可豁免。这不是"太严格"，而是 ROI 决策：一条资金规则的 L0 准出，可能防止的就是一个真实生产故障。

⚙️ 三道门禁的真正价值，不是"挡得严"，而是"挡得准" —— 该挡的（资金、状态机、L0 缺陷）一行不让过；不必挡的（小补丁、文案修改）走快速通道。

六个核心模块：从需求质量到 AI 偏差检测

整个 Harness 落地为六个核心 Skill 模块，每个解决 AI Coding 流程中一类具体问题。本章是把整套流程"展开来看"。

E.1 需求风险识别 + 技术方案与约束注入

在最新架构里，需求风险识别已经从独立模块合并为技术方案的 Phase 0（需求澄清与风险识别）。合并的动机很直接：风险识别和方案设计不该割裂 —— 风险信号应该直接驱动约束的提取，而不是先识别风险、再写方案、再手动对齐。

这个模块用了一个多阶段漏斗式生产流程，每个阶段都有 Gate，上一阶段未通过不能进入下一阶段：

Phase 0: 需求澄清与风险识别
    ↓ Gate: 需求无歧义，风险标签已标注
    ↓ 交互式追问：最多 3 轮 / 维度，15 轮总计，必须等待用户回答
Phase 1: 需求承接与场景识别
    ↓ Gate: 目标可度量，场景识别完成
Phase 2: 架构设计与约束注入
    ↓ Gate: 架构图覆盖所有交互系统
Phase 2.5: 设计决策追问  ★关键阶段
    ↓ Gate: 关键决策有替代方案
    ↓ 交互式追问：最多 2 轮 / 维度，10 轮总计，决策链 7 要素必须记录
Phase 3: 详细设计与约束注入
    ↓ Gate: 接口契约完整
Phase 4: 三板斧与容灾设计
    ↓ Gate: 三板斧判定
Phase 5: 约束汇聚与一致性验证
    ↓ Gate: 约束覆盖率 = 100%
Phase 6: 质量验收与输出
    ↓ Gate: G1 门禁通过

Phase 0 的"Socratic 五维追问"

这不是简单地问"有什么遗漏吗"，而是 5 个维度的递进式追问：

追问过程是交互式的 —— AI 提出问题后必须暂停等待用户回答，不能自问自答。最多 3 轮 / 维度，15 轮总计。这一阶段产出的风险标签（如 has_fund_pattern / has_state_change / has_business_logic）会贯穿后续所有阶段，驱动代码审查阶段哪些维度被条件激活。

Phase 2.5 的"设计决策追问"

实践里发现很多技术方案的问题不是"设计有问题"，而是"决策有问题" —— 决策过程没有记录，替代方案没有考虑，触发条件和可逆性没有说明。所以 Phase 2.5 强制每个关键决策必须记录决策链 7 要素：

决策 ID / 背景 / 选项 / 理由 / 取舍 / 触发条件 / 可逆性

同样是交互式追问，AI 不能自己回答自己的问题 —— 每个决策都必须等待用户在选项之间做选择。这就是这个模块和"审查型"模块最大的不同：它是"生产型"的，不只检查方案好不好，而是引导你生成完整的方案。

E.2 任务拆解与约束绑定

技术方案产出的是一份平铺的约束清单，但 AI 编码是按任务执行的。如果约束清单没有绑定到具体任务，AI 在编码时要么面对整个清单（上下文过载）要么完全看不到约束（约束遗忘）。

这个模块的解法是三步走：

1. 约束解析：把约束清单解析为可执行的结构化数据 —— ID、描述、等级、验证方式。
2. 任务拆解：把需求拆解为文件级粒度的编码任务，每个任务明确：要改哪些文件、改什么内容、预期产出。
3. 约束绑定：为每个任务精确匹配它相关的约束子集，形成"约束索引表" —— AI 在编码任务 T3 时只需要关注 T3 相关的约束。

"按需绑定"是这一步的关键 —— 它有效缓解了上下文窗口的压力，也让审查阶段有一份"按任务索引的清单"可以直接对照逐条核对。

E.3 代码审查与全维验证

这是验收层最核心的模块，合并了多个审查维度的近百条规则。设计理念是聚焦式审查 —— 不是泛泛检查所有维度，而是根据技术方案阶段的风险标签条件激活对应维度：

这里最有差异化的是 AI 偏差专项检测 —— 传统代码审查不会去检查"AI 幻觉 API"或"AI 过度实现"，但这恰恰是 AI 生成代码的独特缺陷模式：

传统审查假设"代码是人写的" —— 人会犯逻辑错误、漏边界条件，但不会编造一个不存在的 API。AI 会。AI 会调用一个看起来很像但实际不存在的库方法，会实现需求里根本没提到的功能，会在长对话里遗忘早期给出的约束 —— 这些用传统维度去查几乎查不出来。

E.4 发布风险评估

代码审查通过 ≠ 可以安全发布。发布风险评估关注的是"发布行为"本身的风险：变更影响范围有多大？是否有灰度策略？回滚方案是否就绪？资金安全专项是否通过？

这一步采用多分组评估 + Go/No-Go 决策模式：每个分组独立评估风险等级，最终聚合为整体风险判断。关键设计是"影响分析内化" —— 不再依赖人工填写影响范围，而是通过变更追溯链自动推断。

到这一步，验证契约的闭环就关上了：技术方案定义约束 → 任务拆解绑定约束 → 代码审查验证约束 → 发布风险评估确认约束。四阶段形成完整闭环，没有任何一个阶段允许约束"消失"。

E.5 需求质量评价：独立的源头守门人

"PRD 质量参差不齐"是 AI Coding 的"源头污染" —— 低质量 PRD 直接导致 AI 产出低质量代码。这不是 AI 的问题，是输入的问题。

需求质量评价模块用多维度结构化评价覆盖完整性、一致性、可测试性、边界条件等维度。它的关键设计是"独立调用"：不绑定任何特定阶段，任何时间点都可被开发者主动调用。这让它能扮演整个体系的"前置过滤器" —— 在所有约束工作开始之前，先确保输入质量。

六个模块的关系：E.1 / E.2 是"把约束说清"，E.3 / E.4 是"把约束验完"，E.5 是"不让坏输入进来"。三个动作各自独立，组合起来才是完整的信任工程。

编排系统：让整个流程自动化、可恢复、可追溯

六个 Skill 模块如果各跑各的，就只是六个孤立的工具。让它们咬合成一台"机器"，需要的是编排系统 —— 这是整套 Harness 的"神经中枢"。

F.1 三层编排架构

编排不是简单的脚本调度器，而是一个有状态、可恢复、上下文感知的多 Agent 工作流引擎。它的核心设计原则是"关注点分离"：

• 路由层：只管"走哪条路" —— 根据需求类型 / 变更规模 / 是否涉及资金，决定走哪种执行模式。
• 规划层：只管"怎么走" —— 把模式翻译为具体的 Phase 序列、Skill 调用顺序、门禁检查点。
• 执行层：只管"走好每一步" —— 调度具体的 Skill 执行、维护状态、处理失败重试。

三层之间通过结构化数据（路由决策、交付计划、状态文件）传递信息，而不是通过隐式状态。这是让整个系统"可调试、可恢复、可追溯"的根。

F.2 三种执行模式

路由层根据多维度评估自动选择执行模式 —— 不是简单按行数判断：

路由依据是 task_type / change_size / involves_fund / involves_state_machine / is_architecture_refactor 的组合判断 —— 越靠近资金 / 状态机 / 架构核心，门禁越重。

F.3 Agent 角色分离：不能"既当运动员又当裁判"

这是整个编排系统里最关键的一条设计决策：

执行者可以写代码、写测试；审查者只能读代码、写审查报告；门禁审计者只读规则和产出物。这种隔离确保审查者在独立的会话中工作 —— 看不到执行者的内部推理过程，只能看到最终的代码和文档。

这是把"人类组织里的回避制度"翻译到 Agent 流程里 —— "既当运动员又当裁判"在多 Agent 架构里同样必须被禁止。

F.4 TDD + CQG 编码流：让 AI 编码也有质量门

编码阶段（Phase 1.5）采用一套严格的工作流。这不是传统意义上的"先写测试再写代码"，而是用 TDD 作为约束落地的验证机制：

RED 阶段：基于约束清单编写测试用例
    ↓ 确认测试编译通过但执行失败
指纹锁定：SHA-256 锁定测试文件，执行者无法修改
    ↓ 锁定后测试文件不可变
GREEN 阶段：编写实现代码，使所有测试通过
    ↓ 遇到资金安全约束冲突时必须暂停
CQG（代码质量门）：fmt → lint → build → test 四步硬检查
    ↓ 任何一步失败即阻断
进入代码审查阶段

指纹锁定是这一步的关键创新 —— 测试文件一旦锁定，编码 Agent 就无法修改测试来"适应"实现。只有审查 Agent 才能解锁。这防止了 AI 为了通过测试而修改测试的"自欺"行为。

CQG 四步硬检查是代码进入审查阶段的前提：格式化 → 静态分析 → 编译通过 → 单元测试通过。任何一步失败都阻断流程，不允许"带病审查"。

F.5 Context Pack：上下文窗口的精准调度

AI 的上下文窗口是有限资源。Context Pack 解决的核心问题是：在每个阶段，只给 AI 看它需要看的内容，而不是把所有文档塞进去。

关键创新是三级优先级管理：

• P0 必传：约束清单、门禁规则、资金安全规则 —— 无论如何不能压缩。
• P1 重要：技术方案核心章节、代码变更摘要 —— 空间允许时全量注入，空间不足时摘要。
• P2 参考：Wiki 知识库、历史变更记录 —— 按需注入，空间不足时省略。

当上下文超出 Token 预算时，按三阶段压缩：结构化提取 → 摘要压缩 → 紧急截断。约束清单在三阶段压缩中始终不可压缩 —— 它是硬红线。

这和操作系统的虚拟内存管理是同一个设计思想 —— 按需加载，而非全量驻留。约束清单是"不可换出的内存页"。

F.6 状态机 + 断点续跑 + 可观测性

编排层内置完整的状态机，每个阶段的状态持久化到 state.json：

• 状态：in_progress / completed / failed / paused
• 检查点：phase-start → execute → interactive-waiting → gate-check → fix → phase-end
• 事件：skill_started / skill_completed / gate_passed / gate_failed / fix_requested / fix_completed

中断后，Phase Runner 读取状态文件和心跳记录，自动生成恢复计划，经人工确认后从最近检查点继续执行 —— 无需从头开始。门禁判定失败后自动进入"修复循环"（最多 3 轮：修复 → 重跑 Skill → 重检门禁），3 轮用尽仍未通过则阶段失败、人工介入。

整个 AI Coding 过程的"可观测性"分三层：

• Decision Log（decisions.json）：路由决策、设计决策、门禁判定、修复策略、上下文压缩等所有关键决策。
• Execution Trace（trace.jsonl）：步骤级追踪，每个 Skill 内部的执行步骤和耗时。
• Metrics（metrics.json）：性能指标、Token 消耗、错误统计。

这让整个流程从"黑盒"变成"白盒" —— 出了问题可以追溯到是哪个决策、哪个步骤、哪个约束出了问题。

可迁移到你团队的 7 个工程范式

把上面这些细节折叠起来，下面这 7 条是从这套实践里能直接迁移到任何 AI Coding 团队的工程范式 —— 不依赖任何具体工具，只是一种工作方式上的取舍。

① 把"约束"做成可验证的物理对象，不是文档

很多团队的约束写在 PRD 注释、技术方案附录、Wiki 散页里 —— 这些都不是约束，是"愿望"。一条真正的约束至少要有：ID / 等级 / 验证方式 / 预期结果。如果它不能被机械化执行，在 Agent 流程里就是无效约束。

② 不在编码时实时检查约束，在编码后批量验证

AI 的上下文截断、约束遗忘、优先级覆盖是固有缺陷。让 AI 在编码时实时执行所有约束 = 把约束扔进黑盒。改成"编码后逐条验证" —— 就像类型检查从动态语言搬到了静态分析阶段，一个量级的可靠性差距。

③ 角色分离：执行者 ≠ 审查者

同一个 Agent 写代码 + 自评代码 = 又当运动员又当裁判，无效审查。让审查 Agent 在独立会话里工作，看不到执行者的内部推理过程，只看代码和文档。这条规则在多 Agent 系统里和人类组织一样重要。

④ 测试文件指纹锁定：禁止"修改测试来通过"

这是一个简单但效果惊人的小设计 —— 测试一旦写好就 SHA-256 锁定，编码 Agent 不能再改。它直接堵死了 AI 最常见的"自欺"路径："实现写不出来，那就改测试。"

⑤ Context Pack 优先级管理：约束是不可换出的内存页

当 Token 预算紧张时，约束清单 / 门禁规则 / 资金安全规则一行都不能丢 —— 哪怕代价是把 Wiki 全部省略。这是一个看起来简单、但实操中经常踩坑的取舍：很多团队压缩上下文时第一反应是删约束，因为约束最长。结果就是 AI"看不见护栏"。

⑥ 门禁是自动化的，不是人工审批

AI 一天产数千行代码，人审一天扫数百行 —— 人工门禁就是瓶颈，最终被绕过。让规则和评分公式自动判定，每条代码全量过 → 这才是配得上 AI Coding 速度的门禁。同时配合"变更规模自适应" —— 小修小补走快速通道，核心变更走全量检查，门禁就不会成为效率的敌人。

⑦ AI 偏差专项检测：传统审查的盲区

幻觉 API、过度实现、约束遗忘、AI 偏差放大 —— 这四类是 AI 生成代码独有的缺陷模式，传统审查维度根本不会去查。任何打算把 AI 代码率推高的团队，都需要把这四类作为专门的审查维度独立出来 —— 否则 AI 写得越多，未被发现的"AI 特有缺陷"就越多。

把这 7 条放回到一句话里：

约束不是限制 AI，而是让 AI 可信；编排不是增加流程，而是让提效可持续。

AI Coding 的速度天花板，最终不是 AI 写得多快，而是团队敢让多少 AI 写的代码直接上线。这个差距就是"信任工程"要解决的问题。

← 返回最佳实践