Harness 工程（一）：五子系统概览

Open Table of contents

1. Harness 的五个子系统

Harness 由五个子系统组成。它们共同的架构思想是：下放出子任务、确保每个子任务的边界，让子任务之间协作配合。

子系统	职责
Instruction（指令）	给 Agent 介绍「游戏规则」，作为指南告诉 Agent 什么能做什么不能做
Tools（工具）	提供 Agent 可调用的能力（MCP、shell、测试命令、文件读写等）
Environment（环境）	控制执行环境（sandbox、依赖版本、`init.sh` 等），保证每次执行的安全与可回溯
State（状态）	自我位置与状态的认知——Agent 需要知道自己在哪、当前进度是什么
Verification（验证/反馈）	测试与校验功能，确保 TDD、语法正确等；让 Agent 摆脱「自卖自夸」

此外，Scope（范围管控） 是跨子系统的约束：界定每个 subagent 的任务边界，以及「怎样才算完成」。它主要归入 Instruction 与任务分解，而不是独立的第六个子系统。

Session Lifecycle（会话生命周期） 是 Environment 的子能力：确定每次会话如何开始、如何结束，并在出问题时支持回溯。

参考：OpenAI Harness Engineering、Martin Fowler — Harness engineering

在工程实践中，上述概念常映射为五个子系统：

实践子系统	对应概念	说明
指令子系统	Instruction + Scope	定义项目目的、技术栈、Agent 不可违反的硬约束；遵循最小化指令
工具子系统	Tools	MCP、shell、测试命令等可调用能力
环境子系统	Environment + Session Lifecycle	sandbox、依赖管理、`init.sh`、会话起止流程
状态子系统	State	让 Agent 清楚当前执行位置与进度
反馈子系统	Verification	迭代的关键，用测试与校验替代 Agent 的主观判断

Harness = 指令 + 工具 + 环境 + 状态 + 反馈，五个子系统缺一不可。

不是模型权重的部分全是 harness——你的 harness 决定了模型能力能被发挥多少。

在开始讨论解决方案之前，先明确大多数问题属于哪几类：

用户要求模糊。 让 Agent 进入工作区时，我们像带着模糊要求的甲方，Agent 会自己猜测未描述的需求。长任务中若 Agent 完成了不想要的实现，改起来代价很高。
版本与接口的隐性需求。 没有明示代码版本、接口契约或技术栈版本，容易导致实现与预期不一致。
环境配置。 长任务中难免出现 pip 安装、Node 版本冲突等问题。Agent 会分心处理环境；若不在 sandbox 中，失误还可能污染执行环境。
缺少验证手段。 不知道自己做得怎么样、什么时候该停，Agent 容易处于「自以为是」的状态，无法自我批判、迭代完善。
跨对话上下文断裂。 长任务无法在一个会话内完成时，新会话的 Agent 不知道之前做了什么，需要 Session Lifecycle 管理会话内与会话间的状态交接。

在 vibe coding 管理项目时，给自己立一条规则：遇事不决，先质疑自己的工程框架（Harness 设置），而不是模型的能力。

模糊描述：

添加一个搜索功能

标准描述（完成标准）：

在工作区根目录放一个 AGENTS.md，告诉 Agent 项目的技术栈、架构约定、验证命令。这是 harness 工程的第一步，也是投入产出比最高的一步——一个 AGENTS.md 可能比你换一个更贵的模型更有效，这话不是开玩笑。