编辑代理说明¶
在修改
AGENTS.md或其链接的任何指南之前，请阅读本文。
Token（代币）预算思维¶
AGENTS.md 会在每次代理请求时加载；领域指南会在进入相关区域时加载。请将 AGENTS.md 保持在 200 行以内，每份领域指南保持在 300 行以内。当文件超出预算时，请进行拆分或删减——不要为了压缩内容而牺牲文笔。
何时「不」应添加内容¶
在编写新规则之前，请询问自己它是否真的必要
- 代理已经能处理了。 先用提示词测试。如果代理在没有该规则的情况下表现正确，则不要添加。
- 一次性事件。 优先考虑在代码层面修复（如 Lint 规则、CI 检查、测试断言），而不是添加新的文档规则。
- 硬编码路径。 文件路径会变动；请使用“搜索 X”之类的模式代替。
- 上游文档。 不要复述 pytest、ruff 或其他工具的文档——直接链接到它们。
- 与现有规则矛盾。 添加前请搜索所有已链接的指南。如果两条规则冲突，请将其合并为一条。
- 其他地方已有涵盖。 在
AGENTS.md和所有已链接的指南中搜索重复的指导内容。
如果上述任何情况适用，请勿添加该内容。
内容应存放的位置¶
目标是保持 AGENTS.md 精简，并拥有丰富的领域指南，向代理传授它们无法仅从代码中习得的知识。
| 范围 | 文件 |
|---|---|
| 项目全局不变性（贡献准则、环境配置、测试/Lint 命令、提交规范） | AGENTS.md |
| 特定领域知识（模型模式、格式细节、弃用时间表） | 领域指南 |
经验法则
- 如果某事只对一个领域重要，请将其放入领域指南。
- 如果某事对所有领域都重要，考虑放入
AGENTS.md——但首先要确认代理是否已经能够处理它。 - 当你拥有 5 条或更多非显而易见的、且共享明确范畴的指令时，请创建一个新的领域指南。
什么样的领域指南是优秀的¶
添加代理无法从代码或公开文档中推断出的内容：与标准模式不同的项目特定约定、需要跨文件上下文的正确处理方法，以及针对重复错误的修复措施。每项条目都应简短、具体且可执行——例如：应触及哪些文件、更改的先后顺序以及要运行哪些测试。
保持文档精简¶
- 每次添加内容都应触发对周边内容的审查，以清理陈旧或冗余的项目。
- 多用示例，少用解释——一个 3 行的代码片段胜过一段说明文字。
- 将相关的要点合并为一个原则，而不是列出各种变体。
- 使用
search for X（搜索 X）代替硬编码的文件路径。 - 领域指南中可以使用 PR 引用以方便追溯，但在
AGENTS.md中应避免使用。
反模式¶
| 模式 (Pattern) | 问题 |
|---|---|
| 被动式积累 | 每发生一次事件就增加一条规则而不清理，会导致臃肿 |
| 指南间复制粘贴 | 重复内容会逐渐产生偏差；应保持在一处，并在他处进行链接 |
| 指令墙 | 长篇的“禁止清单”代理会直接掠过；应整合为原则 |
| 配置快照 | 展示获取该值的命令，而不是直接展示该值本身 |
变更检查清单¶
在提交任何代理指令文件的更改之前
- [ ] 非显而易见？ 如果没有这条规则，代理会做错事吗？
- [ ] 无冲突？ 是否搜索了所有已链接的指南以确保无矛盾？
- [ ] 文件位置正确？ 全局性内容放入
AGENTS.md，特定领域内容放入领域指南？ - [ ] 是否抵消了新增量？ 是否通过删除或整合其他内容进行了补偿？
- [ ] 在预算范围内？
AGENTS.md< 200 行，领域指南 < 300 行？ - [ ] 无硬编码路径？ 在路径可能变动的地方使用了“搜索 X”？
- [ ] 经过测试？ 是否验证了代理确实会遵循新指令？