# Harness 工程（三）：落地实践指南


>本系列共三篇：
1. harness工程（一）：概念与来源 
2. harness工程（二）：六层架构详解 
3. **落地实践指南**（本篇）：两条战线上的具体操作


----

前两篇解决了"是什么"和"由什么构成"。这一篇只回答一个问题：**明天开始，具体做什么？**

按第一篇的两类场景，实践分两条战线：


- **战线 A：使用者的 harness**——你用 agent 干活（vibe coding、文档生成），怎么控制产出质量；

- **战线 B：开发者的 harness**——你在造一个 agent 产品，怎么让整体效果稳定可靠。


两条战线共享同一个心法，先从心法说起。


----

## 〇、一个贯穿始终的心法


Mitchell Hashimoto 的原话：

>**Agent 每犯一次错，就工程化一个机制，让它永远不再犯这个错。**


这是全部实践的最小单元。它意味着工作重心的根本转移：


|旧反应|新反应|
|:-:|:-:|
|在对话里说"不对，应该用 XX 命令"|把正确命令写进 AGENTS.md|
|手动改掉 agent 生成的错误代码|加一条 lint 规则，让错误在 commit 时被拦下|
|下次开会时提醒"别忘了验收"|把验收标准写成测试用例，进 CI|
|跟人吐槽"agent 又幻觉了个 API"|给 agent 装上查官方文档的工具（如 Context7）|

**对话里的纠正是消费，环境里的固化是投资。** 每次纠错都问自己一句：这个教训能不能变成一个文件、一条规则、一个脚本？


----

## 战线 A：使用者的 harness（个人落地）


### A1. 先写一个"活的" AGENTS.md / CLAUDE.md


不要追求一步到位，按 Hashimoto 的方式**增量生长**：


1. 初始只写三样东西：项目是什么、怎么跑起来、怎么验证（测试/lint 命令）；

2. 之后每当 agent 犯错，追加一条对应规则；

3. 定期清理：删除已失效的规则，把长出来的部分拆到 `docs/` 子文档，主文件保持"地图"形态（参考 OpenAI 的 ~100 行原则）。


反面教材：一上来写 2000 行"百科全书"。结果是挤占上下文、规则互相稀释、很快腐化成没人维护的废墟。

### A2. 给 agent 装上"眼睛"：自验证回路


Hashimoto 实践中最重要的一条心得：

>如果你给 agent 一个验证自己工作的方法，它多半会自己修好错误，还能防止回归。


按场景给 agent 配验证手段：


|场景|自验证手段|
|:-:|:-:|
|写代码|测试命令 + lint + tsc，写进 CLAUDE.md 让 agent 做完必须跑|
|写前端/UI|截图脚本、浏览器工具，让 agent 对比预期效果|
|写文档/报告|给一个检查清单（结构、字数、必含要点），让 agent 自查|
|数据处理|给校验脚本（行数、格式、边界值抽查）|

关键转变：**验收标准前置到任务开始时给出**，而不是做完后由你人肉检查。

### A3. 任务切分与会话策略


来自 Hashimoto 六阶段实践中被反复验证的三条：


1. **把会话拆成清晰、可执行的小任务**，别指望一个超长会话"画出整只猫头鹰"；

2. **模糊需求拆成"规划会话 + 执行会话"**：先让 agent 出方案、你审方案，再开新会话执行——上下文干净，跑偏率骤降；

3. **知道什么时候不用 agent**：用 agent 做它大概率做砸的事是最大的时间浪费。摸清能力边界本身就是 harness 的一部分。


### A4. 推理预算的"高-中-高"分配


如果所用的工具支持调整思考深度（thinking 档位），按阶段分配：


- **规划阶段 → 高推理**：充分理解问题、拆好任务；

- **实现阶段 → 中推理**：执行是体力活，省下预算；

- **验证阶段 → 高推理**：捕获错误的最后一道智力防线。


实验数据显示这个"三明治"策略（66.5% 得分）显著优于全程高推理（53.9%）——预算花在两头，回报最高。

### A5. 个人的门禁：别让烂产出离开你的视线


即使是个人项目，也值得有最轻量的门禁：


- **代码类产出**：`git commit` 挂钩子跑 lint + 测试，不合格不许入库；

- **文档类产出**：建立自己的"出库检查清单"——事实抽查、链接有效性、格式一致性；

- **对外动作类**（发邮件、发消息、发布）：**永远人工终审**。这是底线，不是可选项。


### A6. 让 agent 在后台跑起来


Hashimoto 的第 3、4、6 阶段给出了一条渐进路线：


1. **收工前 30 分钟**：启动 agent 做深度调研、issue 分类，第二天早上拿报告"热启动"；

2. **外包稳赢任务**：把 agent 几乎必做对的任务完全托管，自己做需要深度思考的事；

3. **永远有一个 agent 在跑**：空闲时问自己"现在有什么事可以交给 agent？"。


配套的两条纪律：


- **关掉 agent 的桌面通知**。上下文切换极其昂贵——打断权必须握在人手里，你在自然间隙去看它，而不是它随时打断你；

- **后台任务也要 harness**： unattended 的 agent 更需要写入权限收敛、产出落盘、完成后报告，而不是自由发挥。


----

## 战线 B：开发者的 harness（造 agent 产品）


### B1. 从 LangChain 公式出发做清单


**Agent = Model + Harness**。模型选型之外，逐项过一遍 harness 清单：


|部件|自检问题|
|:-:|:-:|
|系统提示词|规则是否都来自真实失败案例？|
|工具集|工具描述是否足够清晰？工具是否少而精（工具过多反而降性能）？|
|文件系统|agent 的工作成果是否落盘持久化？能否跨会话续接？|
|沙箱|生成的代码在哪里执行？权限边界是什么？|
|上下文管理|有没有压缩策略？超长工具输出会不会污染上下文？|
|记忆|跨会话知识存在哪？启动时注入什么？|
|权限|危险操作（删文件、发请求、写生产）是否需要审批？|
|编排|有没有子 agent 拆分？模型路由/降级策略是什么？|

### B2. Agent Loop 的工程化要点


核心循环（模型调用 → 工具执行 → 结果回填 → 判断继续）之外，必须配齐：


- **模型路由**：按任务类型选模型——文本→DeepSeek V4 Flash，编码→GLM-5.2，多模态→SeedDance 2.5。路由是成本与质量的换挡逻辑；

- **模型降级**：主模型超时/额度耗尽时自动切 fallback（如 GLM-5.2 → DeepSeek V4 Pro）。降级策略要在上线前演练过，而不是出事时现写；

- **子 agent 派发**：大任务拆分并行，关键是**上下文隔离**——每个子 agent 只看自己需要的部分；

- **错误恢复**：文件编辑失败 → 回滚 worktree → 重试。恢复路径必须确定性，不能靠"再 prompt 一次试试"；

- **防死循环**：追踪每个文件的编辑次数（LoopDetectionMiddleware 思路），超阈值注入"重新审视你的方案"，或硬中断升级给人类。


### B3. 长时程任务：Ralph Loop + 进度文件


当前模型的通病是过早停止、长任务丢连贯性。对策组合：


1. **进度持久化**：agent 把进度写入 progress.json / 执行计划文件，每次迭代落盘；

2. **Ralph Loop**：hook 拦截模型的退出尝试，对照目标检查——没完成就在干净上下文中重新注入原始提示词，继续干；

3. **执行计划分级**（OpenAI 做法）：小改动用轻量临时计划；复杂工作用带进度和决策日志的执行计划，检入仓库版本管理。


OpenAI 的实测效果：单个 Codex 运行在单个任务上连续工作超过 6 小时（通常在人类睡觉时）。

### B4. 门禁体系：三层拦截怎么搭


按第二篇的三层体系落地时的实操要点：


- **Pre-commit**：检查受保护文件、secret 泄露、新增依赖、lint、tsc、test，BLOCK 级；

- **CI**：全量检查 + 架构约束（如"Controller 不得引用 Mapper"）+ 安全扫描，FAIL 级；

- **Review**：逐步 agent 化——本地自审 → 云端 agent 复审 → 循环至通过，人类只处理需要判断力的部分。


两条红线：


- **错误消息即修复指令**：所有 lint/CI 报错信息按"agent 读得懂、照着能修"的标准写；

- **门禁规则必须机械执行**：任何"靠自觉"的规范都会在 agent 的高吞吐下失效。


### B5. 可观测性：先看清楚，再谈优化


最小可用集：


- **Trace**：LangSmith 或 OpenTelemetry，记录每一步的模型调用、工具执行、返回值；

- **Metrics**：成功率、耗时、重试次数、token 消耗、错误类型分布；

- **Cost**：按次/天/模块统计 token × 单价——成本异常往往是行为异常的先兆；

- **Alerts**：错误率飙升、预算超限、疑似死循环，自动告警。


进阶做法（OpenAI）：**让 agent 自己也能查这些指标**——每个 worktree 一套临时可观测栈，agent 用 LogQL 查日志、PromQL 查指标，"启动时间控制在 800ms 内"这类目标才变得可执行、可验证。

度量体系按五类组织：**吞吐量、质量、人类注意力、Harness 健康、安全**。其中"人类注意力"最容易被忽视——当 agent 吞吐超过人类审查带宽时，系统瓶颈是人，不是模型。

### B6. 对抗熵增：持续"垃圾回收"


OpenAI 发现的一个隐性问题：**agent 会复制仓库里已有的模式——包括那些不均匀的、次优的模式**，时间一长必然漂移。他们的解法：


1. 把"黄金原则"编码进仓库（如：优先共享工具包而非手写 helper；在边界解析数据形状，不做 YOLO 式探测）；

2. 定期跑后台 agent 任务：扫描偏差、更新质量评分、自动开重构 PR；

3. 配套 "doc-gardening" agent：定期扫描过时文档，自动开修复 PR。


类比：技术债是高利贷，持续小额偿还远好于复利后集中清算。**人类的品味被捕获一次，然后在每一行产出上持续执行。**


----

## 落地顺序建议


不要试图一次建完六层。推荐的最小阻力路径：

**第 1 周**：建 AGENTS.md（只写项目简介 + 验证命令），开始执行"每犯一次错固化一条规则"；

**第 2~4 周**：给核心任务配自验证回路（测试、lint、截图），把验收标准前置写进任务描述；

**第 1~2 个月**：补门禁（pre-commit 钩子 → CI），把最重要的 3~5 条规范机械化；

**第 2~3 个月**：接 trace 和成本监控，开始量化 agent 的成功率和花费；

**持续**：每周回顾 agent 的失败案例，问"这个错能不能工程化地消灭"。

Harness 工程不是一个大项目，而是一种**持续还债的工作方式**。正如 Hashimoto 所说：他不需要发明什么新词——重要的是那份" earnest effort "（认真的努力），每次看到 agent 做了坏事，就认真让它再也做不了。


----

## 系列回顾


- harness工程（一）：概念与来源 ：**Agent = Model + Harness**；假设一切输出不可信；每犯一次错，工程化一个机制。

- harness工程（二）：六层架构详解 ：L1 引导 / L2 上下文 / L3 规范 / L4 编排 / L5 门禁 / L6 可观测；事前约束 + 事后防线缺一不可。

- **本篇**：两条战线同一个心法——对话纠正是消费，环境固化是投资；从最轻的规则文件开始，让 harness 随失败案例一起生长。

前两篇解决了"是什么"和"由什么构成"。这一篇只回答一个问题：明天开始，具体做什么？

harness工程（三）：落地实践指南

后端

开发工具

架构设计

Harness工程落地实践指南：两大战线——使用者通过AGENTS.md、自验证回路、任务切分提升agent产出质量；开发者聚焦工具集、门禁体系、可观测性。核心心法：将每次agent错误固化为规则或脚本，对话纠正是消费，环境固化是投资，持续以工程化机制减少失败。

文件系统

数据处理

LangChain

路由

Agent

YOLO

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

harness工程（三）：落地实践指南-腾讯云开发者社区-腾讯云

harness工程（三）：落地实践指南

harness工程（三）：落地实践指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐