AGENTS.md 是写给 Coding Agent 的项目入口。它可以说明仓库用途、构建与验证命令、代码约定和操作边界，让新的会话不必重复确认这些基础信息。
它不适合成为项目百科。Agent 开始工作前会加载这类持久指令，文件越长，越容易混入与当前任务无关、相互冲突或已经过期的规则。每条规则应只在需要它的范围出现，不必追求固定行数。
这就是渐进式披露（progressive disclosure）：根文件只提供所有任务都需要的约束和导航，目录规则、专项文档与 Skill 在相关任务中再进入上下文，必须强制执行的要求则交给 CI、hooks、权限和分支保护。
文件为什么会越来越大
膨胀通常来自一个简单的反馈循环：Agent 做了一件不符合预期的事，开发者补一条规则；另一次会话又出现新问题，于是继续补规则。几个月后，不同成员留下的修补规则开始重复或冲突，却没有人重新检查整份文件。
自动生成也可能造成同样的问题。初始化工具倾向于把「多数项目可能有用」的信息一次写全，生成结果看起来完整，却把依赖列表、目录结构和通用风格建议放进每次会话。Matt Pocock 因此主张不要用初始化脚本生成 AGENTS.md，而应逐行决定哪些内容值得常驻。
这个观点需要结合工具版本理解。当前 Claude Code 官方文档仍提供 /init，并说明它会分析仓库、生成起始文件或对已有文件提出建议。生成内容适合作为待审草稿，不应未经审阅就成为长期指令。无论入口来自 /init、模板还是人工整理，最终都要删除可从仓库推导的内容、核对冲突，并确认每一条都适用于对应作用域。
指令数量本身也是预算
AGENTS.md 中的每个 token 都会占用上下文。模型还要在系统指令、项目规则、Skill、用户要求和当前代码之间同时识别并遵守多条指令。无关规则越多，当前任务获得的注意力越少。
AIHero 文章引用 HumanLayer 的经验判断：frontier thinking LLM 大约可以较稳定地处理 150–200 条指令；较小模型和 non-thinking model 能稳定处理的数量更少。这个数字不是模型厂商公布的硬上限，也不应作为文件验收标准。HumanLayer 同时指出，相关研究仍不充分，具体表现会随模型、Agent harness、指令复杂度与上下文内容变化。
可操作的结论是：根文件应尽量短，只保留普遍适用的内容。新增一条长期规则时，不只计算它本身的长度，还要考虑 Agent 已经从系统、工具、目录规则和当前任务中接收了多少约束。
先明确 AGENTS.md 能做什么
AGENTS.md 是普通 Markdown，没有强制字段，通常随代码提交到 Git。工具加载它后，它会在基础指令与具体代码任务之间形成一层仓库配置。它也是由多种 Coding Agent 采用的开放格式，但并非所有工具都支持。它与 README.md 的受众不同：README.md 帮助人理解和使用项目，AGENTS.md 帮助 Agent 在仓库中采取符合项目约定的行动。两者可以引用同一条命令，但不必复制整份内容。
文件中的内容还可以分为两个 scope。个人 scope 包括跨项目复用的 commit 风格、工具偏好和授权习惯；项目 scope 包括仓库用途、package manager、架构决定与验证命令。Codex 会分别读取用户目录中的全局规则和仓库中的项目规则，因此团队约定不必与个人偏好混在同一个文件里。
开放格式并不保证每个工具采用相同的发现机制。截至 2026 年 8 月 13 日，Codex 官方文档说明：Codex 先读取用户目录中的全局规则，再从 project root（通常是 Git 根目录）沿当前工作目录逐层读取项目规则；同一目录中，AGENTS.override.md 的优先级高于 AGENTS.md，靠近当前工作目录的规则后加载。Codex 还允许配置其他 fallback 文件名。
其他 Agent 可能按目标文件、工作目录或自己的专属文件名解析规则。Claude Code 当前主要使用 CLAUDE.md；如果一个仓库需要让 Claude Code 与支持 AGENTS.md 的工具共享同一份内容，可以在验证两个工具的发现方式后创建符号链接，例如 ln -s AGENTS.md CLAUDE.md。也可以生成镜像文件，但要明确唯一 source of truth，避免两份规则分别演化。
团队同时使用多个工具时，应分别核对加载方式。不要只因为文件名相同，就假设作用域和优先级完全一致。
用作用域决定规则放在哪里
一条规则应放进最小但完整的适用范围。下面的判断顺序可以避免根文件持续膨胀。
根 AGENTS.md 适合保留以下内容：
一句话项目说明，帮助 Agent 判断修改目标和技术语境；
非 npm 的 package manager，以及非标准构建命令和验证门禁；
对所有任务都成立的代码、Git 与安全边界；
指向目录规则、专项文档和 Skill 的条件式入口。
AIHero 文章给出的绝对最小集合更严格：一句话项目说明；项目使用非 npm 工具时说明 package manager；构建或 typecheck 命令不标准时再写入。这里的项目说明类似 role prompt，例如：「这是一个用于可访问数据可视化的 React component library。」一句话就能让 Agent 判断当前仓库的技术目的。
JavaScript 项目如果使用 pnpm 或 Yarn，应明确写出，避免 Agent 默认运行 npm。也可以使用 Corepack，让工具根据 package.json 的 packageManager 字段选择并校验 package manager。这个建议有版本边界：Corepack 项目当前说明，它随 Node.js 14.19.0 至 25.0.0 之前的版本分发；Node.js 25 及之后需要单独安装，不能假设运行环境一定自带。
下面这些内容通常不应长期停留在根文件：
| 内容 | 更合适的位置 | 原因 |
| 某个 package 的框架和命令 | package 内的 AGENTS.md | 其他 package 不需要加载 |
| TypeScript、API 或测试的详细规范 | docs/ 下的专项文档 | 只在对应任务中读取 |
| 发布、迁移、事故处理步骤 | Runbook 或 Skill | 流程长，并且有明确触发条件 |
| 当前功能的验收条件 | Issue 或 Spec | 完成后不再是全局约束 |
| 能由 formatter 或 linter 判断的格式 | 工具配置和 CI | 自动检查比自然语言提醒可靠 |
| 临时故障与一次性绕行方案 | Issue、ADR 或故障记录 | 避免过期方案长期污染指令 |
根文件应该是入口，不是目录清单
项目结构变化快。把每个目录和关键文件的绝对位置写进根规则，短期看似节省搜索，重构后却会把 Agent 引向已经不存在的路径。开发者看到旧路径时可能凭经验产生怀疑，Agent 则可能把每次启动都加载的文字当作当前项目事实，继续沿错误位置查找。
优先记录稳定的信息：项目解决什么问题，模块之间如何分工，使用哪个 package manager，哪些命令构成完成门禁，哪些操作需要单独授权。确实需要路径时，给出有维护责任的入口，并要求 Agent 在使用前从仓库确认现状。更细的目录与调用关系可以由 Agent 在计划阶段搜索代码，生成只服务当前任务的 just-in-time 项目地图。
例如，「认证逻辑永远位于 src/auth/handlers.ts」把实现位置写成了长期事实。更稳妥的表达是：「修改认证行为前，先定位当前认证入口和测试；认证与授权是两个不同概念。」前一句可能在文件移动后失效，后一句描述的是模块能力和领域边界。
领域概念通常比文件路径稳定，例如 organization、group 与 workspace 的含义和边界。但 AI 辅助开发较快的仓库里，领域模型也可能变化，仍应保持克制并定期核对。稳定不等于永远有效。
根文件也不需要重复 Agent 已经具备的常识。「编写高质量代码」「注意性能」「保持最佳实践」无法指导具体行动。规则至少应包含触发条件、动作或验证结果，例如：「修改 TypeScript 后运行 npm run typecheck；声明完成前必须通过 npm run lint。」
代码风格也不应主要依赖自然语言。formatter 和 linter 更快、结果可重复，还能在 CI 中阻止不合规变更。Agent 只需要知道运行哪个命令、哪些错误必须修复；缩进、引号和 import 顺序应优先写进工具配置。
条件式链接才算渐进式披露
把长规则移出根文件只是第一步。Agent 还需要知道何时读取它们。单独列出一排文档链接，仍然会留下选择歧义；条件式入口会把任务类型与资料直接对应起来。
# Project
This is a TypeScript service for processing subscription billing events.
## Commands
- Use pnpm for dependencies.
- Run `pnpm typecheck` and `pnpm test` before reporting completion.
## Boundaries
- Ask before changing production data, pushing commits, or deploying.
- Never commit credentials or customer data.
## Further guidance
- When changing public APIs, read `docs/API_DESIGN.md`.
- When changing database schemas, follow `docs/DATABASE_MIGRATIONS.md`.
- Work under `packages/payments/` follows its local `AGENTS.md`.这份模板只包含起步所需的信息。API 设计规范不会干扰 CSS 调整，数据库迁移流程也不会在撰写文档时占用上下文。Agent 进入对应任务后，才沿明确的入口继续读取。
入口不必写成 ALWAYS READ 一类全大写命令，普通的条件式链接已经给出了触发条件和下一步。语言规则只在修改对应语言时加载，其他任务不必为它们消耗上下文；模型或工具变化时，也可以独立调整入口和专项规则，不必重写一份庞大的根文件。
专项资料可以继续互相引用，形成可发现的文档树。例如：
docs/
├── TYPESCRIPT.md
│ └── references TESTING.md
├── TESTING.md
│ └── references specific test runners
└── BUILD.md
└── references esbuild configuration这类嵌套让 Agent 按任务读取文档。根文件先给出条件式入口，TYPESCRIPT.md 再在涉及测试时指向 TESTING.md。外部的 Prisma、Next.js 或协议文档也可以作为下一层资料，但使用前应核对当前版本和访问状态。
专项流程如果包含多个步骤、工具调用、验收条件和副作用，可以做成 Skill。Skill 适合发布、事故排查、数据迁移等重复工作；短小且稳定的事实留在文档即可。不要为了追求形式，把两三条简单规则包装成新的 Skill。
Monorepo 用嵌套规则缩小作用域
Monorepo 的根文件只应描述仓库用途、workspace 工具、共享门禁和 package 导航。每个 package 再维护自己的技术栈、命令和局部边界。
# Repository root AGENTS.md
This monorepo contains web services and CLI tools.
Use pnpm workspaces to manage dependencies.
See each package's AGENTS.md for package-specific guidance.
# packages/api/AGENTS.md
This package is a Node.js GraphQL API using Prisma.
Follow docs/API_CONVENTIONS.md when changing public APIs.例如，前端 package 可以要求运行组件测试和浏览器验收，支付服务可以要求幂等性与审计测试，基础设施目录可以限制生产变更。把这些规则全部放在根文件中，每个任务都会加载另外两个领域的要求，也更容易出现命令冲突。对于会合并根规则与目录规则的工具，相关层级最终会共同进入上下文，因此 package 级文件同样需要克制，不能把根文件的膨胀转移到子目录。
使用嵌套规则前，要用目标 Agent 验证发现行为。以 Codex 为例，官方文档提供了从指定目录启动或使用 --cd 的验证方式。规则文件存在，不代表当前会话一定加载了它。
把建议与强制门禁分开
AGENTS.md 可以指导 Agent，不能代替确定性控制。下面这些要求如果只写成自然语言，仍然可能因为上下文、工具差异或人为操作而失效：
禁止提交 secret；
生产分支必须通过测试；
数据库变更必须经过审批；
禁止直接 force push；
生成代码必须与 schema 同步。
应把它们分别落实到 secret scanner、CI、required review、branch protection、权限系统或一致性检查中。AGENTS.md 负责告诉 Agent 有哪些门禁、怎样运行和失败后如何处理，自动化系统负责真正阻止不合规结果。
如果 Agent 反复违反同一条规则，先检查规则是否可执行、是否位于正确作用域、是否存在冲突，以及能否改成自动检查。继续追加更多措辞相近的提醒，通常只会让文件更难维护。
重构已经膨胀的规则文件
不要直接删到只剩三行。先完整读取现有文件，并按以下顺序处理：
找出相互冲突的规则。涉及产品、权限或发布边界时，由项目负责人决定保留哪一条，不能由 Agent 静默选择。
给每条规则标记作用域：全局、仓库、目录、专项流程或当前任务。
删除无法执行的空泛要求，以及已经由 formatter、linter 或 CI 完整覆盖的重复说明。
把容易变化的文件清单改为能力说明、搜索入口或由代码生成的文档。
为下沉后的文档补上触发条件，避免形成无人知道何时读取的资料目录。
在根目录和关键子目录分别启动 Agent，确认实际加载的规则和优先级。
重构后还需要 Git review。检查是否误删了安全限制、发布授权、验证命令和领域术语，也要确认新的链接与命令确实可用。AGENTS.md 是项目行为契约，缩短文件不能以丢失边界为代价。
下面这段 Prompt 覆盖完整迁移步骤，可以交给 Coding Agent 生成待审方案。它要求遇到冲突先询问，不授权 Agent 自行选择规则：
请按照渐进式披露原则重构当前 AGENTS.md，并完成以下工作：
1. 查找矛盾：列出相互冲突的指令。每组冲突都先询问我保留哪个版本，不要自行决定。
2. 提取根文件必需项：只保留一句话项目说明、非 npm 的 package manager、非标准 build/typecheck 命令，以及确实适用于每一项任务的规则。
3. 分组其余规则：按 TypeScript、测试、API 设计、Git workflow 等类别整理，每组写入独立 Markdown 文件。
4. 设计文件结构：给出精简后的根 AGENTS.md、每个专项文件，以及建议的 docs/ 目录树。
5. 标记删除项：列出重复、无法执行、过于明显，或 Agent 可以从代码和工具配置直接推导的内容。
修改文件前先展示方案和待确认的冲突。这段 Prompt 适合重构，不代表生成的结果可以跳过 review。文档移动后仍要验证链接、命令、目录级作用域和安全边界。
每次新增规则前检查四件事
新增规则前，可以用四个问题做最后判断：
它是否适用于这个范围内的每一项任务？
它是否描述了明确的触发条件、动作或完成证据？
它会不会与现有规则、工具配置或更高优先级指令冲突？
它能否由测试、lint、CI、权限或代码生成来可靠执行？
答案决定规则的落点。根 AGENTS.md 只保留真正长期、通用且可执行的内容，其余信息在相关目录和工作流中按需出现。
| 规则适用范围 | 存放位置 |
| 仓库内每项任务都需要 | 根 AGENTS.md |
| 单一语言、领域或工作类型需要 | 独立文档，并从根文件写明触发条件 |
| 某个 package 或目录需要 | 嵌套 AGENTS.md，或目标工具支持的目录级规则 |
| 多步骤且重复执行 | Skill 或 Runbook |
| 仅当前功能需要 | Issue、Spec 或当前会话 |
| 必须强制执行 | CI、hooks、权限或分支保护 |
