https://blog.cpdd.fyi/tags/agents.md/Recent content in AGENTS.md on Zampo BlogHugozh-cnWed, 22 Jul 2026 17:45:50 +0800https://blog.cpdd.fyi/posts/agents-md-minimal-contract/Wed, 22 Jul 2026 17:45:50 +0800https://blog.cpdd.fyi/posts/agents-md-minimal-contract/<p>Agent 回答“已完成”时，改动已经落到文件里了。人一复核，才发现它从仓库根启动，却把 <code>services/payments/</code> 的规则当成全项目规则；又或者它从几份互相打架的说明里，挑了一条已经废弃的测试命令跑了一遍。</p> <p>这类返工很烦，因为 agent 看上去并没有偷懒。它读了文档，也执行了命令。只是它从一开始就在猜：该在哪个目录干活，哪份说明算数，怎样才算真的完成。</p> <p>我现在看项目里的 <code>AGENTS.md</code>，先不看它写了多少流程。我先看它有没有把这三件事写死：边界、唯一事实源、完成标准。</p> <p><strong>AGENTS.md 最有价值的工作，是让 agent 少猜。</strong></p> <h2 id="同名文件进到不同-agent-里可能已经不是同一种东西">同名文件，进到不同 agent 里可能已经不是同一种东西</h2> <p>不少团队看到 <code>AGENTS.md</code> 这几个字，就默认它是一套可移植的项目约定。这个直觉很容易害人。</p> <p>Codex 的官方说明里，项目指令会从项目根往当前工作目录逐层拼接，越靠近当前目录的文件越后出现。它还会在每一层优先选择 <code>AGENTS.override.md</code>，再选择 <code>AGENTS.md</code>。你在仓库根运行，和在 <code>services/orders/</code> 里运行，拿到的指令链可能不同。[1]</p> <p>Claude Code 的主文件叫 <code>CLAUDE.md</code>。它会从当前工作目录向上找 <code>CLAUDE.md</code> 或 <code>CLAUDE.local.md</code>；子目录的内容也不会在启动时一股脑塞进来，Claude 读到对应子目录文件时才会按需带入。需要按目录或文件类型定规则时，官方提供的是 <code>.claude/rules/</code>。[2]</p> <p>Hermes 也兼容 <code>AGENTS.md</code>，但发现语义又换了一套：当前文档说明，<code>.hermes.md</code> / <code>HERMES.md</code>、<code>AGENTS.md</code> / <code>agents.md</code>、<code>CLAUDE.md</code> / <code>claude.md</code>、Cursor rules 按优先顺序命中一种来源。<code>AGENTS.md</code> 与 <code>CLAUDE.md</code> 按当前工作目录查找，父目录和子目录副本不会自动合并；它自己的 <code>.hermes.md</code> 才会向上查到 Git 根。[3]</p> <p>这不是要你给三套工具各写一份百科全书。它提醒的是：写任何上下文文件前，先把作用域问明白。</p> <p>“从仓库根启动，适用于 <code>services/orders/**</code>。”</p> <p>这句话看着土，却比一页构建历史更管用。它让人和 agent 都知道，眼前这份规则到底落在哪一块代码上。monorepo 里尤其要把这件事写出来：哪个子包能改，迁移目录能不能碰，当前任务从哪里启动。否则根目录有一份文件，只是维护者的想象；具体 agent 是否会读到、怎样叠加，取决于它自己的发现规则。</p> <h2 id="文件越像运行手册过期后越容易把人带偏">文件越像运行手册，过期后越容易把人带偏</h2> <p>我见过很多越写越长的 <code>AGENTS.md</code>：环境变量、端口、接口字段、部署顺序、线上故障记录、临时迁移状态，全堆在一起。每次 agent 按旧命令做错，大家就再补一句“注意”。</p> <p>然后这份文件慢慢长成了一个谁都不敢删的缓存。</p> <p>问题不在于命令不能写。稳定、每次都会用到的入口，当然该留。问题在于，同一个事实被复制到 <code>AGENTS.md</code>、README、Runbook 和 CI 里，迟早会分叉。agent 没有能力替你判断哪一份历史更新，它只会在自己读到的内容里挑一条看起来合理的路。</p>https://blog.cpdd.fyi/posts/agents-md-not-universal-prompt/Wed, 17 Jun 2026 22:52:57 +0800https://blog.cpdd.fyi/posts/agents-md-not-universal-prompt/<p><img src="https://blog.cpdd.fyi/images/agents-md-not-universal-prompt/cover.svg" alt="AGENTS.md 分层职责图"></p> <p>晚上十一点多，我盯着终端里那段 diff，第一反应不是生气，是有点懵。</p> <p>我明明只让 Agent 改一个很小的接口判断。结果它顺手动了 service，改了 model，又把测试绕过去了。最后还很认真地补了一段解释：这些改动是为了保持架构一致性。</p> <p>这句话最气人。</p> <p>它不是胡来。它看起来甚至很努力。可你知道，这个项目里权限逻辑不能这么碰，数据库字段不能顺手改，测试没跑就说“已验证”更不能接受。</p> <p>于是你打开 AGENTS.md，开始往里面加规则。</p> <p>不要乱改。不要跳过测试。不要引入没确认的依赖。不要动工作区外的文件。不要提交。不要重构。不要假装验证。</p> <p>过几天，它还是会在另一个地方犯同类错误。</p> <p>更烦的是，它不是每次都乱。小改时挺听话，一到多文件联动、接口变更、数据库字段、安全策略，它又开始像一个拿到权限但没进过项目组的人：先动手，动完再解释。</p> <p>这时候很多人的第一反应是继续加规则。</p> <p>AGENTS.md 越写越长，CLAUDE.md 越写越像公司制度，Cursor Rules、OpenSpec、Superpowers、各种 skill 又各写一套。最后真正开工前，Agent 先读半天，人也要猜半天：今天到底该按哪份规则来？</p> <p>问题不一定是规则太少。</p> <p>更多时候，是你把不同层级的规则塞进了同一个入口。</p> <p>AGENTS.md 不该是咒语大全。它更像 Agent 的入职导航。</p> <p>它最重要的工作，不是把每一条纪律都背给 Agent 听，而是告诉它：这类问题去哪里读、什么事情必须先停下来、哪些文件才是当前项目真正的制度。</p> <h2 id="agentsmd-越长未必越稳">AGENTS.md 越长，未必越稳</h2> <p>AGENTS.md 官网对它的定位很朴素：README 是给人看的，AGENTS.md 是给 Coding Agent 看的。构建步骤、测试命令、代码约定、安全注意事项，这些不适合塞进 README 的 Agent 细节，可以放在这里。</p> <p>这句话容易被误读。</p> <p>很多人会把它理解成：既然 Agent 会读 AGENTS.md，那所有规则都往里面放。</p> <p>于是一个文件开始膨胀：项目背景、架构说明、业务概念、测试命令、提交规范、分支策略、重构原则、安全边界、调试流程、代码风格、长期 roadmap，全放进去。</p> <p>看起来很完整。</p> <p>但 Agent 真正执行任务时，完整经常不等于清楚。</p> <p>你让它修一个拼写错误，它读到一堆“重大变更必须先开 proposal”；你让它改认证策略，它又在同一个文件里看到“低风险修改可以直接执行”。规则没有分层，它就只能临场猜：这次到底算 typo，还是架构变更？</p> <p>不给 Agent 分级，它就会把 typo 和架构重构用同一种速度处理。</p> <p>这不是模型笨，而是制度没说清。</p> <p>人类团队不会把新人入职手册、年度规划、数据库迁移审批、单元测试规范、代码评审 checklist 全塞进同一页 Notion。因为每类信息解决的问题不一样。</p>