AGENTS.md 瘦身：全局规则与目录规则分层

AGENTS.md 的真正作用

它适合告诉代理那些“每次都重要、但不一定能从代码直接推断”的规则。因为它会重复进入任务上下文，越长越不一定越好。

好的 AGENTS.md 应减少探索；坏的 AGENTS.md 会让每个任务先读一篇项目百科。

根目录只放全局硬约束

推荐保留：

• 包管理器与关键命令
• 必须遵守的安全边界
• 代码生成物不可手改
• 全局格式/测试要求
• 仓库结构的一句话导航

示例：

# Repository rules

- Use pnpm; do not generate npm/yarn lockfiles.
- Run targeted tests first; run the full suite only before final delivery.
- Never edit generated files under src/generated.
- Frontend-specific rules are in apps/web/AGENTS.md.
- Worker-specific rules are in apps/worker/AGENTS.md.

目录规则放到最近的子目录

前端、后端、数据和部署的要求往往不同。把规则放在对应目录，可以避免每个任务都加载所有领域的细节。

例如：

/AGENTS.md
/apps/web/AGENTS.md
/apps/api/AGENTS.md
/packages/db/AGENTS.md

应当移出的内容

• 一次性需求说明：放到任务 Brief
• 长篇架构背景：放到 docs，并在需要时引用
• 复杂可复用流程：做成 Skill 或脚本
• README 重复内容：保留链接即可
• 过期命令与历史决策：删除或归档

每月体检问题

1. 这条规则是否仍然正确？
2. 是否每个任务都需要看到？
3. 能否从配置或脚本自动执行，而不是文字提醒？
4. 是否与其他文件重复？
5. 能否移动到更近的目录？
6. 是否存在互相冲突的规则？

关于“AGENTS.md 一定省 token”的误区

结构化说明可能减少代理摸索时间，也有研究在特定任务上观察到运行时间和输出 token 改善。但如果文件过长、重复或失效，它同样会增加输入并误导代理。

因此目标不是“写更多”，而是“让每条持续注入的规则都值得”。

来源

• OpenAI AGENTS.md：https://learn.chatgpt.com/docs/agent-configuration/agents-md
• On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents（2026-01-28）