AGENTS.md 设计原则：好的入口文件等于免费换模型
四月底我干了一件事：把我们主仓库里那份 CLAUDE.md 整个删了重写。
那份文件的来历很典型——刚接入 AI Coding 的时候，图省事，直接让模型「分析这个仓库，生成一份 CLAUDE.md」。它生成出来的东西看起来非常专业：目录结构、技术栈清单、编码规范、注意事项，洋洋洒洒四百多行。团队里没人细看，反正「有总比没有强」，一放就是三个月。
促使我重写的是一次很小的事故。让 Agent 加一个导出接口，它在动手前花了七八分钟、烧了大概四万 token 去读各种不相关的文件——包括一个早就废弃的 legacy 目录。我翻执行日志才发现，那份自动生成的 CLAUDE.md 里赫然写着「修改任何接口前，请先全面理解 legacy/ 目录下的历史实现」。这句话是模型自己脑补的，仓库里从来没有这条规矩。Agent 忠实地执行了一条不存在的规则，而我们三个月没发现。
「有总比没有强」是错的
后来我看到 ETH Zurich 的一个研究，算是给我的直觉补了数据。他们测了 138 个真实项目的 AGENTS.md：LLM 自动生成的配置文件，让任务成功率下降约 3%，推理成本上升超过 20%。只有人工精心编写的文件才有正向收益。
原因和我们踩的坑一模一样：自动生成的文件塞满冗余规则、目录结构罗列、各种想象出来的 if-else 条件，每次会话全量注入，挤占的是模型真正干活的注意力。
Augment Code 那边有个更狠的数据：同一份 AGENTS.md，在常规 bug 修复上 +25% 质量，在同一模块的复杂功能开发上 -30% 完整性。正负三十个点的波动。所以这东西不是「锦上添花的文档」，是一个方差极大的杠杆——用对了等于免费升级模型，用反了等于花钱买降级。
重写过程
我重写的过程大概花了两个下午，几个决策记录一下。
第一刀：从 430 行砍到 120 行。 砍掉的内容包括：完整目录树（模型自己会 ls）、技术栈介绍（package.json/go.mod 里都有）、二十多条「注意」「务必」「不要」（大部分是自动生成时的废话）。留下来的标准只有一个：这条信息模型自己找不到、或者找起来很贵。
为什么是 120 行？当时是凭手感，后来看到 Augment 的数据说这一代模型对入口文件的注意力甜区在 100-150 行，算是撞对了。
第二刀：把「描述」改成「决策」。 原来的文件里写「本项目 API 层遵循 RESTful 风格」——这种话对 Agent 毫无用处，它需要的是二选一时的答案。改成表格：
新增接口 -> api/v2/ 下新建，禁止动 v1
改已有接口 -> 必须加兼容层，见 docs/compat.md
需要新增依赖 -> 停下来问人，不要自己 go get
数据库变更 -> 只写 migration 文件，禁止直连执行
这个格式是我们试出来最有效的。散文式的规范模型会「理解」但不一定「执行」，决策表几乎百分之百执行。
第三刀：每条「不要」配一条「要」。 原文件里有十几条孤立的禁令。我观察到的现象是：禁令太多的时候，Agent 会进入一种畏首畏尾的探索模式——它知道到处是雷，但不知道路在哪，于是疯狂读文件确认。后来给每条禁令都补了出路（「不要 X，改用 Y」），过度探索的现象基本消失。
第四刀：写现状，不写愿景。 这是最反直觉的一条。我们的代码库里有些不光彩的妥协——比如有个模块的 service 层直接 import 了 ORM，按理说不应该。旧文件写的是理想架构（「领域层不依赖框架」），结果 Agent 每次碰到那个模块都很困惑：遵守文档就改不动代码，遵守代码就违反文档，最后在两者之间反复横跳。新文件我直接写：「billing/ 模块历史原因分层不干净，改这里时跟随现有风格，不要试图修复架构。」不体面，但有效。
一个容易忽略的事实：位置决定命运
为什么这些内容要写在 AGENTS.md 而不是 docs/ 里？因为发现率完全不是一个量级。Augment 追踪了数百个 session：AGENTS.md 的发现率接近 100%（每次会话强制注入），README 大于 80%，而 docs/ 目录下的孤立文档，Agent 主动去读的概率不到 10%。
我们仓库的 docs/ 下躺着三万多字的架构文档，写得挺好，Agent 基本当它不存在。现在的做法是在 CLAUDE.md 里放指针：「数据库迁移规范见 docs/migration.md」——一行换五十行，需要时它自己会去读。这套「入口精简 + 指针下钻」的分层，配合子目录各自的 CLAUDE.md，实测每轮上下文消耗比堆一个大文件省了差不多三成，而且首轮生成质量明显更高。
重写之后
没有做严格的 AB 测试（生产环境也没法做），但有几个可感知的变化：动手前的无效探索基本消失了；「改错地方」类的返工从每周两三次降到偶发；新同事问「这个项目的规矩是什么」，我直接把 CLAUDE.md 发给他，三分钟能读完——这是个意外收获，给 Agent 写的地图，恰好也是给人类新人的最好入职文档。反过来也成立：如果一份入口文件人类读三分钟抓不到重点，Agent 也一样。
维护上我们定了一条纪律：这份文件有行数预算，想加一条规则，先看看能不能删一条旧的。听起来苛刻，实际执行下来发现大部分「想加的规则」都是针对某次偶发 bad case 的应激反应，冷静两天就会发现不值得占预算。
另一个维护技巧是把 CLAUDE.md 的变更纳入 code review——它本来就在仓库里，PR 里改它和改代码走同一套流程。评审的问题也固定：这条规则模型自己发现不了吗？它可机械验证吗？能不能改成 lint 或 hook？三问过关才允许合入。自从走了这个流程，文件的膨胀速度基本被摁住了。
最后说一句务虚的。「好的 AGENTS.md 等于免费换模型」这个说法我原来觉得夸张，重写完之后觉得方向没错但重点偏了——它真正的价值不是「换模型」，而是这是少数几个完全在你控制之内的杠杆。模型能力、API 价格、上下文窗口都是厂商说了算，唯独这份文件，今天下午就能重写。