agents-md-writer

AGENTS.md 编写指南

在需要的范围内编写经久适用的指令。新增内容应以仓库中不显而易见的事实、反复出现的问题、硬性约束或明确的团队决策为依据；对于机械规则，优先采用可执行的强制措施。

确定生效的层级

识别请求的操作和目标工具。检查相关的全局、根目录、嵌套、工具专用和旧版来源，以及它们如何组合。局部措辞修正只需检查受影响的指令链；层级迁移则需要覆盖所有候选来源和目标工具。

如果决策取决于文件名、发现机制、优先级、覆盖规则、大小限制或重新加载时机，请查阅当前的官方工具文档。对于 Codex，请从 AGENTS.md 指南 开始。不要假设其他客户端采用相同规则。

放置和修订指引

• 在授权目标范围内，将共享指引放在预期适用范围最广的位置。仅在明确针对个人或全局指引时，才使用用户级全局文件。
• 如果支持嵌套规则，请将子树规则放在最接近且合适的现有文件中。只有当范围不同或需要有意改变优先级时，才新增文件。
• 只有当所有目标工具都会读取同一文件时，才使用跨工具通用文件。Codex 的 AGENTS.override.md 会有意替代同一目录下的 AGENTS.md；其他工具的行为须分别核实。
• 尽可能为重复或冲突的规则指定唯一权威来源。链接到说明文档；保留采取行动所需的命令、不变量和上下文。修改相关说法时，查阅脚本、CI、配置和文档，而不是要求每次编辑都全面检查整个仓库。
• 直接说明期望行为。保留实际的权限边界和容易出错的确切步骤；删除泛泛建议、重复审批要求，以及对任务没有影响的无条件阅读要求。

验证并完成

按照文档记录的加载顺序重新阅读受影响的指令链，检查是否存在矛盾或过时命令。更改层级或发现机制时，通过受支持的内省方式或试运行，检查从根目录到有代表性的嵌套目录中的生效来源。报告变更范围、验证情况，以及任何未经核实的客户端行为。审计应保持只读；经授权的修订则应通过修复和验证完成。