Harness 的真相：落地不是框架，是一份 800 字的 AGENTS.md（36 次受控实验）

基于 Hermes v0.20.0 实测（2026-08-24，deepseek-v4-flash）。

📖 摘要：Harness 是 2026 年 AI 圈最热的词——「模型是大脑，harness 是手和脚」。但概念人人听过，落地长什么样却很少人见过。这篇文章用 36 次受控实验（3 种写法 × 4 个任务 × 3 轮）揭开真相：harness 落地的最小单元，就是一份 AGENTS.md。对比无约束、精简铁律、结构化三种写法，结构化写法达标率 100%、成本 1.44 倍，而看似稳妥的「精简铁律」反而触发过度验证、成本飙到 2.28 倍。附可复用的写法模板。

导读

• 目标读者：用 AI Agent（Claude Code / Codex / Hermes / Cursor 等）做交付、写过但觉得「约束文件没什么用」的开发者
• 你会得到：AGENTS.md 三种写法的实测对比数据、为什么「铁律」会失效、一套 800-1500 字的可复用写法模板
• 环境声明：实验在 Hermes v0.20.0 + deepseek-v4-flash 上执行，结论对其他 Agent 平台方向性适用

一、业务场景：Harness 概念满天飞，落地没人见过

2026 年，Harness Engineering 成了 AI 圈最热的概念。OpenAI 说「如果推理模型是大脑，harness 就是手和脚」；Terraform 作者 Mitchell Hashimoto 说「每次 agent 犯错，就工程化一个方案，让它再也犯不了同样的错」。概念一套套，人人都能聊两句。

但我们做 Agent 交付时发现一个尴尬的事实：概念好懂，落地难寻。你说 harness 是「环境」「约束」「工具壳」——那它到底长什么样？是一套框架？一个平台？还是别的什么？

很多人以为 harness 是什么高深的基础设施，但 OpenAI Codex 团队和 Hashimoto 的实践都指向一个朴素到近乎反高潮的答案：harness 落地的最小单元，就是一份 AGENTS.md——一个几百字的 Markdown 文件。Hashimoto 给 Ghostty 写的 AGENTS.md，每一行都对应 agent 过去犯过的一次错。

我们决定用实验验证这个「真相」：如果 AGENTS.md 真的是 harness 的落地形态，那「怎么写」就直接决定 harness 好不好用。于是有了这次 36 次受控实验。

二、场景痛点：约束文件写了，为什么没用

我们观察到三个典型失效模式：

1. 裸铁律被字面执行。写了「测试要全面」，agent 就真的把每个文件都翻出来测一遍——过度验证，耗时成本翻倍，产出反而变差。
2. 约束太长被稀释。几百条规则塞进一个大文件，agent 上下文有限，真正重要的纪律淹没在噪音里。
3. 只有要求、没有禁止。告诉 agent「要自测」，但没说「不许跳过编译直接交付」——它照样能在最该拦的地方漏掉。

写约束不是「写得多」，是「写得对」。这促使我们做了一次受控实验，用数据回答：到底什么写法有效？

三、解决方案：落地真相——AGENTS.md 就是 harness 的最小单元

在讲实验前，先建立框架：AGENTS.md 为什么是 harness 的最小单元？

Hashimoto 给 harness 下过一个朴素定义：「每次 agent 犯错，就工程化一个方案，让它再也犯不了同样的错。」 他给 Ghostty 写的 AGENTS.md，每一行都对应 agent 过去犯过的一次错。OpenAI 的 100 行地图哲学同理：AGENTS.md 只当目录和指针，把关键约束钉在顶层。

所以 AGENTS.md 不是「项目说明书」，是错误经验的固化载体——agent 犯过的错，写进约束文件，变成它下次的行为边界。

四、实验设计：36 次受控实验怎么做的

为了排除「感觉」，我们做了对照实验：

五、运行验证：实测结果

5.1 核心对比（36 次实测）

5.2 关键发现

1. 技能纪律梯度清晰：A 0/3 → B 2/3 → C 3/3 次加载技能。C 写法下 agent 每次都先加载技能再动手——「先加载技能」的铁律真正被内化。
2. B 的裸铁律触发过度验证：T2 任务平均消耗 766k tokens（A 的 3 倍！）——写了「测试要全面」它就把全项目翻出来测。C 用「要求+禁止」成对写法，成本可控。
3. 事实完整性差异：B 有一次从局部日志推断整体（把「3 变体 36 轮」说成「双变体 24 轮」）；C 每次都读完整方案文件、说对。「禁止从局部推断整体」从此写进我们的纪律。
4. C 的约束直接体现在输出格式：表格化、来源标注、汇报三要素逐项出现——约束文件管什么，产出就长什么样。

六、落地建议：约束文件写法要素（可直接复用）

实验结论收敛成一套可复用写法（800-1500 字，超过 3000 字稀释上下文）：

1. 分节：角色 / 执行纪律 / 输出格式 / 禁忌——四节各管一摊
2. 纪律表格：要求与禁止成对（| 纪律 | 要求 | 禁止 |）——只有要求没有禁止，agent 会字面执行成过度行为（B 变体的教训）
3. 「事实完整」纪律必带：涉及范围/数量/结论的事实必须核对完整来源，禁止从局部信息推断整体
4. 分层：项目级约束（AGENTS.md）管输出形态；全局级约束（SOUL/USER/MEMORY）管行为纪律——同样一句话，放 SOUL.md 内化执行（成本 1.59×），放 AGENTS.md 字面执行（成本 2.28×）
5. 记忆是信息不是纪律：行为纪律进身份层（触发强），信息（偏好/环境）进记忆层（触发弱）

一个 AGENTS.md 模板片段（真实模板节选）：

## 执行纪律

| 纪律 | 要求 | 禁止 |

|------|------|------|

| 技能 | 动手前先加载对应技能 | 禁止凭记忆硬写 |

| 自测 | 写完代码立即执行验证 | 禁止跳过测试直接交付 |

| 事实完整 | 结论核对完整来源 | 禁止从局部日志推断整体 |

## 输出格式

- 中文标题，关键信息用表格呈现

- 汇报三要素：做了什么 / 实测结果 / 遗留问题

七、实战坑（实测踩出来的）

八、启示

回到开头那个问题：harness 落地到底长什么样？36 次实验给出的真相是：落地不是一套框架，是一份 800 字的 AGENTS.md——它的本质不是「写要求」，是把 agent 犯过的错固化成行为边界。而这份文件的写法，直接决定 harness 是可靠的缰绳还是勒脖子的死结：结构化、成对、分层，缺一不可。

概念听得再多，不如亲手写一份。下次 agent 反复犯同一个错时，别急着骂模型，也别急着搜什么 harness 框架。问自己一句：这个错，值得写进 AGENTS.md 吗？如果值得，怎么让它在 800 字内、以「要求+禁止」的形式出现？

这就是 harness 的落地——不在 PPT 里，在你项目根目录那份几百字的 Markdown 文件里。

本文基于真实实测记录撰写（Hermes v0.20.0 + deepseek-v4-flash 环境，101/101b 受控实验数据）。实验环境为 WSL，结论对其他 Agent 平台方向性适用，不构成任何平台的官方结论。