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 次实验换来的三句话。
💬 你踩过「Agent 过度听话」的坑吗？欢迎评论区分享你的铁律翻车现场。
下一篇：Hermes Agent 调教实录（二）：给 AI Agent 写记忆的学问
