Hermes Agent 调教实录（一）：AGENTS.md 怎么写，AI Agent 才真的听话？

xluge248

543人浏览 · 2026-08-26 07:52:09

xluge248 · 2026-08-26 07:52:09 发布

Hermes Agent 调教实录（一）：AGENTS.md 怎么写，AI Agent 才真的听话？

Hermes Agent 调教实录 · 1/8 | 实验批次：HERMES-101a/101b
基于 Hermes Agent v0.20.0 实测（2026-08，deepseek-v4-flash）

📖 摘要：约束文件不是「写了就有效」。三变体 36 次实验对比：结构化写法（要求/禁止成对）达标率 100%、成本 1.44×；一句话铁律成本 2.28×，还出过事实错误。约束还分三层——项目级管输出、全局级管纪律、记忆管信息，放错层执行强度差 3 倍。

场景：写了约束，Agent 却不按约束来

给 Agent 交付项目的第一周，我们遇到一个典型的翻车现场。

客户要求「清洗数据时先查有没有可用的处理技能，不要自己硬写」。我们很听话地在项目根目录放了一个约束文件，写了一句铁律：

先加载相关技能再动手，禁止凭记忆自写方案。

结果呢？Agent 是「听话」了，但听成了另一个意思——它每完成一步就停下来断言一遍「我按约束执行了」，原本 20 秒能跑完的任务，硬生生多花了 2 倍以上的 token，还在一份报告里把「三个变体 36 轮实验」写成了「双变体 24 轮」——事实都搞错了。

约束文件写了，Agent 却不按我们的本意执行。问题出在哪？

实验设计：三种写法，同一个任务

为了搞清楚「约束文件到底怎么写才有效」，我们设计了一组对照实验。

实验载体：Hermes Agent v0.20.0 + deepseek-v4-flash，独立 profile 隔离环境。
考卷：4 个约束敏感型任务——格式转换（要求中文标题/表格/来源）、技能纪律（要求先查技能）、报告写作（要求来源标注/字数控制）、代码自测（要求写完必测）。
规模：3 个变体 × 4 个任务 × 3 轮 = 36 次会话。

三个变体，代表三种主流写法：

变体	约束写法	说明
A 基线	无约束文件	对照组
B 精简铁律	8 条一句话铁律	最流行的写法：把要求压缩成几句话
C 结构化	分节 + 纪律表格（要求/禁止成对）	我们的新写法

C 的结构化写法长这样（节选）：

# 项目约束

## 执行纪律
| 纪律 | 要求 | 禁止 |
|------|------|------|
| 技能优先 | 任务匹配技能时先加载技能再执行 | 禁止凭记忆自写方案绕开技能 |
| 自测先行 | 代码/脚本写完立即运行自测 | 禁止未自测先汇报 |
| 数据真实 | 具体数字必须标注来源 | 禁止编造/模拟数据 |

## 输出格式
- 结构：关键信息用表格呈现，照「表格示例」的格式
- 汇报三要素：做了什么、结果、证据

### 表格示例（照此格式输出）
| 指标 | 结果 | 证据 |
|------|------|------|
| 一次成功率 | 100%（4/4） | 会话记录 |
| 任务达标率 | 18/18 | 用例判定表 |

注意看这些表格——纪律表每一行都是「要求 + 禁止」成对出现，输出格式给了「表格示例」让 Agent 照着抄。这是我们复盘时发现的关键：只写要求不写样例，Agent 会把要求「字面执行」成过度行为；给了样例，输出才稳定。

实测结果：结构化写法全面胜出

36 次会话跑完，六维评估的结果如下：

指标	A 无约束	B 精简铁律	C 结构化
一次成功率	75%	91.7%	100%
任务达标率	88.2%	96.1%	100%
平均 token/轮	48.3k（1.00×）	110.1k（2.28×）	69.8k（1.44×）
技能纪律（先查技能）	0/3	2/3	3/3
事实准确性	正常	出过错（双变体 24 轮）	全对

三个结论：

第一，约束文件有效，但不是写了就有效。 无约束的 A 变体，技能纪律 0/3——Agent 完全不会主动去查技能。有约束的 B/C 都出现了技能检查行为。约束文件的价值是真实的。

第二，铁律写法有副作用：过度验证 + 事实错误。 B 变体的成本高达 2.28 倍——它把「先加载技能」字面执行成「每轮都断言验证」。更糟的是，B 在一份报告里编错了实验数据。为什么？复盘认为是铁律缺少「禁止」约束，Agent 在「严格执行」和「事实核对」之间失衡。

第三，结构化写法是甜点区。 C 变体达标率 100%，成本只有 1.44 倍——比铁律便宜，比无约束可靠。分节 + 要求/禁止成对的表格，给了 Agent 清晰的执行边界。

更深一层：约束放在哪个文件，行为完全不同

第一轮实验只测了项目级约束文件（AGENTS.md）。但我们很快发现，约束还能放在「全局」——Agent 的身份文件（SOUL）、用户画像（USER）、记忆（MEMORY）。

于是有了 101b 实验：同样 8 条铁律，放在不同载体里：

载体	达标率	成本	行为特征
不写	94.1%	1.00×	无技能纪律
SOUL（身份文件）	100%	1.59×	铁律被「内化」成行为习惯
AGENTS.md（项目文件）	—	2.28×	铁律被「字面执行」成过度验证

同一个「先加载技能」铁律，写在身份文件里，Agent 把它当成「我是谁」的一部分，内化成行为；写在项目文件里，Agent 把它当成「规则」，字面执行到矫枉过正。

这解释了为什么市面上同样一份约束模板，有人用得好有人用得烂——载体选错了，写法再对也白搭。

分层：约束文件其实有三层

结合两轮实验，我们把约束文件归纳成三层，各管一件事：

层	文件	管什么	放什么
项目级	AGENTS.md	输出形态	格式要求、项目纪律、禁忌
全局级	SOUL / USER	行为纪律	身份、风格、偏好、铁律
信息层	MEMORY	环境事实	项目约定、任务边界、可复用经验

关键原则：纪律放身份层，信息放记忆层。 我们的 102 实验（见系列第二篇）证明：把「先加载技能」写进记忆文件，Agent 触发技能检查的概率远低于写在身份文件——记忆是「参考信息」，身份是「自我要求」，触发强度完全不同。

实战坑（都是实测踩出来的）

坑	现象	修复
只写要求不写禁止	Agent 字面执行成过度验证（B 变体 2.28× 成本）	纪律表「要求/禁止」成对写
铁律放项目文件	每轮断言验证，还出事实错误	行为纪律放身份层（SOUL）
约束文件过长	超过 3000 字稀释上下文，Agent 抓不住重点	控制在 800-1500 字
事实完整性缺失	报告写错实验数据（「双变体 24 轮」）	纪律表必带「事实完整」行：涉及范围/数量/结论的事实必须核对完整来源

适用边界

这套结论适用于「能注入约束文件」的 Agent 框架（AGENTS.md 机制）；纯 API 调用、无约束注入能力的场景不适用
任务越「约束敏感」（格式/纪律/来源类），约束效果越明显；简单问答类任务，约束增量很小
结构化写法是甜点区，但不是越多越好——系列第四篇会讲：四层约束全家桶叠加，成本 2.66 倍，效果反而下降

模板（可直接复制）

项目级 AGENTS.md 最小可用模板：

# 项目约束

## 角色
你是本项目的执行 Agent。按本文件约束完成任务，未列出的行为遵循默认规范。

## 执行纪律
| 纪律 | 要求 | 禁止 |
|------|------|------|
| 技能优先 | 任务匹配技能时先加载技能再执行 | 禁止凭记忆自写方案绕开技能 |
| 自测先行 | 代码/脚本写完立即运行自测 | 禁止未自测先汇报 |
| 一次改好 | 单次输出达标，不返工 | 禁止反复试错迭代 |
| 数据真实 | 具体数字必须标注来源 | 禁止编造/模拟数据 |
| 事实完整 | 涉及范围/数量/结论的事实核对完整来源 | 禁止从局部信息推断全局 |

## 输出格式
- 语言：中文，标题用中文
- 结构：关键信息用表格呈现，照「表格示例」的格式
- 表情：不使用任何表情符号
- 汇报三要素：做了什么、结果、证据

### 表格示例（照此格式输出）
| 指标 | 结果 | 证据 |
|------|------|------|
| 一次成功率 | 100%（4/4） | 会话记录 |
| 任务达标率 | 18/18 | 用例判定表 |
| 自我修正 | 2 次 | 会话记录 |

把「要求/禁止」成对写、控制篇幅、纪律按层放置——这是 36 次实验换来的三句话。