开启 Harness Engineering 探索之旅：当 AI 写得越快，研发整体为何没有同步提速？

过去两年，AI Coding 的能力实现了惊人的跨越：从最初“能写出能跑的代码”，快速演进到如今“能放手让它写一整段功能”。但当我们将 AI 编码能力真正放入真实的业务场景、多人协作环境和复杂的存量系统中时，却意外地发现了一个令人困惑的悖论：AI 写代码的速度越快，研发的整体节奏并没有同步加快。

我们团队很快发现，一个被广泛引用的数据——“AI 写出来的代码占比”一路走高，但真正落实到版本迭代节奏上，提效幅度却远不如这个数字那么好看。在“出码率”和“实际效率”之间，赫然裂开了一道巨大的缝隙。

这个现象并非我们独有。从 OpenAI Codex 团队那篇著名的 Harness 工程博客中，他们反复强调了一个关键观察：“早期进展比预期慢，并不是因为 Codex 不具备相应的能力，而是因为环境的规范不够明确。”整个行业似乎都在不约而同地补同一堂课：为模型搭建一套能稳定干活的“工作环境”。

这一层工程实践，最近被业界正式命名为 Harness Engineering。它不是教模型“怎么回答”，而是设计模型“怎么工作”。今天，我将基于我们团队在一线业务中的真实踩坑、取舍与沉淀，系统性地分享我们的 Harness Engineering 探索之旅。

为什么我们需要 Harness Engineering？

本段核心问题：既然 AI 模型已经足够聪明，为什么还要在它外面包一层复杂的工程框架？

用一个正在被广泛引用的等式可以清晰表达：Agent = Model（模型）+ Harness（模型外的运行框架）

命名者 Mitchell Hashimoto 给出的定义更加朴素且直指核心：“每当你发现 Agent 犯了一个错，你就花时间在它外面工程化一个方案，让它永远不再犯同样的错。”这句话精准地概括了 Harness Engineering 的精髓：将工程关注点从“模型这一句说得对不对”，彻底挪到了“模型这一整段活干得稳不稳”。

换个视角看，这其实是 AI 工程关注点连续迁移的第三站。整个演进路径清晰地展示了我们是如何一步步走到今天的：

Prompt Engineering（2022–2024） ：我们关心的是单次调用的质量——这一句话怎么说，才能让模型这一次输出得更好。这是最原始的“问话”阶段。

Context Engineering（2025） ：我们开始关心每一步的输入——该把什么信息、以什么形式喂给模型。这是给 AI“配齐上班所需的资料”。

Harness Engineering（2026） ：我们开始关心整个任务的完成质量。当 Agent 需要跑长链条、多步骤的活时，可靠性已经不取决于模型本身，而取决于模型外面那一整套工程化框架：执行环境、工具协调、状态管理、反馈注入、约束施加、进展验证。

三者的关系不是替代，而是层层叠加。Prompt 教模型怎么说话，Context 保证它上班有足够信息，Harness 则给它搭一套能持续干活的工作环境。Harness 时代的到来，意味着前两层已基本成熟，而新的短板，被挤到了“模型外面”。

概念结晶：从实践到命名的自然演化

有意思的是，“Harness Engineering”这个词并非某个人一拍脑袋造出来的，而是一个典型的“先有实践、后有命名、再被推广”的概念结晶过程。2025 年 8 月起，OpenAI Codex 团队在 agent-first 内部实验中验证：模型能力之外，环境设计、上下文组织、工具抽象、反馈回路和控制系统同样决定 Agent 能否稳定工作。2026 年 2 月，Mitchell Hashimoto 将这类实践正式称为 harness engineering。随后，LangChain 用“Agent = Model + Harness”明确边界，Thoughtworks 将其拆解为 guides 与 sensors，学界也开始用 ETCLOVG 七层分类做系统化梳理。

目前，Harness Engineering 没有标准定义，但它拥有一条清晰的实践路径：为 Agent 搭建可执行、可约束、可验证、可反馈的工程环境。

我们踩到的“效率裂缝”

回到我们自己的团队：如今，很多同学都已经离不开 AI Coding 了——一个独立小模块从想法到能跑，往往只需要一杯咖啡的时间。但当盘点产出时，我们却发现了一件怪事：单看“AI 写出来的代码占比”一路走高，可真正落到版本节奏上，提效却远没有这个数字那么好看。出码率和提效之间，裂开了一道缝。

深入分析后，我们发现根因有三：

根因一：研发从来不是“写代码”这一个环节。 早在《人月神话》和《没有银弹》里，Brooks 就把软件难题拆成两层：附属复杂度（语法、工具、平台带来的“翻译成本”）和本质复杂度（概念结构的构造、对外部世界的顺应、需求的可变性）。AI 砍掉的恰好是附属那一层，本质复杂度一分没少——甚至因为代码产出更多，下游的对齐、Review、维护反而更重了。

根因二：局部加速只会让瓶颈转移，不会让它消失。 把“写”这一环踩到十倍速，但理解、对齐、验证、沉淀这些环节一步没动。整条链的总时长，由没被加速的部分决定。于是写得越快，下游的 Review、测试、维护越被动，瓶颈只是从“写”挪到了“收”。

根因三：AI 看不见我们工程体系里的隐性约束。 团队规范、领域知识、历史依赖，这些没被显式喂进去的东西，AI 一概看不见。

换个说法：当 AI 把“写代码”这一格的成本压到接近零，研发的瓶颈就显形了——真正的瓶颈本来就不在写，而在于“理解、对齐、追溯、沉淀、验证”这一连串非编码工作。而我们撞上的，正是 Harness 这一层。我们不是在解决 Prompt（模型已经够聪明）；也不是在解决 Context（检索、长上下文这些工具已经成熟）。我们撞上的、想解决的，是怎么让 AI 在我们自己的工程体系里，能验证、能反馈、能修复、能循环、能持续地跑下去。

拆解实践全景：两条轨道与一个长期记忆

本段核心问题：为了让 AI 在真实业务中稳定交付，我们需要搭建怎样的工程化体系？

我们的目标，用一句话说就是：「AI 驱动研发全链路 · 人提需求 → AI 理解 → AI 执行 → 人确认」 。从需求澄清到方案设计，再到实现、测试、部署、归档，覆盖 DEV / TEST / OPS 三段，以及线上运营告警闭环。

要让这个目标真正跑起来，我们把整套体系拆成了 2 条轨道 + 1 个长期记忆：

  • 轨道 1：研发端到端交付——管的是“上线前”。
  • 轨道 2：线上运营——管的是“上线后”。
  • 长期记忆（知识库） ——它让 AI 真正“懂”我们的业务、系统、线上质量。

轨道 1：研发端到端交付——SpecWorker 的项目工程落地

研发端到端交付要解决的核心问题是：换任何人来用、用在任何项目上，AI 的产出质量必须是稳定的、可预期的。为此，我们考虑了三个层面的事。

协议层：AI 每一步的输入输出契约

协议层管的是一件事：AI 每一步的输入和输出必须是什么样的。

反思：为什么需要协议层？因为你和 AI 之间没有契约。 你以为说清楚了，它以为理解了，做出来才发现对不上。人和人协作可以靠默契，人和 AI 协作必须靠契约。协议层就是这份契约。

它规定了四件事：

  • 每一步必须产出什么格式的文档
  • 文档必须用标准模板写
  • 写完机器自动校验是否达标
  • 每次变更只记增量，保留完整历史

预期的效果：AI 不再自由发挥，而是在明确的框架内输出。格式是确定的，内容是可校验的，历史是可追溯的。出了问题能查到是哪一步导致的。

管线层：标准化“需求 → 上线”6+1 阶段

管线层解决的是标准化整条链路工序的问题。让 AI 在跑“需求 → 上线”这条长链时，不会丢了上下文、丢了证据、丢了纪律。

从“需求 → 上线”历经 6 个核心阶段 + 1 个可选前置：P0 brainstorming（可选）→ P1 requirements → P2 design → P3 implementation → P4 e2e-test → P5 deploy → P6 archive。

P1 需求：TAPD 拉取 + AC 可测 + test-cases 同源

核心问题：研发的“理解、对齐”环节，在 AI Coding 里是最容易塌方的——AI 把功能写出来了，但“为什么这样写”没人能复述。核心痛点是：需求口径在 P1 阶段就要钉死，否则下游全部跑偏。

我们的做法有三条硬规矩：

  1. TAPD 拉取做需求底稿：P1 阶段第一步是从 TAPD 拉取本次需求的官方描述，作为 requirements.md 的“原始口径”段落。不允许 AI 自己复述用户的话，只允许它从 TAPD 引用。
  2. AC（Acceptance Criteria）必须可测：每条需求拆成 WHEN（前置条件）→ THEN（系统 SHALL…）形式，禁止“性能要好”这种不可测描述。
  3. test-cases.md 与 requirements.md 同源：P1 阶段同时产出 requirements.md（给 P2 用）+ test-cases.md（给 P4 用），两份文档共用同一份 AC 列表。下游 P4 不再“理解一遍需求自己写测试”，而是直接拿 test-cases 跑。

反思：P1 不解决“用户真正想要什么”——这件事必须人来做，我们只解决“AI 怎么不歪曲已经表达出来的需求”。

P2 设计：契约先行 + sandbox_mode + D-x 改动点

核心问题：传统 design.md 是给人读的——讲背景、讲思路、讲架构图。但 AI 读不懂这种文档，它需要的是机器可读的契约。

我们的做法：

  1. 契约先行：接口签名、数据模型、字段必填项一律写死成 Markdown 表格 + Mermaid 时序图/数据流图。design.md 是契约，不是说明。
  2. sandbox_mode 字段标记写入模式：前端 P2 design.md 顶部强制有 sandbox_mode: true / false 字段，让 AI 在改代码时知道“该不该先隔离”。
  3. D-x 改动点拆解：design.md 里有一个 D-1 / D-2 / D-3 … 改动点列表，逐项标注「文件:行号 @ 函数名」+「目的」+「实现」+「关键代码片段」。P3 实现时按 D-x 列表逐项勾掉，code-reviewer 也按 D-x 列表逐项 review。

反思：design.md 不强求“完美”，只强求“机器可读”——任何“等实现时再说”的字段必须显式标注“待澄清”或“待确认”，不允许暗藏。

P3 实现：D2C + UI 95% 五轮 + code-reviewer 三档

核心问题：实施阶段是最容易翻车的一格——AI 写得快，但写得对不对、像不像、改得稳不稳，全靠下游兜底。

前端 D2C+UI 校准：把“从 Figma 还原 UI”拆成 3 个 Skill 串行（拉设计稿、按 slug 分流、UI 校准）。UI 校准修正循环通过像素差异 + SSIM 双指标驱动，任一指标 < 95% 触发自修循环（最多 5 轮），每轮调起 fixer subagent 做局部修改，直到双 95% 或耗尽 5 轮。

后端 code-reviewer 三档契约 review：每次 P3 实现一个分组都自动调用 code-reviewer SubAgent，对照 design.md 检查一致性，输出三档：

  • Critical（必修） ：契约违反、接口签名不一致、错误码缺失。必须人审 + 签字 + 留痕。
  • Important（必标） ：可绕过但必须显式标记“已知偏差 + 原因”。
  • Suggestion（自由处置） ：风格、命名、注释等。

反思：code-reviewer 不读全文件，优先读 git diff。code-reviewer 也不解决“代码风格”——这部分交给 lint，code-reviewer 只看契约。

P4 集成测试：端测 + 后端 API 测试（双流程 · 失败自愈）

核心问题：测试是 AI Coding 最容易“假完成”的一格。前端和后端的测试形态完全不同，两条流程都要做，但能力栈完全独立。

前端测试：按项目类型分发到 Web 自动化（Playwright）、小程序自动化（真机云测）、通用 Automator，把 test-cases.md 转成可执行脚本。

后端测试：这是最值得展开的部分。整条链路是：

  1. specworker-api-test Skill 从 P2 阶段的 api_test_cases.md 自动生成 Node.js 测试脚本。
  2. 收集环境变量 + 执行。
  3. 失败时 specworker-api-test-debugger SubAgent 接管：把失败请求的 trace-id 提取出来 → 自动去 CLS 拉相关日志 → 去 MySQL 查相关数据行 → 去 Redis 看相关 key 状态 → 产出“失败根因 + 建议修法”的诊断报告。
  4. 诊断报告附给 implementation Agent 修代码，修完自动重跑验证。
  5. 重跑通过则销案；同一用例 3 轮诊断仍未修通则 STOP 并标注“需人工介入”。

反思：api-test-debugger 不解决“日志根本没打”的情况——遇到这类必须回退到 specworker-debugging 让人介入。

P5 部署：前端 git 规范 / 后端 deploy.md 动态解析（双流程）

核心问题：部署阶段是质量最难兜底的一格——一旦上线，错误代价从“整改返工”变成“线上事故”。纪律层评分门槛 total_score ≥ 95，最多 3 轮整改。

前端 P5：

  1. git 提交规范：commit message 必须符合 <type>(<scope>): <subject> 格式。
  2. 测试环境部署 + 状态轮询：推送后按知识库的 CI/CD 规范触发部署，轮询等待最多 10 分钟。
  3. 部署产物落盘：产出 {change_dir}/frontend/deploy.md。

后端 P5：

  1. deploy.md 任务化解析：把 deploy.md 解析成三类任务列表：数据库变更类、流水线发布类、其他类。
  2. SQL 变更强制用户确认：任何数据库 DDL/DML 变更，不允许 AI 自动执行，必须由用户显式 yes/no 才能跑。
  3. 流水线发布 + 轮询：调发布接口后轮询状态，失败时自动拉取 K8s pod 日志。

反思：P5 不解决“灰度策略”和“回滚决策”——这两件事必须 SRE 拍板，AI 只负责“按计划执行”和“失败时报错”。SQL 强制确认看似拖慢节奏，但这是我们踩过线上事故后立的硬规矩——部署阶段宁可慢，不可错。

P6 归档：changes-sync + knowledge-sync + specs-generator

核心问题：归档是最容易被跳过的一格——代码合进去了，测试过了，部署上线了，谁还有耐心写归档文档？但跳过归档的代价是：下次同类需求来时，AI 找不到上次的解法，从零开始；线上踩过的坑，下次照样会踩。归档不是“留资料”，是“复利”。

我们的三件套强制跑：

  1. changes-sync：把 git 实际改动跟 design / planning 描述对齐，确保“代码做了什么”和“文档说要做什么”完全一致。
  2. knowledge-sync：把当前 change 里“被反复用到的设计、踩过的坑、约定的契约”沉淀进项目级知识库 specs/。
  3. specs-generator：根据本次 change 的 delta-spec.md（ADDED / MODIFIED / REMOVED / RENAMED 四类标记），增量合并到 specs/[module]/spec.md 对应章节。

反思：Delta Spec 是 P6 的灵魂——它不直接复制本次 change 的全部文档进 specs，而是只标记“哪些是新增的、哪些是修改的、哪些是删除的”，避免知识库膨胀。

管线上的可监测性：可追踪 → 可回溯 → 可度量

核心问题：AI 驱动研发和传统研发最大的差别，是执行主体从人变成了 AI——每一步出了问题，追责到谁？

如果没有可监测性，AI 跑完一段告诉你“我做完了”，你既无法验证它真的做完了、也无法回放它是怎么做的、更无法度量它消耗了什么资源。我们把可监测性拆成三个维度：

可追踪：把 AI 自述的“我做完了”变成机器能读的证据。通过 .phase-metrics.jsonl（每个阶段一行 JSON 记录）、evaluation.md（独立评分）、Report API payload 三件套实现。

可回溯：AI 跑挂的时候，能从“结果异常”自动收敛到“根因是什么、该怎么修”。UI 还原偏差走截图比对 + 五轮修正；API 测试挂了走 trace-id → CLS → MySQL → Redis 的 SOP 检索路径；跨阶段重试浪费走 summarize-report 组装结构化报告。

可度量：让“这套 AI 体系到底好不好用、贵不贵”从感觉变成数字。通过 Token/成本、耗时、重试/失败率、代码改动量四类指标实现。

反思：SOP 写死，不让 Agent 自由发挥——这条 SOP 是把“人工排查的隐性经验”显式化为 Agent 的检索路径。

纪律层：每道工序硬编码门禁，AI 不可绕过

核心问题：AI 能力这么强，为什么还需要这么严的纪律管控？因为 AI 有一个坏毛病——它会“偷懒”。

它会跳过测试直接写代码、遇到 bug 猜一个修复方案碰运气、没验证就说“已完成”、自己给自己打高分。这些不是偶尔发生，是 AI 的天然倾向。所以我们针对 AI 的每一种“偷懒模式”，设了对应的纪律防线：

  • 写代码想跳过测试？TDD 纪律强制你先写测试再写代码。
  • 遇到 bug 想猜着改？Debug 纪律强制你先做根因分析。
  • 想说“应该做完了”？Verify 纪律要求你必须拿出运行证据。
  • 代码偏离了设计方案？Review 纪律逐项比对。
  • 最后交付时自己打分可能偏高？Evaluate 纪律用独立 SubAgent 来评。

五道防线，每一道拦截 AI 的一种偷懒模式。而且这些纪律不是“建议遵守”，是硬编码到管线里的——强制嵌入、每道都是门禁、触发否决直接阻断。

轨道 2：线上运营

核心问题：代码上线后告警了，AI 怎么稳定修回去？

研发管线管“上线前”，线上运营轨道管“上线后”——研发态与运营态共用同一份知识库、同一套 trace-id 检索 SOP、同一套评分门槛，是 Harness 在不同输入入口上的对偶设计。

整条链路是 7 步：

  1. 告警触发/自动巡检：监控告警 + 周期性巡检双源进入。
  2. 清洗合并：去重、按调用链关联同源告警。
  3. 采集证据：按预定 SOP 自动拉 trace-id 链路、CLS 日志、MySQL 数据行、Redis key 状态、相关变更记录。
  4. 根因分析：AI 给出“假设 + 证据 + 影响面”三件套，不允许只给“猜测”。
  5. AI/人工修复：低风险的 AI 直接出 PR；高风险的必须人工签字。
  6. 回归验证：对原失败 case 重跑一次。
  7. 归档：把“这次告警怎么挂的、怎么修的”回写知识库。

反思：为什么把它单独一条而不是塞进管线？ 因为研发管线是“主动驱动”（人提需求 → AI 执行），运营轨道是“被动驱动”（系统报警 → AI 响应）；两条轨道的输入入口、节奏、纪律点都不一样。但只要共享知识库，它们就是同一套 Harness 的两面。

知识库：AI 的长期记忆

核心问题：没有知识库，每次新需求来 AI 都要从零理解一遍上下文，所谓“复利”也就无从谈起。

我们的做法是把知识库做成两件事：一套规范 + 一套运作逻辑。

知识库规范：构成/组织/内容要求

两套知识库并存，各管一段：

  • 项目级 specs/ ：沉淀产品长期资产——业务规则、技术架构、接口契约、术语表。粒度按“产品/服务”切。
  • 变更级 knowledge-spec/（change 目录） ：每次需求迭代独立一个目录，沉淀本次变更的全部文档。粒度按“change”切。

两者通过 index.md 索引互通。

5 类目录分层设计：business/（业务规范）→ frontend/ + backend/（端侧技术规范）→ common/（接口契约）→ changes/（需求演进），加 archives/ 与 issues/ 两个辅助目录。

依赖严格单向向下：business/ 不依赖任何端，frontend/、backend/ 依赖 business/，common/ 由 trpcgo-protocol 派生，changes/ 可引用上面所有层。

Spec 质量与粒度设计：

  • 粒度三级递进：顶层概述 → 模块/服务 spec → 子页面/接口详情。
  • 两级查找，禁止全局通配：任何检索必须 index.md → 相关 spec 两跳命中。
  • 单一事实来源：术语只在 glossary.md 定义一次，接口只认 .proto。
  • 章节结构统一，让模型“按固定位置取信息”。
  • 原位增量更新，以 Git diff 审查。

知识库三阶段运作：初始化 → 演进 → 治理

阶段一：存量初始化——把家底盘清楚。从历史文档、代码、线上产品同时取证，做信息采集、分析、生成、内容验证四步。但不能完全靠 AI——存量里有大量“过时但还能跑”的代码，必须由熟悉业务的人去确认、剔除。

阶段二：迭代演进——每次归档都强制更新。P6 阶段强制跑三件套：changes-sync、knowledge-sync、specs-generator。没跑完三件套，下一个 change 的 P1 起不来。

阶段三持续治理待实现。

上下文注入：session-start 钩子 + 两级查找 + token 双层结算

核心问题：上下文注入不是“塞得越多越好”，而是“每一步只送它该看见的那一片”。

我们落成四个工程动作：

  1. index.md 两级查找（禁止全局通配） ：每个 Skill 的前置检查里都有一条“禁止使用 **/*.md 全局通配”。
  2. token 双层结算（父 Skill / SubAgent 独立计费） ：一个反直觉洞察——SubAgent 并非节省上下文的银弹，而是另一份独立计费的开销。
  3. SubAgent 优先 git diff，避免读全文件：把“优先读 diff”作为所有 SubAgent 的统一约定。
  4. 控制文件长度，避免出现超长文件。

回头看：协议层定契约、管线层定阶段、纪律层堵漏、再加一份长期记忆——四件事看似分散，但都在做同一件事：把“AI 看不见的东西”挪到它一定看得见的地方。

探索中沉淀的工程原则

本段核心问题：在 Harness Engineering 的实践中，我们总结出了哪些可以复用的工程原则？

走完这一遭，最大的判断只有一句：AI Coding 的工程化，本质是对“不确定性”的系统治理。 模型本身是概率的、注意力是衰减的、上下文是会被压缩的、输出是会自我合理化的——这些都不是 bug，是 LLM 的“物理常数”。Harness Engineering 之所以成立，恰恰是因为我们承认这些常数无法消除，只能在它周围搭一套确定性的骨架兜住它。

原则 1：AI 工作流编排，追求确定性而非自由发挥

采用 Fixed Flow 结合对抗式、程序化质量门禁。具体落到四件事：

  • 状态持久化设计：每个步骤的输入、输出、状态都写到一个共享的持久化文件。
  • 程序化门禁检查：对关键步骤及产出物进行程序化硬检查，一旦不通过，需要退至上一环节再跑。
  • 输入质量要求：通过标准化模板约束输入质量。
  • 对抗式纪律：行为铁律 + 评估独立 + 自我合理化警报。

反思：让 AI“自由发挥”听起来很美，但工程上的代价是把整条流水线的不确定性叠加给下游。Fixed Flow 不是限制 AI 的能力，是把它的能力锚定在可验证的轨道上。

原则 2：上下文控制

当上下文过长时，CodeBuddy 会对上下文进行压缩，影响 SKILL 效果。 落地动作：

  • 将重要的规则固化到 rules 中。
  • 无关联的任务使用新的 session 执行。
  • SKILL 按需读取文件，避免全量扫描。
  • 控制文件长度。

反思：上下文不是“窗口”——是稀缺资源。真正决定 AI 表现的不是窗口大小，是窗口里关键信息的密度。

原则 3：Token 成本优化

  • 合理选择模型，按任务要求选择匹配的模型。
  • 控制上下文长度。
  • 如无必要，不要在一个 Session 一直对话。

反思：便宜的模型 + 紧凑的上下文 + 干净的会话，常常比“最强模型 + 一锅炖”效果更好——任务匹配度才是第一性问题。

原则 4：将确定性过程用脚本实现

大语言模型具有随机性，对于确定性强、可重复执行的流程，沉淀为脚本。我们使用 SKILL 而不是 MCP，因为 MCP 会固定占用上下文长度、工具不可灵活选配、数量过多会影响模型效果。

反思：确定的事用脚本、不确定的事用 AI——这条边界划清楚了，AI 的价值才能被放大。

常见问题与应对方案

本段核心问题：在实践 Harness Engineering 的过程中，哪些问题反复出现？我们是如何解决的？

下面 4 个问题是反复踩到、并已经形成标准应对的——它们之间不是孤立的，而是同一个底层事实（LLM 是概率模型）在不同环节的不同表现。

问题 1：AI 指令遵循

问题：AI 易跳过关键步骤，导致流程偏离；质量门控未严格执行。

原因：上下文压缩导致信息丢失；LLM 注意力衰减，远距离信息关注度下降。

解决方案：

  • TODO 文件驱动：核心步骤写入 TODO 文件，AI 逐条执行并更新进度。
  • 拆解 SubAgent：降低单次上下文，提高模型指令遵循表现。
  • 渐进式披露：按需加载上下文。

反思：AI 不“听话”很多时候不是它不想听，是它真的没看见。所以治理指令遵循，不是反复强调“AI 你要听话”，是把指令搬到 AI 一定看得见的地方。

问题 2：需求歧义

问题：由于自然语言的模糊性，需求文档天然存在歧义，AI 易误解需求。

解决方案：

  • 多轮澄清机制：执行前，强制 AI 提问，确认后再动手。
  • 结构化需求规范：需求统一转为 GIVEN-WHEN-THEN 格式。

反思：需求歧义不是 AI 的问题，是自然语言的物理属性。与其指望 AI“理解力更强”，不如把需求写成它没法误解的格式。

问题 3：设计稿还原

问题：AI 对 Figma 设计稿 UI 还原效果一般，布局/切图/样式易失真。

解决方案：

  • 引入中间产物（html + css + 切图）：AI 更擅长基于结构化中间产物渲染。
  • 多轮 UI 校准迭代：截图对比，逐步逼近设计稿。

反思：当 AI 在 A → B 一步到位很差时，在中间插一层 A → C → B——让每一段都是 AI 真正擅长的转换。

问题 4：如何保证产物的可靠性

问题：LLM 是概率模型且存在幻觉，每次生成的代码会有差异。

解决方案：

  • 自验证循环：编写 → 运行 → 测试 → 修复 → 再验证。
  • 单元测试驱动开发：先生成测试用例，再生成实现代码。
  • 审查 Agent 门控：关键产物经交叉评审，达标后再交付。

反思：可靠性不是“让 AI 一次写对”，是“承认它写不对，但用机制兜住”。自验证循环、UTDD、审查 Agent——这三件事的共同点是：没有一个相信 AI 单点输出，全都靠“输出 + 验证”双轨。

未来挑战：地图刚画出来的地方

本段核心问题：Harness Engineering 的实践还有哪些未解难题？下一步应该往哪个方向走？

走到这里，我们越来越清楚一件事：Harness Engineering 不是一套“先有理论再去实现”的工程方法——它是先在 Anthropic、Codex、我们这种一线团队的踩坑里冒出来，再被回头命名、回头总结的。这套体系的价值，不在于“我们做对了多少”，而在于我们承认还有哪些没做对。

具体来说，至少有六件事还在路上：

  1. 评分机制和下游真实消耗的耦合还没打通：P2 得 90 分但 P3 翻车的反馈回路目前只在 docs 里写了规则，scorer 仍按“只看本阶段产物”打分。
  2. 知识库的自动治理还在演进：changes-sync / knowledge-sync / specs-generator 三件套解决了“如何归档”，但“归档进去的东西如何老化、如何淘汰”还没有机制。
  3. 运营轨道的告警闭环还在补全：主链路跑通了，但跨项目的 SOP 复用、知识库共享还在试。
  4. 多模型评估、跨项目知识迁移、Agent 自我进化：这些更前沿的方向，我们也只是站在了门口。
  5. 业务复杂度高的历史项目如何适配进来：老项目的历史积淀往往是“水下的冰山”，目前还得靠熟悉业务的同学陪跑做大量初始化。如何把这部分“陪跑成本”压下来，是我们现在最头疼、也最值得继续投入的一格。
  6. AI 测试的可靠性挑战还在持续探索：AI 生成测试用例仍可能覆盖不足、断言偏弱。下一步需要补齐测试用例质量评估、反例生成、覆盖率与业务风险映射，以及“测试本身是否可信”的二次评审机制。

这一路走下来，我们没有发明任何新概念——把头部公司在 Harness 这一层踩出来的工程语言，一层一层落到我们自己的体系里。但这恰恰是 Harness Engineering 这件事最有意思的地方：它不是一套终极框架，而是一张被现实不断逼着补全的地图——每跑一次真实业务，地图就被推进一格。

我们刚走到地图刚画出来的地方，前面还有很大一片空白。

实用摘要与操作清单

本段核心问题：如果你想在自己的团队落地 Harness Engineering，最关键的几个抓手是什么？

上手三板斧

  1. 先卡住需求入口：从 TAPD/Jira 拉取需求作为唯一事实来源，所有 AC 必须可测，测试用例与需求同源。这是防止下游跑偏的第一道闸。
  2. 再钉死设计契约：把 design.md 从“给人读的说明”改成“机器可读的契约”——接口签名、字段必填、状态机全部结构化，P3 实现和 code-reviewer 都拿同一份比对。
  3. 最后建立反馈闭环：每个阶段结束必须有独立评分（≥95 才能进下一阶段），失败时必须能自动回溯根因（trace-id → 日志 → 数据库 → Redis）。

纪律底线三条

  • TDD 强制：写代码前必须先写测试。
  • SQL 变更强制人工确认：不允许 AI 自动执行 DDL/DML。
  • P6 归档三件套强制跑：changes-sync + knowledge-sync + specs-generator 没跑完，下一个 change 的 P1 起不来。

成本控制两招

  • 优先 git diff，避免读全文件：所有 SubAgent 统一约定。
  • token 双层结算，父 Skill / SubAgent 独立计费：别把 SubAgent 当作节省上下文的银弹。

一页速览（One-page Summary）

维度 核心要点
Harness 定义 Agent = Model + Harness。不是教模型“怎么回答”，而是设计模型“怎么工作”。
为什么需要 AI 写得越快，研发整体没同步提速。根因是本质复杂度没减、瓶颈转移、隐性约束看不见。
核心体系 2 条轨道（研发端到端交付 + 线上运营）+ 1 个长期记忆（知识库）。
协议层 AI 每一步的输入输出必须符合契约，格式确定、内容可校验、历史可追溯。
管线层 P1→P6 标准化工序：需求拉取→设计契约→实现+code-review→测试自愈→部署门禁→归档复利。
纪律层 TDD、Debug、Verify、Review、Evaluate 五道防线，硬编码为门禁，AI 不可绕过。
知识库 项目级 specs/ + 变更级 change 目录，两级查找禁止全局通配，SSOT 单一事实来源。
可监测性 可追踪（证据）、可回溯（根因）、可度量（成本/耗时/重试率）三维度。
四条原则 Fixed Flow 追求确定性、上下文控制、Token 成本优化、确定性过程用脚本。
待解难题 评分与下游消耗耦合、知识库自动治理、老项目适配、AI 测试可靠性。

常见问答（FAQ）

Q1：Harness Engineering 和 Prompt Engineering 有什么区别？

Harness Engineering 关心的是 Agent 完成整个任务的工作环境，而 Prompt Engineering 关心的是单次调用的输入输出质量。前者是后者的上一层，两者不是替代关系，而是叠加。

Q2：为什么 AI 写得越快，研发整体却没同步提速？

因为研发从来不是“写代码”这一个环节。AI 砍掉的是附属复杂度（语法、工具），但本质复杂度（概念结构、需求可变性）一分没少。局部加速只会让瓶颈从“写”转移到“理解、对齐、验证、沉淀”。

Q3：P6 归档为什么这么重要？

跳过归档的代价是：下次同类需求来时，AI 找不到上次的解法，从零开始；线上踩过的坑，下次照样会踩。归档不是“留资料”，是让知识产生“复利”。

Q4：为什么要强制 SQL 变更人工确认？

这是我们踩过线上事故后立的硬规矩。数据库变更风险极高，AI 自动执行 DDL/DML 一旦出错，代价从“整改返工”直接变成“线上事故”。部署阶段宁可慢，不可错。

Q5：SubAgent 不是能节省上下文吗？为什么还要强调 token 双层结算？

一个反直觉的洞察：SubAgent 并非节省上下文的银弹，而是另一份独立计费的开销。它每读一遍全文件，主 Agent 端毫无感知，但成本照样产生。所以必须优先 git diff，避免读全文件。

Q6：老项目怎么接入这套 Harness 体系？

老项目的历史积淀往往是“水下的冰山”——过期文档与现网行为对不上、废弃接口没人敢动。目前还得靠熟悉业务的同学陪跑做大量初始化，用 AI 跑出初稿、人工剔过时、人工补关键约束，三步下来才能形成可用的初版。

Q7：AI 测试用例本身怎么保证质量？

当前测试左移、E2E、API 测试和失败自愈已经能拦住一部分问题，但 AI 生成测试用例仍可能覆盖不足、断言偏弱。下一步需要补齐测试用例质量评估、反例生成、覆盖率与业务风险映射，以及“测试本身是否可信”的二次评审机制。

Q8：这套体系适合什么规模的团队？

这套体系本身是从一线实战中长出来的，无论团队大小，核心思路——定契约、立规矩、建知识库、做监测——都可以按需裁剪。小团队可以先从“需求入口卡住 + 设计契约钉死 + 独立评分门禁”三板斧开始，不必一上来就铺满全流程。