AGENTS.md 优化指南：让规则更短、更主动、更可验证

概览

AGENTS.md 不是项目手册，也不是把所有经验都写进去的操作清单。它是一组持续生效的决策边界：告诉智能体什么时候读取上下文、哪些工作可以直接完成、哪些动作需要明确批准，以及怎样判断任务已经完成。

随着模型能力提升，过度详细的规则会产生反效果。它们会增加上下文成本，扩大触发范围，制造重复检查，并让模型在本来可以继续的地方停下来询问。更好的方向不是不断追加规则，而是保留真正改变行为的约束，把它们压缩成短句，并让每条规则只负责一个判断。

本文结合 OpenAI 关于 GPT-6 Astra 的 AGENTS.md 建议、Anthropic 关于 Claude Fable 5.1 的提示工程建议，以及一次真实的双语规则审查和封版过程，整理一套适用于代码智能体的优化方法。

两篇官方资料给出的共同方向

OpenAI 在 2026 年 9 月发布的文章指出，技能、AGENTS.md 和任务提示词都会影响智能体的工作方式。技能描述应尽可能短，复杂工作应采用渐进披露；AGENTS.md 应让模型读取任务需要的内容，而不是在每次编辑前强制阅读一整套文档。文章还特别提醒，随着模型变强，过去为了防止模型越界而加入的强硬提示，可能变成新的阻塞点。模型需要清楚的完成边界和适度的继续执行许可。

Anthropic 对 Fable 5.1 的建议更偏向具体行为调优。它观察到模型在低推理强度下可能较少调用搜索，在小范围修改中可能重写整个文件，在 xhigh 或 max 处理长交付物时可能先在思考中起草全文，再在回答中重新写一遍。因此建议按需提高推理强度、优先局部编辑，并在确实遇到长交付物重复起草时使用任务级提示。

两篇资料可以抽象成四条通用原则：

1. 规则只在相关任务中触发。
2. 规则说明结果和边界，少规定模型必须经过的每一步。
3. 已有授权应当复用，只有实质缺口才需要再次询问。
4. 规则是否有效要看实际行为和成本，不能只看文字是否完整。

但模型特有的观察不能直接升级成全局规则。Claude 的长交付物重复起草现象，适合在 Claude 专项提示或具体长任务中处理；目前没有足够证据证明同一句话对 GPT 具有相同收益。对 GPT 统一加入这类规则，可能增加提示长度，却没有可验证的改进。

AGENTS.md 应该解决什么问题

一份有效的 AGENTS.md 至少要回答五个问题：

• 当前工作属于简单、复杂还是高风险任务？
• 用户的明确请求已经授权哪些必要动作？
• 什么情况必须暂停并报告，什么情况可以继续处理？
• 需要读取哪些上下文，哪些内容可以复用？
• 用什么证据判断修改正确且任务完成？

它不需要描述每个工具的完整用法，也不需要为每种失败预先写一套脚本。工具文档、模型说明和复杂工作流应放在按需加载的专项文件中。根层规则只保留路由、边界和不可遗漏的安全约束。

推荐的最小骨架

一个适合长期维护的结构可以按工作决策顺序组织：

1. 语言与跨版本不变量。
2. 任务分类与高风险批准项。
3. 执行流程和授权复用。
4. 安全、运行环境和敏感信息。
5. 上下文检索与 Token 效率。
6. 工作区、恢复和持久状态。
7. 委派与模型路由。
8. 验证、质量审查和完成报告。
9. 项目级改进和子代理边界。

顺序的目的不是让模型背诵流程，而是让相关规则在做决定时靠近。结构调整本身不会自动减少 Token，也不值得为了形式重写整份文件。只要现有条款已经覆盖这些决策，就应优先删除重复句，而不是再复制一套“最小骨架”。

执行流程可以压缩为以下几句：

- Inspect relevant context; plan complex work and preserve recovery where needed.
- Perform the narrowest authorized work; apply the relevant verification and quality review.
- Complete the authorized objective, including fixes caused by the change.
- Ask only when an unresolved material gap affects correctness, scope, safety, or reversibility.
- Pause blocked actions; continue independent authorized work.
- Report the result, checks performed, and remaining blockers accurately.

这段应替换重复的简单任务流程、复杂任务流程、完成要求和验证顺序，而不是与原条款并存。高风险操作清单仍应单独保留，因为它定义的是批准门槛，不是普通工作流的重复说明。

自主性与授权：减少打断，但不扩大范围

自主性最容易被两类相反的规则破坏。一类把所有不确定性都升级为复杂任务，另一类要求每个动作都先确认。两者都会让常规工作变慢。

更精确的写法是：明确的 change、build、fix 或 create 请求，授权完成目标所需的本地编辑和相称验证；已授权范围内的批准可以复用；只有当范围、正确性、安全性或可逆性存在无法通过上下文和合理默认值解决的实质缺口时，才询问用户；如果一部分被阻塞，只暂停该部分，继续独立且已授权的工作。

这几条不会删除高风险批准要求。强制推送、生产推送、发布标签、共享分支删除、批量删除、权限变更、外部写入、生产部署、延迟执行和敏感目录操作，仍然应当保留明确授权门槛。优化的目标是缩小普通工作的确认范围，而不是把高风险动作变成默认动作。

安全规则也应区分“使用秘密”和“披露秘密”。例如：

Use secrets only within authorized scope; redact outputs unless disclosure of specific secrets to a specified destination is explicitly authorized.

这允许授权任务使用必要凭据，同时默认不把凭据原文写入日志、回答或提交。只有对特定秘密、特定目标的明确披露授权，才改变输出脱敏要求。实际执行仍受更高层级的平台和系统限制约束。

上下文规则：按需读取，复用已有证据

上下文策略应当直接服务于 Token 效率和正确性：

• 渐进读取与任务相关的上下文。
• 复用仍适用的上下文，避免重复读取未变化的大文件。
• diff 足够时用 diff 获取变更上下文。
• 只补读缺失部分，并使用互不重叠的范围。
• 只有在任务需要精确结构或格式时，才完整读取小文件。
• 处理行情、新闻、模型能力、软件版本等时效性事实时，使用当前来源并记录来源和日期。

“读取相关上下文”不等于“每次都读取整个仓库”。好的规则应指出文档的适用条件，例如“架构文档用于服务边界变更，部署文档用于部署准备”，而不是要求每次编辑都读取所有文档。

如果使用 LeanCTX 或其他压缩工具，还要明确区分“压缩成功”和“命令执行成功”。压缩只说明输出被归档或缩短，不能代替实际结果、退出状态和文件状态。缺失证据时，应按工具提供的恢复机制补读，而不是把压缩状态当作失败，也不能把它当作执行成功。

持久状态：一个索引，按条件启用

持久状态适合跨会话任务、委派或交接、阻塞或暂停任务，以及需要审计记录的高复杂度工作。短单会话任务若能在当前上下文中验证，就不应为了满足目录结构而创建 handoff 文件。

一旦触发持久状态，使用一个项目级 handoff/INDEX.md 作为可识别入口，再使用任务目录中的 HANDOFF.md 保存当前状态。INDEX.md 至少记录任务、状态、更新时间、目标、交接文件和工作目录。历史快照只在当前状态即将被覆盖且确实需要保留决策依据时创建。

关键是保持一个权威入口。不要让不同类型的“持久状态”各自创建索引，也不要把临时日志、缓存和可复现产物混入交接目录。这样既能保持可识别性，也能避免每个小任务都产生额外文件。

路由：能力和推理强度分开评估

模型能力和推理强度是两个维度。固定路径、低风险、易验证的任务可以使用较低能力和较低推理强度；跨模块、关键、高风险或未解决的任务才需要更高能力或更强推理。

成本优先的项目可以把 Basic + xhigh 作为“路由不确定时”的初始基线，但它只是成本策略，不是所有任务的最佳答案。每个可独立路由的工作单元仍应结合范围、风险、不确定性、验证要求、成本和延迟评估；只有需求或结果发生实质变化时才重新评估。不要因为一次临时失败就判定某个路由不受支持，也不要无证据地反复尝试被拒绝的路由。

路由规则应保留“最低充分组合”这个目标，而不是强制所有任务从同一能力层级开始。这样才能在性能、费用和时间之间保持可调节性。

验证：按风险和产物类型匹配

验证不是“每次都跑全套测试”，也不是“看到成功消息就结束”。应先审查受影响行为和 diff，再执行与风险相称的检查，并只因新变更、失败或未解决风险重复检查。

文档没有测试套件时，不应机械补充“测试和类型检查”。但也不能因此跳过验证。文档的验证对象是结构、链接、术语、版本、规则关系和发布格式。验证条款应该允许模型根据产物类型选择证据。

完成条件也要写清楚。若任务包含运行实现、检查结果和修复变更引起的失败，就把这些全部纳入目标；不要在第一次实现后自动停下来等待用户。相反，未授权的额外重构、清理和新功能应作为建议报告，而不是顺手加入当前修改。

长交付物：专项提示优先于全局硬规则

Claude 官方资料指出，Fable 5.1 在 xhigh 或 max 下处理长文档、完整代码文件或大型表格时，可能在思考中起草大段内容，再在最终回答中重复生成。这会增加等待时间和输出 Token。官方建议为思考和最终回复预留总额度，并在确实使用高推理强度时提醒模型把推理用于理解需求、检查输入和解决结构问题，避免完整起草两遍。

这条建议不应直接加入所有模型的全局 AGENTS.md。更合适的做法是：

• 只有经常生成完整长交付物时，才在对应模型的专项提示中加入。
• 只有观察到重复起草或额度不足时，才在具体任务中启用。
• 不把“避免重复起草”误写成“减少必要推理、检查或修订”。
• 对普通代码编辑、局部需求修改和短回答不触发。

目前 OpenAI 关于 GPT-6 Astra 的官方文章重点是减少冗长技能、按需读取文档、清晰定义完成边界和避免不必要的强制测试，并没有给出与 Claude 长交付物重复起草完全等价的结论。因此，GPT 是否需要同一条规则应由实际 Token、延迟和质量数据决定，而不是由模型名称推断。

双语规则和封版检查

如果同时维护 English 权威版和中文审阅版，先更新 English，再同步中文。两份文件应保持章节、条目、代码块、路径、状态值和规则关系一致；中文可以自然表达，但不能改变范围和例外。

封版前至少检查：

1. 是否只保留一个权威规则，删除了重复表达。
2. 每条规则是否有清晰触发条件、动作和边界。
3. 普通授权、明确批准、高风险禁止项是否分层表达。
4. 是否仍会让每次调用都预检、全量读取或重复询问。
5. 是否把模型特有经验误写成全局硬规则。
6. 是否根据产物类型选择验证方式。
7. 持久状态是否只有一个可识别入口。
8. 双语版本是否语义对应，代码块和标识符是否不变。
9. 是否运行 git diff --check，并确认提交只包含授权范围。

结语

AGENTS.md 的质量不取决于规则数量，而取决于它能否在关键分岔点给出短、准、可执行的判断。最值得保留的规则通常是：任务如何分类，授权如何复用，何时暂停，哪些上下文按需读取，怎样验证完成，以及哪些高风险动作必须得到明确批准。

OpenAI 的建议提醒我们重新审视积累的脚手架；Anthropic 的建议提醒我们用实际模型行为来验证专项提示。两者结合后的方法很明确：先删除不必要的触发，再压缩重复语义；保留安全边界和验证证据；对模型特有问题使用局部、可测量的提示。这样既能提高主动性，也能控制上下文和 Token 成本。

参考资料

• Rethinking skills and prompts for GPT-6 Astra，OpenAI Developers，2026-09-11。
• Prompting Claude Fable 5.1，Anthropic Claude Platform Docs，访问日期：2026-09-21。