Harness 工程：把 AI 关进笼子

模型决定了智能体的上限，Harness 决定了智能体的下限。没有 Harness 的大模型只是一台发动机，经过 Harness 工程化的智能体才是一辆能上路的车。

---

一、Harness 到底是什么

Agent = LLM + Harness。

大模型提供推理的"大脑"，Harness 提供执行、记忆与安全保障的"身体"。

这个词原意指"马具"——骑手用缰绳和鞍具把烈马的奔腾之力化为可控的前行。Harness 工程干的是一样的事：不是让 AI 跑得更快，是让它跑得对。

打个比方：你让 AI 帮你转账。LLM 正确识别了金额和收款人——这没问题。但以下问题 LLM 解决不了：

• API 返回超时了，重试？重试几次？
• 参数没按 API 要求的格式构造怎么办？
• 网络抖动导致重复扣款谁来兜底？
• 这个操作本身有没有权限？

这些全归 Harness 管。模型管"想什么"，Harness 管"怎么安全地做"。

---

二、Harness 的五脏六腑

一个完整的 Harness 系统可以拆成 五大核心子系统 + 两大基础保障：

子系统	干啥的	类比
运行时引擎	驱动 Agent 的主循环：感知→推理→决策→执行→学习	心脏
工具层	管理所有外部 API、数据库、文件系统调用的注册、验证、隔离执行	手脚
记忆子系统	工作记忆/短期记忆/长期记忆三层，带向量检索	大脑皮层
输出治理	LLM 输出格式校验、语义验证、幻觉检测、安全过滤	免疫系统
编排引擎	复杂任务分解、多 Agent 协作、工作流管理	神经中枢
安全层（贯穿）	权限梯度管理、沙箱隔离、注入防护	防火墙
可观测性层（贯穿）	日志、追踪、指标三位一体	黑匣子

下图是核心架构的简化视角：

接入层（CLI / Web API / SDK）
        │
编排层（任务分解、多Agent协调）  ← 简单任务可省略
        │
智能体核心层 ──┬── 运行时引擎（主循环）
              ├── 工具层（注册/执行/隔离）
              ├── 记忆子系统（工作/短期/长期）
              └── 输出治理（校验/幻觉检测）
        │
横切关注点 ── 安全 · 可观测性 · 存储

---

三、四条铁律，每条都是线上事故堆出来的

3.1 约束优先——先画圈，再撒野

不是先想"AI 能干什么"，而是先定义"AI 绝对不能干什么"。

真实案例：AI 顺手改了一个不在需求范围内的导出逻辑，review 没发现，上线后导出的 Excel 列名全是错的。

从那以后，"不做什么"变成了强制约束，写在每个 Skill 的禁区栏里：

• 不引入项目技术栈以外的依赖
• 不顺手重构不在任务范围内的代码
• 不在没有 PRD 的情况下凭空拆任务
• 不用 AI 自己说的"没问题"代替人手验证

3.2 可验证——每一步都要能回放

传统软件的代码可以事先审查。Agent 的行为是运行时动态生成的（即生即灭的"暗码"），可验证性是 Harness 对抗暗码的核心武器。

三层递进：

1. 操作日志：记录了啥、调了啥、成了没
2. 执行追踪：步骤间的因果链条，带 trace_id 串联
3. 可重放：相同输入 → 相同输出，做不到就是非确定性 bug

3.3 渐进信任——别一上来就全自动

六档信任模型，逐级放开：

信任等级	含义
Manual Only	完全人工操作
Approve Always	每步都审批
Approve Once	整个任务审批一次
Ask First	关键操作前问一下
Auto with Notification	自动执行 + 发通知
Full Trust	完全撒手（别在生产环境用）

先把 Ask First 跑稳，再根据可观测数据逐步放权。信任不是给的，是挣的。

3.4 故障假设——每一步都可能挂，提前想好怎么兜

AI 写的代码有个特点：第一版最工整，改到第三版开始"改不动了"。加上需求来回变、AI 识别不了变更范围，单点故障指数级放大。

Harness 层的核心价值：超时兜底、智能重试、降级策略、检查点恢复。不是消灭错误，是让错误不扩散。

---

四、实战落地：8 个 Skill 串起全链路

在企业级前端项目上的真实实践，8 个 Skill 覆盖需求→设计→开发→测试→验收→Bug修复的完整闭环：

Skill	职责
product	需求评审 → 任务拆解
api	接口文档 → 类型定义 + 请求函数
ui	设计稿 → 组件代码
page	组件 + API → 完整页面
test	单元测试
qa	QA 用例扫查
review	Code Review + 规范回写
bugfix	Bug Case → 根因定位 → 修复

依赖链一目了然：

product（需求拆解）
    │
    ├──▶ api（接口对接）     ├──▶ ui（设计还原）
    │                              │
    └──────────┬───────────────────┘
               ▼
          page（页面组装）
               │
               ▼
          test（单元测试）
               │
               ▼
          qa（QA 扫查）
               │
               ▼
          review（Code Review）
               │
               ▼
          bugfix（Bug 修复，独立触发）

核心落地机制

所有产出收进一个目录 spec/：

spec/changes/user-management/
├── .spec.yaml          # 进度追踪（每个skill状态：pending→completed）
├── product.md          # 需求评审 + 任务列表
├── api.md              # 接口契约 + 类型定义
├── ui.md               # 组件列表 + 还原说明
├── page.md             # 数据流 + 状态说明
├── tests.md            # 测试结果 + 覆盖率
├── qa.md               # 用例对照 + 通过率
└── review.md           # 结构化审查报告

进度不用问人，打开 .spec.yaml 看一眼就知道卡在哪。Review 时所有上下文全在一个目录里，不用追着问"接口文档发哪了"。

四个底座机制

1. SDD 闭环（规范驱动开发）：CLAUDE.md 定义规范 → AI 按规范生成 → Code Review 验证符合度 → 发现违规补规范。每次 AI 跑偏都是发现规范漏洞的机会。
2. 不清晰就停：需求模糊、接口缺字段、Case 信息不全——停下来问，不许猜。
3. 文档驱动防幻觉：Tailwind/React/useRequest 等关键依赖强制先读 Context7 官方文档再回答，代码从真实文档锚定，不从模型训练数据里瞎编。
4. spec 单目录收拢：进度可追踪，上下文不丢失，Review 时一眼看清全貌。

常见坑速查表（bugfix Skill 为例）

现象	原因	处理
修完一个 Bug 引入另一个	只看了 happy path	回三步检查法里"边界"逐条过：空值、权限、并发
顺手重构了无关代码	忍不住"顺便优化"	改前把"不做什么"念一遍，多一行都不写
改了好几个文件但根因没找到	在症状层面修修补补	退回定位：一句话说清根因了吗？说不清继续查

---

五、Harness 为什么比模型更重要——数据说话

OpenAI Codex 的百万行实验

OpenAI 团队 5 个月内用纯代码生成方式构建了一个内部产品，代码规模约 100 万行，零人工代码编写。3~7 名工程师驱动 Codex，平均吞吐量 3.5 PR/人/天，整个项目以"1/10 的人工耗时"完成，单个 Codex run 可无人值守连续工作 6 小时。

关键发现：工程重心从"写代码"转向"为 Agent 设计可读、可验证、可枚举的环境"。

LangChain Deep Agents 的纯 Harness 优化

在 Terminal Bench 2.0 上的实验，完全不加模型能力，只优化三个 Harness 层级：

• 失败检测：每个 Agent 步骤后检查是否真正完成预期操作
• 执行隔离：每次尝试独立沙箱环境，防止失败污染后续
• 多轮验证：Agent 提交答案前先自检，失败则重试

结果：通过率从 52.8% → 66.5%，排名从 30 名开外进入全球前 5。没有换模型、没有微调、没有提示词优化。纯工程改进。

量化收益参考（企业级实践）

维度	指标
效率提升	7~8 倍（CRUD 开发从数天缩短至数小时）
质量改善	规范符合率 +25%，缺陷率降低 50%
人力优化	重复劳动减少 30%，单开发者产出放大 2~3 倍

---

六、落地的 6 个要素

从 PPT 的总结来看，Harness Engineering 不是单一工具，而是一套闭环体系：

要素	解释
Rule	编码规范与设计约束，定义行为标准和质量红线
Skill	高频操作与最佳实践封装，可复用的能力组件
Sub Agent	多智能体角色分工，模拟真实研发团队协作
Workflow	协作流程编排，定义 Agent 间交互与执行顺序
Scripts	自动化脚本执行，编译/测试/扫描门禁保障
MCP	工具链集成协议，无缝连接现有 DevOps 生态

闭环逻辑：规范定义 → 流程编排 → 自动化执行 → 质量反馈 → 持续迭代。

---

七、从哪开始？

新手不要一上来就铺 8 个 Skill。建议路径：

1. 先做一个 Skill——挑最痛点。需求不清做 product，UI 还原差做 ui，Bug 反复出做 bugfix。一个跑稳再扩。
2. 用 Markdown 写，放 .claude/skills/ 下。结构就三段：触发条件、执行步骤（标注决策点）、常见坑速查表。
3. 建一个单目录收产出，哪怕只收两三个文件，也比到处散落强。进度用 yaml 标，别靠脑子记。
4. CLAUDE.md 是约束来源——Skill 管流程，CLAUDE.md 管规范。AI 跑偏了先判是哪个漏了。
5. 第一个版本别追求完美，跑起来 review 自然会告诉你漏了什么。

单项目跑稳之后，再考虑多 Agent 并行——Skill 是基础，多 Agent 是加速器，顺序不能反。

---

一句话总结

Harness 工程不是让 AI 更聪明，而是让 AI 更可靠。把 AI 关进流程的笼子里，不是削弱它，是让它真正可用。

模型决定了你能跑多快，Harness 决定了你能不能跑到终点。

---

参考资料：

• 《智能体 Harness 工程指南》（yeasy, 2026）
• OpenAI Codex: “Harness Engineering: Leveraging Codex in an Agent-First World”（Ryan Lopopolo, 2026）
• 企业级 AI Coding 的 Harness 工程实战（2026）