Harness 是什么?Harness Engineering 六层架构与 Agent 工程实践
使用 Claude Code、Codex 这类编码 Agent 时,我们给出需求,它们就能读取项目、修改文件、运行测试。不过,模型本身输出的是文本或工具调用。谁来执行命令?测试结果从哪里返回?进程退出以后,做到一半的任务怎么办?
Harness 就是负责这些工作的外部执行系统,设计和改进这套系统的工作称为 Harness Engineering。 同一个模型接入不同的执行系统,结果也可能差很多。Can.ac 的编辑接口实验中,Grok Code Fast 1 的得分从 6.7% 升到了 68.3%。模型没有换,变的是把修改写进文件的方式。具体测试条件放在后面的 Hashline 部分说明。
Harness 是什么?
Agent = Model + Harness
Agent = Model + Harness 中的加号表示分工。模型输出“运行测试”的调用,实际执行还需要工作目录、依赖环境和权限。Harness 在这些条件下启动命令,拿到结果,再发起下一轮模型请求。退出码、失败用例和错误输出返回给模型,它才有依据继续修改。若应用只返回一句“执行失败”,模型连测试没通过还是命令没找到都难以区分。
跨会话状态也由应用保存。模型能够分析输入中的测试结果,但不会凭空知道终端里刚发生了什么;上一轮的进度如果没有保存、没有重新加载,也不会自动出现在新会话中。LangChain 的 Vivek Trivedy 在《The Anatomy of an Agent Harness》中,正是从这些模型之外的工作来拆解 Harness。

Harness 和 Prompt / Context Engineering 的关系
Prompt Engineering、Context Engineering、Harness Engineering 不太适合放在同一层比较。它们更像一层套一层,处理的问题范围越来越大。

| 层级 | 解决的问题 | 关注点 | 典型工作 |
|---|---|---|---|
| Prompt Engineering | 怎么把指令说清楚 | 让模型理解意图,减少局部歧义 | 系统提示词设计、Few-shot 示例、思维链引导 |
| Context Engineering | 该给 Agent 看什么 | 在合适时机给模型提供正确且必要的信息 | 上下文管理、RAG、记忆注入、Token 优化 |
| Harness Engineering | 系统怎么持续执行、纠偏、观测和恢复 | 长链路任务中的持续正确、偏差修正、故障恢复 | 文件系统、沙箱、约束执行、反馈回路、观测 |
这三类工作经常出现在同一次修改中。例如,让 Agent 修复一个失败用例:Prompt 说明要修什么、有哪些限制;Context 提供相关代码与失败日志;Harness 执行文件修改和测试,把输出送回模型。我们可以调整其中一部分,但不能用一句“请仔细检查”替代测试命令的执行。
Harness 包含哪些组件?
从一次模型请求看,输入包含消息和工具定义,输出可能是回答,也可能是工具调用。历史消息、磁盘上的文件、外部 API 都需要应用接进来。按这几类数据和操作,可以找到相应的 Harness 组件:
| 请求涉及的能力 | Harness 提供的支持 | 对应组件 |
|---|---|---|
| 记住多轮对话历史 | 维护对话历史,每次请求时拼进上下文 | 记忆系统 |
| 执行代码、跑命令 | 提供 Bash 和代码执行环境 | 通用执行环境 |
| 获取实时信息,比如新库版本、API 变化 | 接入 Web Search、MCP 工具 | 外部知识获取 |
| 操作文件和环境 | 抽象文件系统,引入 Git 版本控制 | 文件系统 |
| 判断自己有没有做对 | 提供沙箱、测试工具、浏览器自动化 | 验证闭环 |
| 长任务中保持连贯 | 做上下文压缩、记忆文件、进度追踪 | 上下文管理 |
表中的组件不一定各自对应一个服务。对话历史可以存在同一进程中,文件读写和命令执行也可能共用一个沙箱。是否需要外部检索,则取决于任务:修复仓库内已有的逻辑,不一定每次都要联网。
Harness 进阶
一个成熟的 Harness 长什么样?
组件接通以后,任务仍然可能失败。例如,工具已经返回错误,Agent 却继续执行下一步;或者文件已经改好,新会话又从头做了一遍。排查这些问题时,需要继续看组件之间怎么配合。
下图按职责分了六层,用来检查一次任务经过了哪些环节。这是本文的归纳,不是协议规定的架构。
| 层级 | 名称 | 解决什么问题 | 关键设计 |
|---|---|---|---|
| L1 | 信息边界层 | Agent 该知道什么、不该知道什么 | 定义角色与目标,裁剪无关信息,结构化组织任务状态 |
| L2 | 工具系统层 | Agent 怎么和外部世界交互 | 选择工具、控制调用时机、提炼工具结果并反馈 |
| L3 | 执行编排层 | 多步骤任务怎么串起来 | 安排步骤、分支和停止条件,处理工具返回后的下一次调用 |
| L4 | 记忆与状态层 | 长任务中间结果怎么管理 | 独立管理当前任务状态、中间产物和长期记忆,避免状态混在一起 |
| L5 | 评估与观测层 | Agent 怎么知道自己做对了没有 | 建立独立于生成过程的验证机制 |
| L6 | 约束、校验与恢复层 | 出错了怎么办 | 预设规则拦截错误,失败时提供重试、回滚或降级 |
比如,Agent 发出了测试调用,但环境中没有对应命令。此时 L2 返回的是命令启动失败,L3 可以安排修正环境或停止任务,L4 则应记录“测试未执行”。L5 不能把“调用过测试工具”算作验证通过。
L6 还要处理另一类问题:这次写操作有没有授权,失败前到底写入了什么?只要部分操作可能已经完成,重试前就需要核对实际状态,否则会重复修改。六层可以在一个进程里实现,重点是这些处理没有遗漏。
为什么瓶颈经常不在模型?
模型给出了修改,文件却没有变,这时可以先查看编辑工具返回了什么。精确文本替换需要找到与旧内容匹配的位置,空格或缩进不同都可能匹配失败;补丁接口则要求输入符合补丁格式。工具拒绝了这次操作,后面的测试自然也用不上模型生成的新代码。
Can.ac 的实验比较了这些编辑方式。它使用的 Hashline 在读取文件时,为每行附上一个短内容哈希。模型想替换第 2 行,可以引用原文中的 2:f1:2 是行号,f1 是哈希,不需要再抄一遍旧内容。
读取和修改之间,文件仍可能变化。工具执行前会核对标记,不匹配就拒绝修改。不过,短哈希可能碰撞;标记匹配也只帮助确认修改位置,不能证明新代码符合需求。
在这组实验中,Grok Code Fast 1 更换编辑接口后,得分从 6.7% 升到了 68.3%。任务是在 React 代码中引入可逆错误,再比较修复后的文件。这是编辑任务的成绩,不能直接换算成日常开发成功率,但能帮助区分“模型没有改对”与“工具没有把修改写进去”。
修改已经写进文件,又是另一种情况。LangChain 在执行记录中发现,有些 Agent 写完代码后只读一遍,就认为任务结束,根本没有运行测试。
团队为此在系统提示词里补充了构建、验证和修复要求,并加入 PreCompletionChecklistMiddleware。Agent 准备退出时,这个中间件会提醒它按任务要求做验证。之后是否执行了测试、测试是否通过,仍要看实际调用和输出,不能从这条提醒推断。
这些改动连同工具等配置的调整,让同一个 gpt-5.2-codex 在 Terminal Bench 2.0 上从 52.8% 升到 66.5%,由当时前 30 名之外进入前 5 名。原文报告的是整套调整后的结果,不能把提升全部归给退出前提醒。
同一篇文章里,Claude Opus 4.6 在较早版本 Harness 上的得分为 59.6%。它没有经过同样的优化迭代,因此这组数字还不足以单独比较模型能力。模型与 Harness 的组合也需要评测。 固定同一批任务,再比较成功率、成本和失败步骤,才能判断换用的组合是否适合当前任务。
为什么上下文喂越多,Agent 反而越蠢?
测试日志还在上下文里,Agent 却漏掉了报错,这不一定是窗口已经装满。材料能放进去,与模型能否找出当前需要的内容,是两件事。相关信息被大量无关输出夹在中间,前面的要求也可能被遗漏。
Dex Horthy 用 Smart Zone 和 Dumb Zone 描述这类工作状态:前者较容易有效推进任务,后者则在上下文累积后开始表现变差。他在 2025 年的文章中介绍过把利用率控制在 40%–60% 的方法,2026 年的访谈又谈到随模型和任务调整使用量。
图中的约 40% 是对早期经验说法的简化,并不是所有模型都适用的分界。图和表用于说明这种变化,具体阈值仍需用自己的任务评测:
| 区间 | 图中占比 | 想表达的现象 |
|---|---|---|
| Smart Zone | 0 - ~40% | 上下文较少且相关时,模型较容易聚焦任务 |
| Dumb Zone | 超过 ~40% | 无关信息持续累积时,可能遗漏要求、重复操作或调用出错 |
以失败用例为例,几轮完整测试日志可能占了很大篇幅,当前需要的却只是其中一个报错。可以把日志原文放到文件里,在请求中保留错误位置和读取入口。模型需要前后文,再调用工具读取;下一步修改要用到的相关代码,则不能跟旧日志一起按比例删掉。
换会话时,仅保留日志路径还不够。日志说明测试时发生了什么,却不一定记录测试以后又改了哪些文件。交接记录还需要留下已完成的修改和未通过的检查,否则新会话可能重新做一遍。Anthropic 对 Sonnet 4.5 采用的 context resets 会在后文展开,具体实现也可以参考上下文工程。
压缩以后,用原来的任务继续执行,检查模型能否找到报错、接上未完成的步骤。输入量和耗时一起记录,才便于选择压缩阈值。如果 Token 少了,失败原因也跟着丢了,这次压缩就没有达到目的。
从哪里开始搭 Harness?
可以先选仓库里一项结果明确的修改,让 Agent 按项目规则改代码,再运行对应检查。检查失败时,错误能不能返回给它,它能不能继续修复,这一轮走通以后,再补跨会话进度和并行执行。
P0 到 P2 只是一般的投入顺序。任务本身要求的授权和检查要先具备,例如做性能优化,从一开始就得有测量数据,不能因为可观测性列在 P2 就推迟接入。
P0:可以马上做
| 行动 | 为什么 | 参考实践 |
|---|---|---|
创建 AGENTS.md 并持续维护 | 由支持该文件的宿主加载项目约定,按实际失败修订 | Hashimoto 每一行对应一个历史失败案例 |
| 写自定义 Linter + 修复指令 | 错误消息直接告诉 Agent 怎么改 | OpenAI 的 Linter 报错自带修复方法 |
| 把团队知识放进仓库 | Slack、Wiki、Docs 里的知识对 Agent 很难稳定可见 | OpenAI 把仓库作为事实来源 |
AGENTS.md 放进仓库后,还要看当前宿主是否支持读取,以及任务实际加载了哪个目录下的规则。文件中的测试命令也可以直接运行一次:路径已经改了、依赖没有装好,规则即使被读到,检查仍然跑不起来。
P1:P0 稳了之后再补
| 行动 | 为什么 | 参考实践 |
|---|---|---|
| 分层管理上下文 | 避免把所有信息塞进一个文件,按需披露 | OpenAI 把 AGENTS.md 当目录用,约 100 行 |
| 建立进度文件和功能列表 | 用 JSON 记录功能与验证状态,便于逐项核对 | Anthropic 初始化 Agent + 编码 Agent 两阶段 |
| 给 Agent 端到端验证能力 | 打开页面、操作关键流程并检查实际结果 | Anthropic 使用 Playwright / Puppeteer MCP |
| 控制上下文利用率 | 用自有评测确定压缩和交接阈值,避免无关历史持续累积 | Dex Horthy 的 Smart Zone / Dumb Zone 观察 |
Anthropic 的长任务实践把初始化与后续开发分开:第一次准备环境和功能清单;新会话开始后,先读进度、查看 Git 记录,再运行基础端到端测试。接着只推进选定功能,并留下验证结果。新会话因此能先确认已有功能是否正常,再决定下一步;JSON 清单本身并不能阻止误报完成。
P2:有余力再考虑
| 行动 | 为什么 | 参考实践 |
|---|---|---|
| Agent 专业化分工 | 按任务隔离无关信息,减少各自需要处理的上下文 | Carlini 的去重、优化、文档 Agent |
| 定期垃圾回收 | 清理速度要跟得上生成速度 | OpenAI 的后台清理 Agent |
| 可观测性集成 | 把性能优化从感觉问题变成可测量的问题 | OpenAI 接入 Chrome DevTools |
你的 Harness 到哪个阶段了?
下表是对常见配置的粗略归纳,编号方便讨论,不是成熟度标准。使用现成编码 Agent 时,即使没有给项目写规则,工具通常也已经提供了基础 Harness。是否需要并行 Agent 或自动修复,要看任务与验证条件,不能按编号逐级照搬。
| 阶段 | 特征 | 工程师角色 |
|---|---|---|
| Level 0:未补项目约束 | 使用默认 Agent,主要通过 Prompt 提要求 | 手动写代码,偶尔使用 AI |
| Level 1:基础约束 | AGENTS.md、基础 Linter、手动测试 | 主要写代码,AI 辅助 |
| Level 2:反馈回路 | CI/CD 集成、自动化测试、进度追踪 | 规划和审查为主 |
| Level 3:专业化 Agent | 多 Agent 分工、分层上下文、持久化记忆 | 设计环境和管理执行过程 |
| Level 4:自治循环 | 无人值守并行化、自动清理、自修复 | 架构设计和质量把关 |
Harness 还没解决的问题
Agent 改完一个接口,编译和新增测试都通过了,旧调用方却可能用不了。这类已有代码库的改造通常叫作棕地(Brownfield)改造,原来的接口、部署方式和遗留逻辑都要继续考虑。Stripe 复用了现有开发环境与检查工具;缺少回归用例的项目,还需要补上旧行为的验证。
可以先固定一组输入和预期输出,比较修改前后的结果。这里的预期输出要从需求确定。如果模型误解了需求,再照着自己的实现写测试,实现和测试就可能一起通过,却一起偏离要求。编译器也检查不了完整的用户流程。
执行日志还有另一项限制。工具把文件写到了错误目录,仍可能返回写入成功;Agent 据此报告完成,目标目录里却没有产物。日志可以用来追查写到了哪里,验收则要检查文件是否出现在要求的位置。Anthropic 的评测说明因此区分执行轨迹与最终环境状态。让另一个 Agent 审查时,也需要给它检查实际结果的条件。
项目中的其他取舍可以对照这些问题:
| 问题 | 需要验证什么 | 公开案例或参考 |
|---|---|---|
| 棕地项目怎么改造 | 既有接口、构建与回归用例是否支持重复验证 | Stripe 复用现有设施;Böckeler 讨论类型系统、模块边界等 Ambient Affordances |
| 怎么验证 Agent 做对了事 | 用例验证的是需求,还是生成代码自身的逻辑 | Böckeler 对功能行为验证的讨论:AI 生成的测试不足以单独保证正确性 |
| AI 生成代码的长期可维护性 | 重复实现、复杂度、架构偏移及修复引入的问题 | Böckeler 区分静态检查与语义判断;后者仍需审查 |
| Harness 该做厚还是做薄 | 新增检查捕获的错误、运行成本及升级后的必要性 | Anthropic 升级模型后移除 Sprint 分解,保留 Planner 和 Evaluator |
| 单 Agent 还是多 Agent | 子任务的独立性,以及合并时的协调和验证成本 | Hashimoto 用单 Agent,Carlini 用 16 个并行 Agent;任务不同,不能只按项目规模选 |
Harness 案例:这些团队是怎么做的
OpenAI:三个人,五个月,一百万行,零手写代码
OpenAI 的这项实验有个特别的约定:工程师不手写代码。2025 年 8 月,团队从空仓库起步,把应用逻辑、测试、CI 配置和内部工具都交给 Codex 生成。人负责提出要求、准备环境,并验证结果。五个月后,团队整理了这些数据:
| 指标 | 数值 |
|---|---|
| 团队规模 | 3 名工程师,后扩至 7 人 |
| 持续时间 | 5 个月,2025 年 8 月起 |
| 代码规模 | 约 100 万行 |
| 手写代码 | 0 行,设计约束 |
| 合并 PR 数 | 约 1,500 个 |
| 日均 PR/人 | 3.5 个 |
| 效率提升 | 团队估计耗时约为手写的十分之一 |
注意,“十分之一”是团队对这个项目的估计,并没有做手写开发的受控对照。表中的代码量也包含基础设施、工具和文档,不能只按业务代码理解。
给 Agent 一张地图,不要塞一本千页手册
他们一开始也试过把规则集中写进一个很大的 AGENTS.md。问题很快出现:说明文件占用了太多上下文,真正要修改的代码和相关资料反而被挤出去;规则过期以后,也难以逐条维护。
后来,AGENTS.md 缩到约 100 行,主要指向 docs/ 中的资料。设计说明、架构图和质量评级分别维护。例如,执行计划放在 exec-plans/ 下,进行中的计划与已完成的计划分开存放。Agent 顺着入口找到当前计划,就不必把整套文档一次读完。
AGENTS.md 负责项目约定和资料导航,具体加载方式由宿主决定。Skill 则用名称、描述匹配任务,再加载详细流程;它也支持按需提供材料,但用途不完全相同。相关区别见Agent Skills 详解。
架构约束要靠工具执行
OpenAI 的项目在每个业务领域内采用固定分层:
Types → Config → Repo → Service → Runtime → UI分层的依赖方向交给自定义 Linter 和结构测试检查。结构化日志、Schema 与类型命名、文件大小也有对应规则。这样,Agent 引入了违规依赖,检查就会报错,不需要等人逐行发现。
报错还会告诉 Agent 应该怎样修复。它根据错误位置和修复要求改文件,再跑一遍检查。这里用到的是本轮工具反馈,模型参数并没有因此更新。
可观测性也要给 Agent 看
假设任务要求服务在 800ms 内启动,Agent 从哪里知道改完有没有达标?团队为每个 Git worktree 提供可运行的应用实例及本地可观测性栈,日志、指标、链路追踪都能在当前任务中查询。修改前后可以直接测量比较。
浏览器这边,他们接入 Chrome DevTools Protocol,支持获取 DOM 快照和截图。Agent 因而可以操作页面,复现问题,再检查修复后的行为。这些能力让“验证结果”有了具体的操作入口。
熵不会自己消失
Agent 会参考仓库里的现有写法。旧用法没有清掉,下一次修改就可能继续沿用,文档和代码之间的偏差也会留下来。
OpenAI 最初每周五都要花时间清理这类问题,约占工作时间的 20%。后来改为由后台 Agent 定期查找文档不一致、架构违规和冗余代码,通过清理 PR 处理。清理任务处理的是已经进入仓库的内容,不能被一次提交前的 lint 完全替代。
Slack 里的知识,Agent 很难稳定用上
一项约定只在 Slack 里讨论过,当前 Agent 又没有读到这段讨论,它就无法据此修改代码。OpenAI 把团队知识移入版本控制,让代码与相关约定都能在仓库中找到,并且留下修改记录。
这不意味着所有项目都要迁移全部文档。先看当前任务需要的约定是否可访问、是否与代码一致,再决定哪些资料需要进入仓库。OpenAI 也明确指出,缺少相近的工程投入时,不能假定能复现他们的结果。
Anthropic:从上下文焦虑到三智能体架构
编译器可以用编译与运行结果检验,应用界面还要实际操作才能发现问题。Anthropic 的编译器与应用开发实验因此采用了不同的分工和反馈方式。
用 16 个 Agent 写 C 编译器
Nicholas Carlini 让 16 个 Claude Opus 4.6 实例并行开发一个 Rust 编写的 C 编译器。项目记录给出了约两周运行中的会话量、测试结果和费用:
| 指标 | 数值 |
|---|---|
| 持续时间 | 约 2 周 |
| 并行 Agent 数 | 16 个 Claude Opus 4.6 实例 |
| 会话数 | 约 2,000 个 |
| 产出 | 10 万行 Rust 代码 |
| GCC torture test | 99% 通过率 |
| 可编译项目 | PostgreSQL、Redis、FFmpeg、QEMU、SQLite、Linux 6.9 Kernel 等 |
| API 成本 | 约 2 万美元 |
这还不是可以直接替代成熟编译器的完整工具链。原文说明,x86 启动所需的 16 位代码仍借助 GCC,演示也使用了 GCC 的汇编器和链接器;生成代码的性能和 Rust 实现质量仍有限制。
编译器测试会产生大量输出。Carlini 将日志写入文件,失败信息采用 ERROR: [reason] 这类便于 grep 的单行格式。Agent 先看到错误,再去对应文件查详情,正常测试的重复输出不必一直留在当前上下文里。
等待时间也是问题。完整测试可能阻塞很久,于是快速测试模式只运行 1% 或 10% 的测试子集,固定同一 Agent 的采样,让它可以比较前后结果;不同 VM 使用不同采样,扩大整体覆盖。只通过自己的子集,仍不足以认定整个编译器没有回归。
多个 Agent 都在改编译器,也可能各自实现了一份相近功能。项目因此逐渐分出编译器实现、去重、性能、代码质量和文档等任务。每个会话根据分工和已有测试结果继续推进,需要排查时再读取对应日志,减少重复实现后再清理的工作。
Anthropic 为什么借鉴 GAN?
界面做得怎么样,让生成它的模型自己评价,答案可能过于乐观。Anthropic 在 2026 年 3 月的应用开发实验中观察到了这类偏差,于是把生成和评估交给不同 Agent,后来又加入规划者。
这里借鉴了 GAN 中生成与评判分开的思路。Evaluator 给出反馈,Generator 再修改应用,模型参数不会在这个过程中更新。
Planner(规划者)→ Generator(执行者)⇄ Evaluator(评估者)Planner 接收 1-4 句话的产品描述,扩展为产品规格,规划时被允许扩大功能范围。初版中的 Generator 按 Sprint 实现功能,动手前先与 Evaluator 约定完成标准;实现之后,Evaluator 通过 Playwright MCP 操作运行中的应用,再反馈设计与功能问题。
这两类失败发生的位置不同:
| 问题 | 表现 | 解法 |
|---|---|---|
| 上下文焦虑 | Sonnet 4.5 快到上下文上限时草草收尾 | context resets + 结构化交接,单靠压缩不够 |
| 自我评价偏差 | Agent 自信地夸自己做得好,实际质量一般 | 生成和评估交给两个独立 Agent |
前端任务还需要给设计评价提供依据。实验提高了设计质量与原创性的权重,同时检查功能性和代码质量。否则仅凭功能列表打勾,无法判断布局和操作体验是否达到了要求。
遇到上下文焦虑,Anthropic 选择重启
前面提到的上下文焦虑,来自团队较早对 Sonnet 4.5 的观察:窗口接近上限时,任务还没做完,Agent 就开始收尾。压缩历史虽然腾出了容量,却没有充分解决这个行为,因此团队采用 context resets。
重启前先生成结构化交接文档,记下当前状态、已经完成的工作和下一步。新 Agent 从这份记录与必要材料继续,不再带着整段旧历史。代价也在这里:若交接漏掉失败原因或验证命令,新会话仍要重新查。重启还增加了编排复杂度、Token 开销和等待时间。
后续应用开发实验的初版使用 Opus 4.5。作者发现上下文焦虑已明显缓解,因此移除了显式 context resets,改用 Claude Agent SDK 的自动压缩,在一次连续会话中完成构建。实验以同一个复古游戏制作器需求比较 Solo 与 Full Harness。两次运行的时间和费用不同,Full Harness 还扩展了产品规格,因此不能把结果理解为同等预算下只增加 Agent 数量的收益。
两种配置的成本对比如下:
| 配置 | 耗时 | 花费 | 效果 |
|---|---|---|---|
| Solo Harness,单 Agent + 最少工具 | 20 分钟 | $9 | 界面可打开,游戏运行逻辑有缺陷 |
| Full Harness,三 Agent + 完整工具链 | 6 小时 | $200 | 可运行,功能更丰富,仍有操作引导问题 |
同文还展示了一个浏览器音乐制作工作站(DAW):Full Harness 运行将近 4 小时,花费 $124.70,产出包含编曲视图、混音台和播放控制。这个任务没有在此表中列出对应 Solo 结果,不能据此计算两种配置的效果差距。
换成 Opus 4.6 后,作者又移除了 Sprint 分解,保留 Planner 和 Evaluator,将逐 Sprint 检查改为构建结束后统一检查。发现问题后仍可继续修复并再次 QA,文中的 DAW 运行记录就包含三轮 Build/QA。
这与前文 Sonnet 4.5 的上下文焦虑实验是不同阶段的观察。模型升级后,可以逐个移除组件并比较结果;是否保留评估器,还要看任务是否超出了当前模型独立完成的能力范围。
Stripe:每周 1300+ 个 PR 的无人值守模式
Stripe 在 2026 年 2 月的第二篇 Minions 文章披露,每周合并的纯 Minions 生成 PR 已超过 1300 个,仍由人审查。一次典型任务从 Slack 请求开始,在隔离的 Devbox 中修改代码并运行检查,最后交付 PR。
它的 Blueprint 把实现、修复 CI 等不确定步骤交给 Agent,把运行 lint、推送变更等步骤写成确定性代码。因此,执行检查不依赖模型临时决定,失败反馈才会回到需要推理的节点。
| 组件 | 作用 | 关键设计 |
|---|---|---|
| Devbox | 开发环境 | AWS EC2 预装源码和服务,预热池分配,启动约 10 秒,“牲口不是宠物” |
| 编排状态机 | 流程控制 | 混合确定性节点,比如 lint、push,和 Agent 节点,比如实现功能、修 CI;该确定的地方确定,该灵活的地方灵活 |
| Toolshed MCP | 工具服务 | 集中式 MCP 服务,近 500 个工具,每个 Minion 拿到筛选后的子集 |
| 反馈回路 | 质量保障 | Pre-push hook 秒级修 lint;推送后最多 2 轮 CI,运行相关测试;300 万+ 是已有测试库规模 |
CI 失败后,Minion 可以读取反馈再修复,但不会一直循环:相关 CI 最多运行两轮,仍未解决的问题随结果交给工程师。本地 pre-push 检查则尽量提前发现并修复 lint 问题,减少完整 CI 的等待。
Devbox 和工具链原本就服务于 Stripe 工程师。Minions 复用了这些设施,因此不必为每个任务重新准备源码与服务。这也是他们所说的 What's good for humans is good for agents 在这个案例中的具体含义。
Minions 底层是 Block 开源项目 goose 的一个 fork,Stripe 针对无人值守场景做了定制。
Mitchell Hashimoto:一个人的 Harness 工程学
Mitchell Hashimoto 是 Vagrant、Terraform、Ghostty 终端模拟器的作者。在 My AI Adoption Journey 中,他记录了自己的使用过程:从来回复制代码和命令输出,到让 Agent 在可执行环境里工作,再逐步把确定性较高的任务交给它。写作时,他仍选择一次只跑一个 Agent,并保持参与。
原文按六个阶段组织,表中的做法对应他的工作习惯,不要求其他团队按顺序复制:
| 步骤 | 名称 | 做法 |
|---|---|---|
| 1 | 放弃聊天模式 | 让 Agent 在能读文件、跑程序、发 HTTP 请求的环境里直接干活 |
| 2 | 复现自己的工作 | 每件事做两次,一次自己做,一次让 Agent 做,他形容这个过程“痛苦至极” |
| 3 | 下班前启动 Agent | 每天最后 30 分钟给 Agent 布置任务,比如深度调研、模糊探索、Issue 分拣 |
| 4 | 外包确定性任务 | 挑出 Agent 几乎一定能做好的任务后台跑,建议关掉桌面通知,避免上下文切换 |
| 5 | 工程化 Harness | Agent 每犯一次错,就工程化一个方案,尽量让它以后不再犯同类错误 |
| 6 | 始终有 Agent 在跑 | 写作时约 10-20% 的工作时间有后台 Agent 运行,仍在探索如何提高 |
Ghostty 的 AGENTS.md 中,规则对应着过去发生过的错误。这里可以检查一个很具体的问题:下一次遇到同类任务,Agent 能否从这条记录知道怎样操作?命令写错,就记录可用命令;项目约定没遵守,就说明约定适用于哪些文件。若同样的错误反复出现,还需要检查规则是否被加载,或将能自动判定的部分交给工具。
Birgitta Böckeler 对 Harness 的梳理
Birgitta Böckeler 在 Martin Fowler 网站讨论了 Harness 如何帮助工程师检查 Agent 产出。对照前面的 OpenAI 案例,可以从文档加载、架构约束和冗余清理三方面整理其工作:
| 归类 | 关注点 | 典型实践 |
|---|---|---|
| Context Engineering | 管理 Agent 看到什么、什么时候看到 | 从巨大 AGENTS.md 演化为入口文件 + 分层文档 |
| Architectural Constraints | 确保 Agent 不跑偏 | 自定义 Linter、结构测试、LLM Agent 充当约束 |
| Garbage Collection | 对抗熵积累 | 定期运行清理 Agent,扫描不一致和违规 |
这张表按工作内容归类,前面的六层表按执行职责拆分,两者用于不同角度的检查。例如,Linter 发现依赖方向错误后,报错仍需回到 Agent 的下一轮输入中;检查工具和上下文组织在同一次修复中会一起起作用。
她也提出了 Harness 模板的可能性。组织只使用少数技术栈时,开发环境、可用工具与通用检查可以随脚手架一起提供。但新项目的接口预期、模块依赖和测试数据仍需要单独确定,模板无法替项目回答这些问题。
旧项目尤其需要先看现有条件。类型检查能发现一类错误,明确的模块划分让依赖规则可检查,Spring 等框架则封装部分实现细节。Böckeler 将这类代码库本身提供的条件称为 Ambient Affordances。若一个模块缺少测试,依赖关系也不清楚,接入 Agent 后仍然要补这些工作;Stripe 的结果不能代替对当前仓库的检查。
还要把功能验收留下来。删除重复实现、修正依赖方向,并不能回答用户流程是否正确。前面已经提到测试与实现可能共享误解;这里需要能独立核对需求的验收依据,必要时由人实际操作检查。Böckeler 对依赖 AI 生成测试的局限也有相关讨论。
总结
检查 Harness 时,可以从最近一次未完成的任务入手:模型有没有拿到需要的信息,工具有没有成功执行,执行结果有没有进入下一轮,最终检查是否对应用户要求。沿着记录找到具体失败位置,才能决定改接口、补资料,还是调整测试。
接入一个新机制后,保留原任务再跑一次,并记录新增的耗时和费用。当前任务若只缺少一条可用测试命令,就先解决这一项;等到跨会话进度丢失、重复实现累积等问题实际出现,再增加相应处理。
Harness 也要随模型能力变化重新检查。某个 Linter、评估器或多 Agent 环节曾经必要,并不意味着它会一直保留。保留能捕获真实错误的机制,移除只增加上下文和编排成本的部分,才能让 Agent 在具体项目里稳定推进。
