日本語/中文/English

Study Notes / 2026 ・ No.05

AGENTS.md 札记

交给 AI 的“这个仓库的规矩”

发布

本期要回答的问题

Q1AGENTS.md 到底是什么 Q2在什么场景下应该用它 Q3该怎么写（附实例） Q4AI 变得更聪明之后，还需要它吗

先说 Q4 的结论：“要写的会变少，但不会消失”

Codex、Claude Code、Copilot、Cursor……开始用编码智能体之后，
仓库里就会出现一个叫 AGENTS.md 的文件。
它是做什么用的、怎么写才有效，本期一次讲清。

一

AGENTS.md 是什么 ── Q1 的答案

CORE

AGENTS.md 是写给编码智能体看的 README。它就是放在仓库最上层的一个普通 Markdown 文件，没有固定格式，也没有必填项。智能体开始工作时会先读它，从中了解怎么构建、怎么跑测试、要遵守哪些规矩。

这个格式由 OpenAI 在 2025 年 8 月发布，是和 Amp、Google 的 Jules、Cursor、Factory 等一起整理出来的。同年 12 月，它与第 1 期提到的 MCP 等项目一起，被捐赠给了 Linux 基金会旗下新成立的 Agentic AI Foundation（AAIF），成为不属于任何一家公司的通用格式。据官网介绍，使用它的开源项目超过 6 万个，能读取它的智能体和 IDE 超过 30 种。

工具自己的配置文件对 AGENTS.md 的处理
OpenAI CodexAGENTS.md原生格式。把主目录的 ~/.codex/AGENTS.md 和从仓库根目录到当前工作目录路径上的 AGENTS.md 拼接起来读取（合计默认上限 32KiB）
Claude CodeCLAUDE.md没有 CLAUDE.md 时改读 AGENTS.md（v2.1.277 起）。也可以在 CLAUDE.md 里写 @AGENTS.md 导入
GitHub Copilot
（coding agent）		.github/copilot-instructions.md2025 年 8 月起支持 AGENTS.md
Cursor・Jules・Devin・Zed・Aider 等列在官网的支持列表中

和 README 的区别在于读者。README 是给人看的，写项目是什么、怎么用；AGENTS.md 是给智能体干活用的，写用哪条命令验证、哪些事不能做。官方的说法是：这样可以把给智能体的细碎指示单独放一处，不把给人看的说明弄乱。

二

为什么需要它

WHY

智能体每次都是“第一天上班的新人”。正如第 1 期所写，模型一次只能看到上下文里的内容。换一个会话，你上次口头叮嘱的事就全没了。

  • 有些事推测不出来 ── “这个 HTML 是生成的，不要直接改”“发布要等人确认”这类事，读多少代码也看不出来
  • 推测要花钱花时间 ── 为了找到跑测试的方法，打开一个个文件，试了又失败。写下来只要一行
  • 不同的人说法不同 ── 让团队里谁用哪个智能体都按同一套规矩干活，把口头叮嘱搬进文件

把它看成交给新同事的入职资料，就好理解了。不同之处在于，对方每次都一定会通读全文，而且相当听话地照做。正因为如此，才必须写得短而准确。

三

什么场景下用 ── Q2 的答案

WHEN

值得放的是要让智能体反复干活的仓库，尤其是存在“读代码也看不出来的规矩”的仓库。一次性的小活，写在请求里就够了。

场景是否适合理由
构建或测试步骤特殊◎自有脚本、经由 Docker、需要环境变量等。让它自己找，会耗时间和 token
有不能碰的地方◎生成文件、外部代码、生产配置。一旦被改坏，损失很大
业务系统开发◎独特的命名规范、改动需审批的表。业务规则没写在代码里
团队同时使用多种智能体◎一个文件就能把同一套规矩告诉所有工具
monorepo○前端和 API 风格不同时，可以按文件夹分别放 AGENTS.md
结构常规的小应用△常规结构，智能体自己就能看懂
用完即弃的脚本×写它的工夫反而更大

判断标准很简单：“同一句提醒，是否已经对智能体说过两次”。说过两次的，第三次多半还得说。这时往 AGENTS.md 里加一行，是最不浪费的养法。

四

怎么写 ── Q3 的答案

HOW

原则有三条：短、具体，而且只写从代码里读不出来的东西。写什么，用“智能体自己能不能查到”和“出错时损失大不大”两条来判断，就不会纠结。

写，还是不写

用机制拦住 CI・钩子・分支保护 写了也无法强制 必须写 禁止事项及替代做法 生成文件・生产环境・审批 不写 项目概要 语言・结构・泛泛之谈 简短写 命令・命名习惯 省去查找的工夫 损失大 损失小 智能体自己能查到 读代码也看不出来

右上一定要写。左上不止要写，还要用机制拦住

  • 命令写成能直接执行的样子 ── 不写“跑一下测试”，而写 npm test -- --run。智能体会真的去执行写下的命令
  • 附上一句理由 ── 比如“这是生成文件，不要直接改（去改源头的 build.py）”。有了理由，它在没写到的类似情况下也能正确变通
  • 禁止事项要配上替代做法 ── 只写“不要……”，智能体会去找别的旁门左道
  • 不要写长 ── Claude Code 官方文档建议 CLAUDE.md 以 200 行以内为宜；Codex 默认把读取总量限制在 32KiB。越长越不容易被遵守，每次的成本也越高
  • 不写机密 ── 密码和 API 密钥不要放进仓库，这个文件是所有人共享的
  • 必须遵守的事，用机制保证 ── AGENTS.md 只是“上下文”，没有强制力。不许直接推到 main 就用分支保护，不许破坏格式就用 CI 或钩子（如 Claude Code 的 hooks）拦住

按文件夹放置时，离得近的优先

repo/ ├─ AGENTS.md ├─ web/ │ ├─ AGENTS.md │ └─ src/ └─ api/ └─ … ← 在这里工作 在 web/src/ 工作时 1 repo/AGENTS.md 全局约定 2 web/AGENTS.md 仅限 web 的约定 3 你的请求 优先级最高 越往下越优先（离得近的胜出）

Codex 从根目录向工作目录依次拼接读取，越靠后（越近）的起覆盖作用

在 monorepo（多个项目放在同一个仓库）里，子文件夹也可以放 AGENTS.md。官网的说明是“离得最近的文件优先”，以及“请求本身优先于一切”。据说 OpenAI 自己的仓库里有 88 个 AGENTS.md。

和 Claude Code 一起用时，没有 CLAUDE.md 就会直接读 AGENTS.md。如果两个都想放，官方做法是在 CLAUDE.md 开头写一行 @AGENTS.md 导入，下面再补充只给 Claude Code 的指示。也可以用符号链接（ln -s AGENTS.md CLAUDE.md），但如果有人在 Windows 上 clone，用导入更稳妥。

# CLAUDE.md @AGENTS.md # 以下只写给 Claude Code - 大改动之前，先用列表列出计划再动手
五

实例：本站的 AGENTS.md

举个例子：如果给本站（kiji-site）放一个 AGENTS.md，会是下面这样。这是一个用一个 Python 文件生成三种语言页面、通过 Cloudflare Pages 发布的小仓库。在和 AI 一起做这个博客的过程中，我只留下了每次都要解释的事和差点犯过的错。

# AGENTS.md — kiji-site 骐霁科技（KIJI Info-Tech）的公司网站，日文・中文・英文三种语言。 ## 结构 - 所有页面由 build.py 生成。根目录的 *.html 是生成文件，不要直接修改 （要改就改 build.py 里对应的地方，再重新构建） - 图片放在 blog-img/<文章 slug>/，分 1600 和 960 宽的 webp 与 jpg ## 命令 - 构建：python3 build.py - 生成发布文件：./build.sh（输出到 dist/） - 检查显示：python3 -m http.server 8765 打开，宽 1280px 和 390px 都要看 ## 新增文章时 - 在 POSTS・FILE（三种语言）・POST_CATEGORY 各加一行 （漏了 POST_CATEGORY，构建会中止） - 列表卡片按从新到旧排列，加在最前面 - 图的 SVG 在构建后用 getBBox 检查 （文字溢出・重叠。英文版最容易出问题） ## 必须遵守 - 照片只用允许再利用的（CC BY・BY-SA・CC0 等）， 在图注里写明作者和许可协议 - 价格・时刻・版本号要用一手资料核实，并注明“截至 2026 年 9 月”这样的时间点 - 不要 git push。发布由人确认后进行 - 提交信息用日文，要点分条列出
写了什么为什么写
*.html 是生成文件一让它改样式，它就容易直接改 HTML，下次构建就没了
命令和检查宽度不让它去找，连看哪个屏宽都定好
新增文章的步骤让它把三处改动当成一组记住，漏一处构建就停
图的检查英文版标签溢出的事故真实发生过两次
照片的许可不让它从网上随便找图
不要 push发布前要过人眼。无法撤回的操作由人来做

反过来，没写什么同样重要。“用 Python 写的”“blog.html 是文章列表”这类项目介绍一概没放。打开文件就能看懂的，智能体会自己去读。这个 30 行左右的文件，大小也和下一章的研究结论相吻合。

六

真的有效吗 ── 研究结果

DATA

相关研究还很少，结论也不一致。但指向是一致的：“由人写的、简短的、只写代码里看不出来的东西的 AGENTS.md”有望奏效，其他的要么没用，要么反而碍事。

研究研究对象结果
Lulla 等
（2026 年 1 月）		10 个仓库・124 个拉取请求有 AGENTS.md 时，运行时间中位数缩短 28.64%，输出 token 减少 16.58%，完成率相当
Gloaguen 等
苏黎世联邦理工学院
（2026 年 2 月）		AGENTbench 138 例・SWE-bench Lite 300 例。Claude Code・Codex・Qwen CodeLLM 自动生成的文件使成功率下降 0.5–2 个百分点，人写的文件平均提高约 4 个百分点。两者都使推理成本增加 20% 以上。仓库概要说明没有帮助
Khatri
（2026 年 7 月）		Claude Code 与 Codex CLI，17 个任务・288 次运行对正确性没有显著影响。失败原因不在“不知道”，而在设计与实现的功力

苏黎世联邦理工学院的论文这样解释无效的原因：智能体会忠实执行写下的指示，增加测试和探索，结果让任务本身变得更难。并不是写得越多越好。

由此可以得出：不要把 /init 等自动生成的文件原样放进仓库。生成之后，由人读一遍，把看代码就知道的行删掉再放。这是目前最稳妥的用法。

第三篇是个人研究者尚未经过同行评审的论文。所有数字都只在各自的实验条件下成立。

七

变聪明之后还需要吗 ── Q4 的答案

VIEW

我的答案是：“要写的会变少，但不会消失”。把 AGENTS.md 里常写的内容分成三类，就能清楚地看出，哪些会因为变聪明而不再需要，哪些是聪明也补不上的。

模型变聪明之后，还剩下什么

现在 变聪明之后 读代码就懂 查一查就知道 没写下来的意图 不再需要 没写下来的意图 这部分留下

宽度表示分量的大致感觉。没写下来的意图，不会因为模型更聪明而变小

  • 读代码就懂的（项目概要、用的语言、目录结构）── 现在就已经不需要了，研究也表明它没有帮助
  • 查一查就知道的（构建和测试命令、本地运行方法）── 模型越聪明、越快、越便宜，自己去找的成本就越不值一提。写它的意义将只剩“省时省钱”
  • 哪里都没写下来的意图（为什么这样做、什么不能做、由谁拍板）── 读多少代码和历史记录都找不到。这不是聪明与否的问题，而是信息根本不在那里

换成人来想就明白了。再优秀的工程师，跳槽第一天也不会知道“周五不碰生产数据库”“这张表的改动要财务审批”。越是优秀的人，越会先来问清这些规矩。

会变的是形式。让智能体把自己发现的事记下来的机制（如 Claude Code 的自动记忆）、只在需要时才加载的操作手册（技能）、有强制力的机制（钩子和 CI）都已经出现，不必再把一切都写进一个 AGENTS.md。即便如此，由人决定、由人写下、人和 AI 读的是同一份的那个地方，应该会一直存在。理由和 README 不会消失是一样的。

本章是笔者基于以上事实的判断。

结 — 一页总结

  1. AGENTS.md 是写给智能体的 README。普通 Markdown，Codex・Copilot・Cursor 等 30 多种工具会读，Claude Code 在没有 CLAUDE.md 时也会读。
  2. 适用于要让智能体反复干活、存在读代码也看不出来的规矩的仓库。同一句提醒说过两次就补进去。
  3. 要写的是命令、禁止事项及替代做法，以及理由。简短，由人来写。不写概要和泛泛之谈。
  4. 必须遵守的事，用分支保护・CI・钩子拦住。AGENTS.md 没有强制力。
  5. AI 越聪明，要写的越少。但作为传达代码里没写的意图的地方，它会留下来。

参考

AGENTS.md 札记 — 全七章 / 2026.09

← 返回文章列表