目录一、Harness 工程到底是什么二、Prompt、Context 和 Harness 有什么区别三、一个完整 Harness 通常包含什么四、从 0 搭建一个代码 Agent Harness第一步建立项目结构第二步编写 AGENTS.md第三步定义一个具体任务第四步加入自动检查脚本第五步规定 Agent 的执行循环五、如何处理长任务六、如何让 Agent 自己发现错误七、Agent 反复犯错时怎么办八、如何建立评估集九、Harness 工程的五条实践原则总结最近 AI 圈出现了一个新词Harness Engineering通常翻译为 Harness 工程也有人称为“驾驭工程”。这个词听起来很新但它解决的问题其实非常现实为什么同样使用 GPT、Claude 或 Codex有些 Agent 能连续完成复杂任务有些 Agent 却经常跑偏、忘记目标、乱调用工具最后还无法判断自己到底做没做对很多时候问题不只在模型而在模型外面的那套运行环境。这套运行环境就是 Harness。一、Harness 工程到底是什么Harness 原本指的是马具或缰绳。马本身有力量但如果没有缰绳、路线、障碍和骑手它的力量并不能稳定地服务于目标。AI Agent 也是一样。模型可以理解语言、生成代码、调用工具但它并不知道当前任务的边界是什么哪些工具可以使用每一步应该先做什么什么结果才算成功失败之后应该如何恢复上一次执行留下的状态在哪里。Harness 工程就是围绕 Agent 建立一整套“让它看得准、做得对、错了能恢复”的工程系统。一个实用的定义是Harness 工程 提示词 上下文 工具 任务编排 状态管理 评估 约束与恢复它不是某个框架也不是一个固定产品而是一种设计 Agent 的方法。二、Prompt、Context 和 Harness 有什么区别这三个概念不是互相替代而是范围逐步扩大。Prompt Engineering 解决的是怎么把任务讲清楚让模型理解你的要求。例如你是一个 Python 工程师请修复登录接口的参数校验问题并保留现有 API 格式。Context Engineering 解决的是怎么把模型需要的信息送到它面前。除了任务本身模型还需要知道项目目录结构相关代码接口文档测试结果团队规范历史执行状态。Harness Engineering 解决的是怎么让模型在真实环境中连续完成任务并且能被验证和纠错。简单来说Prompt 是把话说清楚。Context 是把资料准备好。Harness 是把整个工作流程搭起来。三、一个完整 Harness 通常包含什么一个实用的 Harness至少可以拆成六层。第一层上下文管理决定当前这一轮应该给模型看什么。不要每次都把整个项目、所有规则、全部历史记录塞进上下文而是按照任务动态加载。第二层工具系统决定 Agent 能使用哪些工具。例如读取文件搜索代码运行测试查看 Git diff调用接口发送消息。工具不是越多越好。工具越多Agent 越容易误用。第三层任务编排规定 Agent 应该按照什么顺序工作。例如先读需求再分析代码然后制定计划接着修改代码运行测试根据测试结果修复最后汇报结果。第四层状态与记忆决定任务完成到一半后下一轮如何继续。任务状态不要只放在上下文里而应该写入文件、数据库或任务系统。第五层评估与观测决定如何判断 Agent 做得好不好。不能只看 Agent 自己说“任务完成”而要看测试、日志、输出格式和业务指标。第六层约束与失败恢复限制 Agent 的危险行为并为常见失败准备恢复路径。例如限制修改目录限制工具调用次数禁止直接删除生产数据API 限流后自动重试任务超时后保存进度失败后从上一个检查点继续。四、从 0 搭建一个代码 Agent Harness下面用一个代码项目举例。目标是让 Agent 为项目添加一个新功能并且必须经过测试、代码检查和结果验收。第一步建立项目结构在项目根目录增加以下文件project/ ├── AGENTS.md ├── progress.md ├── tasks/ │ └── task-001.md ├── scripts/ │ └── check.ps1 └── evals/ └── cases.md这些文件分别负责AGENTS.md项目规则和工作流程。progress.md任务进度和交接信息。tasks/task-001.md当前具体任务。scripts/check.ps1自动检查代码。evals/cases.md评估 Agent 是否完成任务。第二步编写 AGENTS.md示例内容# 项目开发规则 1. 修改代码前先阅读当前任务文件和相关模块。 2. 先给出简短实现计划再开始修改。 3. 不要修改任务范围之外的文件。 4. 修改完成后必须运行 scripts/check.ps1。 5. 测试失败时先分析错误原因再继续修改。 6. 不要删除已有测试。 7. 最终报告必须包含 - 修改了哪些文件 - 运行了哪些检查 - 检查结果是什么 - 仍然存在什么风险 8. 每完成一个阶段就把进度写入 progress.md。注意这个文件不应该写成项目百科全书。只放最重要的规则详细规范可以拆到 docs 目录中需要时再读取。第三步定义一个具体任务tasks/task-001.md任务为用户模块增加邮箱格式校验。 要求 1. 只修改用户模块相关代码。 2. 邮箱为空时返回明确错误。 3. 邮箱格式错误时返回明确错误。 4. 增加至少两个测试用例。 5. 不改变已有接口返回结构。 6. 完成后运行项目测试和代码检查。任务越具体Agent 越不容易跑偏。不要只写“优化一下用户模块。”应该写清楚改什么不改什么成功标准是什么如何验收。第四步加入自动检查脚本如果项目使用 Node.js可以创建 scripts/check.ps1$ErrorActionPreference Stop npm test npm run lint git diff --check Write-Host All checks passed.如果是 Python 项目可以替换为$ErrorActionPreference Stop python -m pytest ruff check . git diff --check Write-Host All checks passed.关键不在于具体命令而在于不要只告诉 Agent “请认真检查”。要给它一个可以真实执行的检查入口。第五步规定 Agent 的执行循环给 Agent 的工作流程可以固定为1. 阅读 AGENTS.md。 2. 阅读当前任务文件。 3. 阅读 progress.md。 4. 搜索相关代码和测试。 5. 输出实现计划。 6. 修改代码。 7. 运行 scripts/check.ps1。 8. 如果失败分析错误并修复。 9. 再次运行检查。 10. 更新 progress.md。 11. 输出最终修改说明。这比一句“帮我完成这个功能”稳定得多。因为 Agent 不仅知道目标还知道工作顺序和验收方式。五、如何处理长任务长任务最容易出现两个问题第一Agent 忘记最初目标。第二上下文越来越长模型开始忽略早期信息。解决方法是把状态写到文件里而不是只留在对话中。progress.md 可以这样写任务增加邮箱格式校验 已完成 - 找到用户模块入口 - 找到参数校验类 - 增加了邮箱为空的测试 进行中 - 增加邮箱格式错误测试 待完成 - 运行完整测试 - 检查接口返回结构 - 更新任务说明 遇到的问题 - 当前项目使用统一异常处理不能直接返回字符串下一轮 Agent 开始时先读取 progress.md就能知道自己目前做到哪一步。如果任务很长还可以采用“分轮执行”第一轮分析和规划。第二轮实现主要功能。第三轮补充测试。第四轮运行检查和修复。每一轮都使用新的上下文但通过文件保存任务状态。这比让一个 Agent 在同一个超长对话里连续工作更稳定。六、如何让 Agent 自己发现错误不要让执行 Agent 自己给自己打分。一个更可靠的流程是规划 Agent拆解需求 执行 Agent修改代码 验收 Agent运行测试和检查 修复 Agent根据失败结果修改 再次验收即使不使用多个模型也可以把执行和验收分成两个独立阶段。例如执行阶段只负责修改代码。验收阶段只负责运行测试检查接口查看 Git diff验证输出格式确认是否满足任务要求。验收必须尽量接近真实使用场景。例如做前端 Agent 时不能只检查代码有没有语法错误还要真正打开页面、点击按钮、提交表单确认功能能用。七、Agent 反复犯错时怎么办最重要的一条原则是不要只在提示词里提醒 Agent。应该把解决方案沉淀到项目环境中。例如Agent 总是忘记运行测试错误做法“请注意修改后一定要运行测试。”更好的做法把测试写进 scripts/check.ps1并规定任务完成前必须执行这个脚本。再比如Agent 总是使用错误的代码格式。可以增加代码格式检查Lint 规则提交前 Git Hook自动化测试类型检查。Agent 每犯一次错误环境就变强一点。这就是 Harness 工程最重要的“复利效应”Agent 犯错 → 找到原因 → 把修复写入规则、测试或工具 → 下一次自动避免 → Harness 持续增强八、如何建立评估集如果没有评估集你只能凭感觉判断 Agent 是否变好了。可以从过去真实任务中挑选 10 到 20 个案例记录任务描述正确修改的文件预期测试结果不能修改的内容最终应该输出什么。例如案例 1 任务增加邮箱格式校验 必须修改user/service.py、tests/test_user.py 禁止修改payment 模块 必须通过python -m pytest每次修改 Harness 后都重新运行这些案例。关注以下指标任务完成率测试通过率越权修改率平均执行轮数工具调用失败率人工返工时间。这样才能知道改动到底有没有效果。九、Harness 工程的五条实践原则第一状态外置不要依赖模型记忆。第二执行和验收分离不要让 Agent 自己当裁判。第三失败要沉淀成规则、测试或工具。第四规则文件保持简短详细内容按需加载。第五技术债持续偿还不要等到项目失控后再集中清理。总结Prompt Engineering 解决的是“怎么把任务讲清楚”。Context Engineering 解决的是“怎么把正确资料送给模型”。Harness Engineering 解决的是“怎么让 Agent 在真实环境中持续做对”。真正可落地的 Harness不是一个复杂的名词而是一套可以执行的工程机制有明确任务有可控工具有固定流程有外部状态有自动检查有评估数据有失败恢复。如果你正在使用 Codex、Claude Code、Cursor 或其他编程 Agent不要只花时间修改提示词。先从这几件小事开始建立 AGENTS.md建立任务文件加入自动检查脚本保存 progress.md整理一组真实评估案例。这就是 Harness 工程最简单、也最有效的起点。
)
