Harness Engineering：引导、约束与整合

上下文工程、MCP、Skills、记忆、压缩——都在解决一个问题：Agent 是否获得了足够的信息。这些机制只决定 Agent 知道得够不够。当 Agent 开始写文件、运行命令、操作外部系统时，会出现另一组问题：

• 执行方向是否正确？偏离后能否纠正？（方向）

• 哪些操作不允许执行？误删文件由谁拦截？（安全）

• 这些能力如何组织成一个能稳定运行的系统？（编排）

Harness 可以按构建者和使用者分成两层：

图：Harness 的两层同心圆

三个同心圆：核心是模型，外一圈是 Agent 构建方的 Harness（System Prompt、代码搜索工具、编排等），最外圈是 Agent 使用者的 harness（针对自己系统配置的前馈和反馈控制）。 做产品的提前设好条条框框，管住大模型能干啥； 用产品的就在这套规则里自由操控智能体和模型干活。

三类能力：驾驭、约束、整合

Harness 一词原指套在马身上的整套装备。从词源出发可以拆出三类能力，对应 Harness 要解决的三个方面：

图：驾驭 / 约束 / 整合

1. 驾驭（Steer）控制Agent执行方向、停止时机。对应具体机制：System Prompt / 规则文件（WORKBUDDY.md、AGENTS.md）说明工作方式；Skills 规定某类任务的步骤；Task / Todo 把大目标拆成任务清单；错误消息中的自我纠正提示在卡住时提供方向（而非只给错误码）。

2. 约束（Constrain）防止执行超出安全范围。对应具体机制：权限边界（误删文件需要被拦截）、Sandbox（隔离环境，执行出错也不影响本机）、Approval Gate（危险操作需要人工确认）、Allowlist/ denylist（限定可操作的命令和路径），以及测试验证、rollback、audit log。

3. 整合（Integrate）把各项能力配齐并协同。对应具体机制：执行能力（tools、MCP、browser、filesystem）、状态承载（memory、logs）、协作机制（subagents、hooks、connectors）、自动化（CI、定时任务）。整合的作用在于编排和协同：谁先调用谁、谁触发谁、谁的输出回传给谁。

这三类能力必须共同工作：只有引导没有约束，Agent 可能执行不该执行的动作；只有约束没有反馈，出错后无法修正；工具多但缺编排，长任务难以稳定完成。

业界三家的实践

在讨论 WorkBuddy 的做法之前，先看三家有代表性的实践：OpenAI、Anthropic 和 LangChain。

图：OpenAI 实践

OpenAI：一个 3 人小组用 Codex 从空仓库开始开发，全程不手写代码，5 个月产出约 100 万行代码、1500 个 PR，并投入内外部使用。他们配套的机制包含：

• 让 Codex 直接操作浏览器、读取 DOM / 日志 / 监控指标；
• 用 linter 和结构测试自动检查架构分层、依赖方向、命名和文件大小；
• 把 AGENTS.md改成目录入口、把详细知识结构化放进 docs 供按需查询；
• 后台运行周期性任务扫描代码漂移、自动创建重构 PR。

这一案例说明在配套机制完整时，Agent 可以参与大规模代码生产。但其 Harness 主要集中在代码内部质量和可维护性上，没有说明功能和业务正确性如何维护。

Anthropic（第一篇：Effective harnesses for long-running agents）：处理长任务时发现两种典型失败：Agent 一次承担过多工作（中途耗尽上下文、给下一个 Agent 留下缺少说明的半成品），或看到部分成果就过早判定完成。

解决方案：一开始就把要做的事拆成 200+ 条具体行为描述的功能清单（JSON）、每条标 pass/fail 并禁止删条目或降标准；一次只处理一项任务；统一的启动脚本 init.sh；除单测外用浏览器自动化做端到端验证；用进度文件 + Git 历史做交接、恢复和回滚。

WorkBuddy 的 Agent 在这一点上做了类似设计：执行较大任务时，先把目标拆解成结构化任务清单，并在推进过程中持续更新状态。同时解决“一次承担过多 / 过早判定完成”和“上下文遗忘”两类问题—显式任务状态可以让 Agent 在长对话里恢复进度，也让用户更容易判断任务是否真的完成。

图：跨会话任务交接

Anthropic（第二篇：Harness design for long-running application development）：在前一篇基础上发现两个更深的问题——接近上下文上限时模型会降低完成标准偷懒、自我评估不可靠（Agent 评价自己产出时倾向给正面结论，前端设计这类缺少确定性测试的任务尤其明显）。

方案借鉴 GAN 的对抗评估思路，用Claude Agent SDK 构建三个角色：Planner（把一句话需求展开成完整规格，定范围但不指定实现细节）、Generator（按 sprint 逐功能实现、用 git 版本控制、提交前先自检）、Evaluator（独立验收 Agent，用 Playwright 像真实用户一样操作运行中的应用，逐条核查、把 bug 定位到行号和原因后打回）。

其中可以借鉴的点：分离执行和验收（验收角色可用不同模型，或在 WorkBuddy 里用 Teams 分工）、把标准写进规则文件、先确认需求再执行、随模型升级精简约束。

图：Planner / Generator / Evaluator

LangChain：langchain 从框架构建者角度，把 Agent 中除模型之外的一切都纳入 Harness——系统提示词、Tools / Skills / MCP、文件系统、沙箱、浏览器、编排逻辑与 Hooks，这是一个更宽的定义：Agent = Model + Harness。它的几个核心观点：

• Agent 要有持久状态、能跨会话工作；
• 无法为每件事预先准备工具，所以要给 Agent 一台计算机（Bash + 代码执行）；
• 要能安全可扩展地运行代码、能自我验证；
• 用压缩、工具结果卸载、Skills 渐进式加载等机制应对 Context Rot；
• 用 Ralph Loop（Hook 拦截提前结束信号，在新上下文里重新注入目标继续执行）。

LangChain 还提出一个视角：模型和 Harness 在共同进化。实际评估的对象通常是“模型 + Harness”的组合——同一个模型换了工具名、Patch 格式、压缩策略或错误回传方式后，表现可能明显变化。因此比较或升级模型时，要把 Harness 一起纳入 Eval。

WorkBuddy Agent 的五层 Harness（构建者视角）

WorkBuddy 构建良好的 Harness 有两个目标：提高 Agent 首次执行的正确率，并提供反馈循环让系统能自动发现和纠正常见问题。

在 WorkBuddy 的设计里，Harness 是一个控制系统：Agent 行动前，系统通过前馈(预注入)（Feedforward）提供目标、规则、环境和可用能力；Agent 行动后，系统通过反馈传感器（Feedback sensors）观察结果，并把错误和修正信息返回给 Agent。

前馈提高第一次就做对的概率，反馈让 Agent 在问题进入人工审查前先自我纠正。只有前馈没有反馈，规则是否有效无法验证；只有反馈没有前馈，Agent 会反复犯同类错误，再依赖后置修正。

这两类控制还可以按执行方式分成“计算型”和“推断型”。计算型控制由确定性程序执行，例如语言服务器协议LSP、类型检查、linter、单元测试、结构测试、依赖扫描、脚本和 codemod，优点是快、便宜、可重复，适合在 Agent 每次修改后反复运行。推断型控制依赖模型做语义判断，例如 Review Agent、架构审查 Agent、AI judge 和设计评估，优点是能覆盖“是否过度设计”“是否误解需求”“是否符合团队约定”这类难以写成规则的问题，缺点是更慢、更贵，也更不确定。

WorkBuddy 的原则是：能用计算型信号解决的问题，优先交给确定性程序；需要语义判断的问题，再交给审查 Agent。反馈也要按时机分层：快速检查尽量前移到代码编辑后、提交前或 Agent 自我纠正循环中；更昂贵的架构审查、详细代码审查、端到端验证放到代码集成前后；代码持续腐化和运行时健康则交给定时巡检工具，如死代码扫描、覆盖率质量分析、依赖风险、延迟、错误率、服务指标 和日志异常。这样 Harness 不只是一组规则，而是一套持续运行的控制系统。

图：Harness 五层结构

五个层次：

1. 运行环境层：Agent 在哪里执行。

文件系统、Shell / Bash、Sandbox、Browser、MCP / Connectors、权限边界 / Approval Gate、Allowlist/ denylist。这一层用户通常感知不到，但缺少任何一项，上面几层都难以稳定运行。LangChain 指出，文件系统是 Agent 最基础的运行环境，它支撑了持久状态、跨会话工作和多 Agent 协作。

2. 引导层（Feedforward）：Agent 开始前掌握什么。

在执行前提供必要信息和约束，提高首次正确率。包括：项目上下文（项目概况、目录层级、关键依赖—早期模型不会主动探索代码库，可能在根目录写错文件）、环境上下文（操作系统、Shell、时间、时区、地理位置、产品语言、已装 Skills、已连 Connectors）、规则与风格（不同模型不同倾向）、工具使用规则（独立的搜索 / 读取可并行、改文件前先读、路径不明先搜、长任务先拆 Todo）、Skills 和规则文件（把隐性知识保存成 Agent 能读到的内容）、上下文结构与 Prompt Cache（保持稳定前缀、追加动态内容、按需加载工具）。

3. 反馈层（Feedback）：Agent 执行后如何获知错误。

验证执行结果并把错误及修正信息返回给 Agent。工具结果包含可纠正信息（文件未找到提示搜索路径、编辑失败提示重新读取、权限不足提示请求确认、命令报错返回完整 stderr）——OpenAI 把 Agent 受阻视为“环境中缺少工具、规则或文档”的信号。编辑前的时间戳校验：Agent 改文件前比较“上次读取时间”和“文件最后修改时间”，若读取后被用户改过就拒绝写入、要求重读，避免覆盖最新修改。将外部验证信号返回 Agent：lint、类型检查、测试、构建等确定性信号成本低、可稳定重复；架构审查、代码审查和端到端验证这类推断型或高成本信号，则按风险放在更靠后的检查阶段。再加上 Audit log 让所有动作留痕、可追溯回放。

4. 编排层/RunTime层：多个能力如何组织。

按任务组织能力、按需暴露上下文、为不同角色分配职责：渐进式加载、意图识别和路由、多模型路由、Teams 多 Agent 协作、并行工具调用。

5. 迭代层：Harness 自身如何持续调整。

前面四层要随模型能力、用户场景和已发现的问题持续迭代。WorkBuddy 主要用了几种迭代方式：

• 模型能力提升后精简上下文：新模型能用 Glob / Grep 自主探索项目结构后，项目概览就可以缩减；
• 出现新问题增加约束：输出过长、格式不稳定时补充更明确的行为边界；
• 按模型配工具：根据实际表现调整工具组合；
• 针对重复问题增加机制：反复出现文件覆盖、能力选择混乱等问题时就对应补充写入保护、能力发现机制。

这类迭代需要证据支撑：一次失败可能是偶发，同类失败多次出现或风险很高时再调整 Harness。新增机制也要评估副作用：更严格的审批降低误操作风险，也增加打断；更多规则约束输出，也占用上下文。

WorkBuddy 团队作为使用者，如何建立 Harness

借用 OpenAI Codex 实验总结的四类组件，可以把 WorkBuddy 团队的现有实践归入同一框架。

图：使用者视角的四类组件

1. 上下文工程：让 Agent配齐完成任务所全部信息。通过分层规则文件（根目录里的AGENT.md/ WORKBUDDY.md记录整体架构、依赖、安全和风格；子仓库用局部 WORKBUDDY.md补充）、OpenSpec（较大变更先读写规范文件）、Skills（按任务加载）、斜杠命令封装常用操作流程。

2. 架构约束：把规则变成可执行检查。团队可以把架构规则、代码规范和提交要求接入本地检查、Git Hooks、CI 门禁和审查 Agent。确定性问题优先交给程序检查，需要语义判断的问题再交给审查 Agent。

3. 反馈循环：把验证结果返回给 Agent让其自我修正。包括编辑后检查点（每次修改代码后校验代码行数、架构合规性、注释完整度）、本地检查与 CI 结果、/team:mr工作流（构建验证 → 生成变更集→ 创建 MR → 关联 Issue）对应 OpenAI 的表述：

“Agent 卡住时，我们把它当作信号——找出缺了什么（工具、护栏、文档），反哺回仓库——而且总是让 Codex 自己写这个修复。”

4. 垃圾清理：持续处理规则、代码和运行状态的偏差。现有检查主要防新增问题，对历史问题还要周期性扫描：WORKBUDDY.md/ OpenSpec 与代码是否一致、历史代码是否违反新规则、是否有重复实现 / 失效文档 / 过期依赖。

这四类组件形成一个持续过程：上下文工程提供规则和任务信息，架构约束阻止已知违规，反馈循环帮 Agent 修正本次执行，垃圾清理处理跨任务积累的漂移。

还没解决的问题

现在讲 Harness 的文章大多只聊架构划分、命名规范、代码复杂度、技术债务、自动重构，很少聊怎么验证功能和业务逻辑对不对。之所以缺少一套能批量落地的业务校验方案，主要是四点：

第一，需求本身很难被说明。产品文档一般只单独讲一个个功能，很少说明多个功能搭配使用会是什么效果。举个例子，会话既能置顶又能归档，两个功能单独测都没问题，但组合起来就有疑问：已经置顶的会话允许归档吗？文档没写清楚的话，Agent 会自己脑补一套规则，代码和测试用例全都按它这套理解去写。所有自动化检查全部通过，实则悄悄加入了没有经过业务确认的逻辑。

第二，代码实现和测试容易同流合污。如果同一个 Agent 同时开发功能、编写测试，一旦它理解错需求，bug 会同时留在代码和测试里。哪怕所有测试跑通，也没法保证程序符合业务原本想要的效果。

第三，业务正确性很难量化评判。编译器能查语法、类型错误，监控可以统计性能、报错指标，可业务逻辑是否合理，大多必须业务人员人工确认。

第四，业务逻辑出错代价巨大。核心业务一旦出错，容易引发资金亏损、合规风险、用户流失，所以相比普通代码质量问题，我们对业务验证结果的可靠性要求高得多。