writing-agents-md

writing-agents-md

设计一个精简的指令接口，而不是仓库手册。先消除重复和冲突，再将每条保留的规则放到最合适的最小作用范围内。只有当目标宿主评估证明存在能力缺口，或涉及代价高昂的错误、长期有效的政策时，才添加严格约束。

工作流

1. 界定任务。 确定目标宿主、文件、目录范围，以及请求的模式：create、update、rewrite 或 review。除非用户同时要求修改，否则审查应保持只读。遵守仅输出结果的请求。
2. 查明生效链。 编辑前，找到所有适用的祖先、目标、覆盖、嵌套、导入和路径范围指令文件。如果宿主发现机制或优先级会影响结果，请阅读 host-semantics.md。
3. 确定依据。 将现有指令文件视为长期约定来阅读，然后检查仓库代码、配置、CI、文档和近期证据，确认是否存在偏差。可观察到的实现可以推翻过时的实现声明，但不会自动凌驾于人为制定的安全、发布、合规或运维政策之上。将尚未解决的冲突标记出来，以便负责人确认。
4. 逐条处理候选规则。 使用下方的路由接口。审查或修订现有指令链时，请阅读 checklist.md 逐行审查。
5. 只重写选定的目标位置。 只编辑请求授权的目标位置；在该范围之外报告建议的迁移位置，并保持相关文件不变。保持单一事实来源，使用具体且可验证的措辞，并在更新时保留无关且有效的规则。正面描述期望行为；仅在确有必要时设置禁止性护栏，并同时说明安全做法。
6. 验证完成情况。 检查完整的生效链，解决或报告冲突，验证已更改的文件；除非用户只要求输出最终文件，否则说明迁移或删除的内容。

路由接口

对每条规则，选择一项操作：

• 保留 — 当规则会影响此文件作用范围内的决策，且足够简洁、具体、可验证并且稳定，值得始终加载时，将其保留在此处。
• 缩小范围 — 如果只有某个子树或某类文件需要这项长期指引，则将其移至最近的嵌套 AGENTS.md、嵌套 CLAUDE.md 或路径范围规则。
• 延后处理 — 将有条件触发、依赖大量参考资料或需要多步完成的工作移至技能或文档。只有在 Agent 需要了解相关材料存在且知道何时加载时，才留下简短提示。
• 强制执行 — 将确定性要求放入代码、配置、测试、CI、权限或钩子中。如果指令中的理由或备用做法仍会影响决策，则只保留这些非显而易见的内容。
• 删除 — 移除重复内容、过时说法、通用默认规则、对行为没有实际影响的规则、目录介绍，以及简单的一文件或一命令查询。
• 验证 — 当依据不确定时，保留或明确标记尚未解决的规则，尤其是涉及安全、生产环境、发布、法律或外部系统约束的规则。

可发现性是证据，而不是自动删除的理由。如果简短的标准命令或仓库用途说明能避免重复的错误选择或高昂的探索成本，则可以保留。将分支繁多的验证流程移至技能中，而不是扩充始终加载的上下文。

编写规范

• 始终将大部分常驻 token 用于说明容易踩坑之处、会影响决策的约定和安全做法。
• 规则的适用范围应与其加载范围一致；适用于整个仓库并不意味着适用于仓库之外的所有场景，适用于整个子树也不意味着仅适用于特定任务。
• 与其复制参考内容，不如优先提供同时指出相关材料及其适用时机的指引。
• 将示例视为可选参考，而非机械照搬的规则。只有在路由决策仍不明确时，才阅读 examples.md。
• 如果没有值得加载的长期指令，优先使用极简文件，或者不创建文件。如果用户明确要求创建，则应解释这一结论，而不是默默跳过交付内容。

有关此接口和基于模型的剪枝的原理，请阅读 principles.md。