正文
AGENTS.md 正在变成 AI 编程代理时代的新型仓库规则文件。它的定位很清楚：像 README 是写给人看的，AGENTS.md 则是写给 AI coding agent 看的，用来说明项目结构、安装命令、测试方式、代码风格、安全注意事项等信息。AGENTS.md 官方介绍也把它称为一种“简单、开放的格式”，用于给编码代理提供上下文和指令，并且可以被多个 AI 编程工具采用。
但问题也来了：AGENTS.md 真的越详细越好吗？
不一定。很多团队刚开始写 AGENTS.md 时，容易把它写成“AI 版团队手册”：项目背景、技术栈历史、所有命令、所有风格偏好、所有禁止事项、所有业务规则、所有安全要求，甚至还加上大量“你必须”“你永远不能”“你每次都要”。结果文件越来越长，AI 看似获得了更多上下文，实际却更容易跑偏。
这篇博客要讨论的不是“AGENTS.md 有没有用”，而是一个更实用的问题：AGENTS.md 到底该写多短，才不会帮倒忙？
AGENTS.md 是规则文件，不是知识库
AGENTS.md 最适合承载的是“代理开始改代码前必须知道的少量规则”。官方示例也很克制，常见内容主要包括 setup commands、code style、testing instructions、security considerations 等。
它不应该变成这些东西：
这些内容不是不能给 AI，而是不适合全部塞进 AGENTS.md。原因很简单：AGENTS.md 往往会在任务开始时被自动读入上下文。OpenAI Codex 文档说明，Codex 会在开始工作前读取 AGENTS.md，并按全局、项目、子目录的顺序合并指令；更靠近当前目录的文件会覆盖更早的指导。
也就是说，AGENTS.md 是“默认注入”的规则，不是“按需查询”的资料库。默认注入的内容越多，代理每次任务都要背负越多噪音。
- 项目完整历史。
- 架构决策全集。
- API 文档副本。
- 业务需求文档。
- 团队 onboarding 手册。
- 所有 lint 规则的自然语言复述。
- 所有测试用例和异常情况说明。
为什么 AGENTS.md 可能帮倒忙
AGENTS.md 有用，但它不是越长越有用。规则太多、过期、冲突，都会让代理做出看似遵守规则、实际破坏项目的修改。
规则太多，重点会被稀释
AI 编程代理不是不读规则，而是会在有限上下文里综合任务、代码、错误、测试输出和规则文件。AGENTS.md 写得越长，真正重要的规则越容易被普通偏好淹没。
比如下面这类规则经常出现在超长文件里：
这些话没有错，但太泛了。它们不会显著提升代理表现，因为任何成熟编程代理本来就会尽量这么做。真正有价值的是项目特有、代理无法从代码中稳定推断的规则，例如：
AGENTS.md 要写“非显而易见的规则”，而不是写“好代码宣言”。VS Code 的 Copilot 自定义指令文档也建议保持指令简短、自包含，聚焦非显而易见的规则，跳过 linters 或 formatters 已经能强制执行的约定。
- 使用清晰的变量名。
- 编写高质量代码。
- 避免重复逻辑。
- 保持代码简洁。
- 注意性能。
- 注意安全。- 修改支付逻辑后必须运行 `pnpm test:payments`。
- `packages/legacy-admin` 仍使用 Vue 2，不要引入 Vue 3 API。
- 数据库迁移文件只能新增，不能修改已发布 migration。过期规则会让代理做错正确的事
AGENTS.md 一旦进入仓库，大家往往很少维护。半年后，技术栈升级了，测试命令变了，目录结构拆了，旧规则却还在。
例如：
但项目已经迁移成：
这时 AI 代理很可能为了遵守 AGENTS.md，把代码放进错误目录。对人类开发者来说，过期文档可以靠经验绕过；对代理来说，规则文件往往具有更高权重。它会“认真地做错”。
所以，AGENTS.md 越长，维护成本越高；维护成本越高，过期概率越大；过期规则越多，帮倒忙的概率也越大。
- 所有新组件必须写在 `src/components`。apps/web/app/components
packages/ui/src相互冲突的规则会制造不确定性
很多仓库会同时存在多个规则文件，例如 AGENTS.md、.github/copilot-instructions.md、CLAUDE.md、GEMINI.md、Cursor rules 等。GitHub Copilot coding agent 已经支持仓库根目录和子目录中的 AGENTS.md，同时也继续支持 GitHub 自己的 Copilot instructions、CLAUDE.md、GEMINI.md 等格式。
这带来一个现实问题：同一条规则可能在不同文件里写了不同版本。
例如：
代理到底该听谁？不同工具有不同优先级和合并方式。VS Code 文档说明，个人指令、仓库指令、组织指令之间存在优先级；OpenAI Codex 文档也说明，项目中更靠近当前工作目录的 AGENTS.md 会覆盖更早的指导。
因此，规则文件越多、越长、越重复，冲突风险就越高。
# AGENTS.md
- 使用 pnpm。# .github/copilot-instructions.md
- 使用 npm。# packages/admin/AGENTS.md
- 使用 yarn。研究结果并不总是支持“多写点更好”
围绕 AGENTS.md 的效果，已经出现了一些研究。一个 2026 年的论文摘要显示，在多个编码代理和模型的实验中，仓库上下文文件往往会降低任务成功率，同时让推理成本增加超过 20%；作者的结论是，不必要的要求会让任务变难，人类编写的上下文文件应只描述最小必要要求。
不过，研究结论并非完全单向。另一项关于 AGENTS.md 对代理效率影响的研究分析了 10 个仓库和 124 个 pull request，结果显示 AGENTS.md 的存在与更低的中位运行时间和更少的输出 token 相关，同时任务完成行为相近。
这说明一个更合理的判断是：AGENTS.md 有用，但有用的不是“长文件”，而是“少量准确规则”。
仓库规则文件到底该写多短
我的建议是：
这不是硬性标准，而是一个实战阈值。判断 AGENTS.md 是否太长，可以看这些信号：
更简单的标准是：AGENTS.md 应该短到代理每次读它都值得，短到人类 reviewer 愿意认真审它。
如果团队没有人愿意在 PR 里 review 这份规则文件，那它就已经太长了。
| 读完超过 3 分钟 | 文件已经像文档，不像规则 |
| 大量规则带有“通常”“尽量”“最好” | 规则不够明确 |
| 不同目录规则互相打架 | 根文件管得太细 |
| 写了 lint 已覆盖的内容 | 重复约束 |
| 写了很多业务知识 | 文件变成知识库 |
**根目录 AGENTS.md 控制在 40-80 行以内；复杂 monorepo 可以放宽到 120 行，但超过 150 行就应该拆分。**
AGENTS.md 最该写什么
一份好的 AGENTS.md 只回答少数几个问题：这个仓库怎么启动，改完代码必须跑什么检查，有哪些项目特有的坑，哪些目录有特殊规则，什么事情必须先问人。
这个仓库怎么启动
命令要准确，不要写三套“可能可用”的命令。AI 代理最怕模糊指令。
## Setup
- Install dependencies with `pnpm install`.
- Start the web app with `pnpm dev`.
- Run the full test suite with `pnpm test`.改完代码必须跑什么检查
这类规则很有价值，因为代理无法总是从代码结构判断团队的验证习惯。
## Checks
- After changing TypeScript files, run `pnpm typecheck`.
- After changing UI components, run `pnpm test:ui`.
- Before finishing, run `pnpm lint` if the change touches application code.有哪些项目特有的坑
这比“写高质量代码”重要得多，因为它直接避免破坏仓库。
## Project rules
- Do not edit generated files under `src/generated`.
- Do not modify existing database migrations; create a new migration instead.
- Do not add new runtime dependencies without asking first.哪些目录有特殊规则
根目录 AGENTS.md 不要塞满所有子项目规则。更好的做法是分层。
AGENTS.md 官方 FAQ 说明，如果指令冲突，离被编辑文件最近的 AGENTS.md 会胜出；GitHub Copilot coding agent 也支持根目录和嵌套 AGENTS.md。
这对 monorepo 特别重要。根文件只写全局规则，子目录文件写局部规则。
AGENTS.md
apps/web/AGENTS.md
packages/ui/AGENTS.md
packages/legacy/AGENTS.md什么事情必须先问人
这类规则能减少“代理过度主动”。AI 代理最大的风险之一不是不会做，而是做得太多。
## Ask first
- Ask before changing public API contracts.
- Ask before deleting files.
- Ask before adding paid services, tracking code, or new dependencies.AGENTS.md 不该写什么
AGENTS.md 应该是护栏，不是愿望清单。下面这些内容最容易让文件膨胀，也最容易过期。
不写空泛价值观
少写：
多写：
- Always write clean, maintainable, scalable code.- Keep functions under 80 lines unless there is a clear reason.
- Prefer existing utilities in `src/lib/date.ts` over adding new date helpers.不复述自动化工具能检查的规则
如果 Prettier 已经管格式，就不要写：
除非项目没有自动化工具，或者这个规则无法被工具稳定检查。
- Use 2 spaces.
- Use single quotes.
- No trailing commas.不写大型架构文档
少写：
多写：
历史背景可以放到 docs/architecture.md，AGENTS.md 只链接它：
## System architecture
本系统从 2019 年开始建设，最初采用……## Architecture constraints
- Business logic belongs in `src/domain`, not in route handlers.
- API handlers should call services from `src/services`.- For architecture details, see `docs/architecture.md`.不写互相重复的规则文件
如果你已经有：
请尽量不要复制粘贴五份。可以选一个主文件，其他文件只做极简转发或工具特定补充。否则规则漂移是迟早的事。
AGENTS.md
.github/copilot-instructions.md
CLAUDE.md
GEMINI.md
.cursor/rules一份足够短的 AGENTS.md 模板
下面是一份可直接改造的短模板：
这份模板不长，但已经覆盖了代理最需要知道的内容：安装、测试、禁止事项、安全边界、目录提示。
真正好用的 AGENTS.md 通常不是“百科全书”，而是“护栏”。
# AGENTS.md
## Purpose
This file gives AI coding agents the minimum rules needed to work safely in this repository.
## Setup
- Use `pnpm install` to install dependencies.
- Use `pnpm dev` to start the local app.
- Use `pnpm test` to run tests.
## Required checks
- Run `pnpm typecheck` after changing TypeScript files.
- Run `pnpm lint` before finishing application code changes.
- Run package-specific tests when editing files inside `packages/*`.
## Code rules
- Do not edit generated files under `src/generated`.
- Do not modify existing database migrations; create a new migration.
- Reuse existing utilities before adding new helpers.
- Do not add runtime dependencies without asking first.
## Safety
- Ask before changing public API contracts.
- Ask before deleting files or moving large directories.
- Do not commit secrets, tokens, credentials, or `.env` files.
## Directory-specific notes
- `apps/web` contains the main web app.
- `packages/ui` contains shared UI components.
- Check for nested `AGENTS.md` files before editing subdirectories.判断一条规则该不该进 AGENTS.md
写入前先问这些问题：
这些问题能帮团队把 AGENTS.md 从“愿望清单”压缩成“必要规则”。
- 这条规则是否会影响代码修改结果？如果不会，删掉。
- 代理能否从现有代码、lint、测试中推断出来？如果能，通常不用写。
- 这条规则是否长期稳定？如果经常变，别写进根文件。
- 这条规则是否只适用于某个目录？如果是，放到子目录 AGENTS.md。
- 违反这条规则会不会造成明显损失？如果会，写；如果只是个人偏好，慎写。
推荐的维护方式：把 AGENTS.md 当代码审
AGENTS.md 不是一次性文件。它会影响代理行为，所以也应该进入 code review。
建议团队建立三条维护规则：
尤其在这些场景之后，一定要回看 AGENTS.md：
AGENTS.md 最危险的状态不是“没有”，而是“看起来权威但已经过期”。
- 包管理器从 npm 改成 pnpm。
- 测试框架从 Jest 改成 Vitest。
- 项目从单仓库变成 monorepo。
- 新增 generated code。
- 数据库 migration 规范改变。
- CI 命令改变。
- 旧模块进入维护模式。
- 修改 AGENTS.md 必须经过 review。
- 删除已过期规则优先于新增规则。
- 每次重大目录调整后检查 AGENTS.md 是否仍准确。FAQ：AGENTS.md 仓库规则文件常见问题
结论：AGENTS.md 要短，不是因为 AI 读不懂，而是因为规则越少越可靠
《AGENTS.md 可能帮倒忙：仓库规则文件到底该写多短》这个问题的答案可以总结成一句话：
AGENTS.md 应该短到只剩“代理不该猜、也不能猜错”的规则。
不要把它写成知识库，不要把它写成团队文化墙，不要把它写成所有工具配置的自然语言副本。它最适合写三类内容：怎么装、怎么测、哪些事不能乱动。
一份好的 AGENTS.md，不是让 AI 看起来更“懂事”，而是让它少犯代价高的错误。规则越短，越容易维护；越容易维护，越不容易过期；越不容易过期，越能真正帮到项目。