Harness怎么用：六步跑通AI编程闭环

很多人第一次使用 AI 编程工具时，会把需求完整地说一遍，然后等待一份“已经完成”的答案。真正打开代码一看，却可能发现它改错了目录、漏了测试、破坏了旧功能，甚至只是生成了一段不能运行的示例。问题未必是模型不够聪明，而是它没有项目规则、没有可控工具、没有失败反馈，也没有必须通过的验收标准。

图1：看模型与 Harness 的分工。模型提供能力，Harness 把能力组织成可验收的交付。

Harness 可以直译成“马具”，在 AI 编程里更接近“智能体运行框架”。它不是另一个大模型，而是包在模型外面的工作环境和控制系统：把目标、上下文、工具权限、执行循环、测试反馈和验收规则组织起来，让模型不只回答问题，还能在边界内完成任务并证明结果。

一句话理解：模型决定能力上限，Harness 决定这种能力能否稳定变成交付。

为什么只换更强模型仍然不够

真实软件任务不是补全几行代码。SWE-bench 论文用 2,294 个真实 GitHub 问题构建评测，覆盖 12 个 Python 仓库；任务经常要求同时理解多个文件、调用执行环境、处理长上下文并完成复杂推理。论文最初报告的最好结果只有 1.96%。这不是今天的能力排名，而是一个重要历史信号：只给问题和代码，不给可靠的执行闭环，模型很难稳定完成真实工程任务。

另一个变化是任务正在变长。METR 对长软件任务的研究发现，AI 智能体可独立完成的任务时长在过去六年里大约每 7 个月翻倍一次。能力越强、任务越长，一次错误的权限、上下文或验收设计，影响就越大。

图2：看真实软件任务的难度与任务时长变化。任务越长，执行边界与反馈闭环越重要。

因此，真正的问题已经从“模型能不能写代码”转向“怎样给它合适的环境，让它知道该做什么、能做什么、哪里做错了、什么时候算完成”。这正是 Harness 的职责。

一个可用的 Harness，至少有六层

图3：看一个可用 Harness 的六层结构。六层缺任何一层，都可能让代码修改失去约束或验收依据。

任务入口。 把模糊诉求改写为任务契约：目标是什么，允许改哪里，明确不能做什么，最后用什么命令和证据验收。没有这一层，智能体容易在“顺手优化”中越界。

上下文。 给模型项目规则、关键代码、测试命令、架构说明和必要的历史决策。上下文不是越多越好，而是当前动作需要什么就提供什么。整库材料全部塞进去，反而会淹没重点并增加成本。

工具与权限。 决定智能体能读取文件、编辑代码、运行终端、检索资料还是调用 API。权限应分级：默认从只读开始，写入限定目录，联网和高风险动作需要确认。工具名不重要，边界清楚才重要。

执行循环。 智能体按照“观察环境 → 决定下一步 → 执行动作 → 读取结果”的循环工作。它先定位问题、再制定计划、然后改动；失败后根据新证据继续修正，而不是一次生成后结束。

测试与反馈。 编译、单元测试、静态检查和日志，是机器能够理解的客观反馈。模型说“应该没问题”不算证据，测试命令的结果才算。Anthropic 在构建有效智能体中也强调，应优先使用简单、可组合的模式，并让工具返回对下一步决策有用的信息。

验收与回滚。 最后对照完成标准检查修改范围、测试结果、关键差异和遗留风险。高风险动作要能暂停，失败改动要能恢复。真正的完成不是输出一句“已完成”，而是交付可核验的证据。

从零使用 Harness：六步完成第一次闭环

图4：看 Harness 从小任务、任务契约到证据验收的六步流程，每一步都有明确产出。

第一步：选择一个小而清楚的任务

第一次不要让智能体“重构整个系统”。选择边界清楚、可回滚、人工预计 30–90 分钟能完成的任务，例如“给一个接口新增可选参数，并补充单元测试”。

动作： 确认涉及的模块、允许修改的文件和可能受影响的调用方。 产出： 一个能够在单次工作中闭环的小任务。

第二步：写出任务契约

不要只说“把这个接口改一下”。一个可执行的任务至少写清四件事：目标、范围、禁止项、完成标准。

可以直接照下面的格式写：

目标：为查询接口增加可选参数 limit，默认行为保持不变。范围：只修改接口层、参数校验和对应测试。禁止：不改数据库结构，不升级依赖，不重构无关代码。验收：相关单元测试全部通过；旧调用方式仍可用；输出修改文件、测试结果和风险。

动作： 把“想要什么”改成“什么情况下算完成”。 产出： Harness 可执行、使用者可验收的任务说明。

第三步：准备最小上下文

在项目根目录放置智能体规则文件，例如 AGENTS.md，写清目录结构、开发命令、测试方式、代码规范和禁止动作；再确保仓库能在干净环境中安装依赖、运行测试。规则文件相当于给每次任务共用的“工作手册”。

项目入口：src/测试目录：tests/安装依赖：npm ci运行相关测试：npm test -- user-api提交前检查：npm run lint && npm test禁止修改：migrations/、secrets/、生产配置

动作： 提供当前任务真正需要的规则、代码位置和验证命令。 产出： 模型可以自主定位工作对象，不必反复猜项目结构。

第四步：限制工具与权限

把工具按风险分层。读取文件、搜索代码可以默认允许；编辑只开放到当前仓库；安装依赖、联网访问和执行项目命令应在受控环境里进行；删除、发布、修改生产数据等动作必须由人确认。

最小权限原则很简单：完成当前任务不需要的能力，就先不给。 这样即使模型判断错误，影响范围也被限制在可恢复区域。

动作： 配置可读范围、可写范围、可执行命令与确认点。 产出： 一个既能工作又不容易越界的执行环境。

第五步：让智能体按闭环执行

把任务契约交给 Harness，要求它先读取项目规则和相关文件，再输出简短计划。计划合理后进入执行循环：定位代码、编辑文件、运行测试、读取失败信息、修复并重试。限制重试次数，连续失败时暂停并报告，不让它无休止地改动。

图5：看使用者、Harness、模型、工具与测试环境如何协作；失败反馈会回到修正环节，而不是直接宣布完成。

以“新增接口参数并补测试”为例，Harness 会先读取规则与现有测试，定位接口入口；随后修改参数定义和校验逻辑，补充默认值、合法值、非法值三类测试；运行测试后，如果发现旧调用失败，就根据日志修复兼容逻辑，再次验证。

动作： 观察计划、文件差异和测试反馈，只在权限升级或方向改变时介入。 产出： 一组经过机器反馈修正的代码改动，而不是未经验证的代码片段。

第六步：按证据验收

验收时不要只读智能体的总结，至少检查五项：修改范围是否越界，目标测试是否通过，完整检查是否通过，关键改动能否解释，遗留风险是否明确。对于重要功能，再补一次人工走查或灰度验证。

[ ] 只修改了约定范围内的文件[ ] 新旧调用方式均有测试覆盖[ ] 测试与静态检查通过[ ] 没有写入密钥、生产数据或无关配置[ ] 失败时可以回滚，遗留风险已说明

动作： 查看代码差异、命令结果和风险说明。 产出： 可接受、可拒绝、可回滚的明确结论。

Harness、提示词和工作流框架有什么区别

方案

解决什么问题

能否直接执行

适合场景

选型结论

提示词模板

统一任务描述和输出格式

通常不能

问答、写作、一次性代码建议

任务不需要操作环境时最轻量

工作流 / Agent Framework

编排多个步骤、模型和服务

可以，但需自行补工程约束

固定业务流程、客服、数据处理

流程稳定且要系统集成时使用

Agent Harness

组织仓库上下文、工具权限、执行反馈和验收

可以

代码修改、测试、调试、长任务

真实工程交付优先使用

三者不是互斥关系。提示词可以放进 Harness，Harness 也可以由工作流框架调度。明确的选型原则是：只要任务会修改真实代码、调用工具、持续多步或产生风险，就不应只依赖提示词；至少需要一个能控制权限、反馈和验收的 Harness。

常见失败，以及怎么修

上下文过多。 把整个知识库和所有日志一次性塞给模型，会降低重点识别能力。修法是先用目录、搜索和摘要定位，再按动作加载原文。

验收写成主观句。 “代码质量良好”“功能正常”无法让机器判断。修法是改成可执行命令、明确断言和可观察结果。

权限一次开满。 为省一次确认而开放生产凭据、删除权限和任意联网，会把小错误放大。修法是分级授权，并为高风险动作设置人工门禁。

没有停止条件。 智能体可能在失败后持续试错，造成大量无关改动。修法是限制轮次、改动文件数或耗时；触发阈值后只报告证据，不再继续写入。

把评测成绩当交付保证。SWE-bench Verified通过人工审核得到 500 个更可靠的测试样本，但任何公开基准都不能替代自己的仓库规则、测试和线上指标。正确做法是用公开评测看趋势，用内部任务集决定是否上线。

最小落地清单

如果团队现在还没有 Harness，不必先建庞大平台。先做到这七件事：

1. 选择 10–20 个真实、可回放的小任务作为内部任务集。
2. 在仓库维护一份简短的智能体规则文件。
3. 给每类任务写清范围、禁止项和验收命令。
4. 默认只读，按任务逐级开放写入、执行和联网权限。
5. 保留计划、工具调用、文件差异、测试结果和失败日志。
6. 为连续失败、越界改动和高风险动作设置停止条件。
7. 统计一次通过率、人工介入次数、返工率和回滚率，再逐步扩大任务范围。

Harness 的价值不在于让 AI 看起来更自主，而在于让自主过程可观察、结果可验证、错误可恢复。先把一个小任务稳定做对，再扩展到更长、更复杂的任务，这比一开始追求“全自动工程师”更可靠。