writing-agents-md

编写 Agent 指令

让 AGENTS.md/CLAUDE.md 聚焦于 Agent 无法从附近代码或工具中可靠推断出的项目决策。不同运行环境加载指令的方式各不相同；在计算上下文开销前，先确认适用的根目录文件和嵌套文件。

保留、迁移或移除

• 保留不明显的命令、代价高昂的陷阱、领域词汇，以及项目特定的所有权/兼容性决策。
• 将规则迁移到所需的最小子树或按需使用的技能中。长篇依据或事件证据应使用链接引用，而非直接写入。
• 移除通用工程建议、重复规则、过时的模型锁定、修辞性强调、固定的响应流程，以及运行环境或工具链已负责的流程。
• 规则必须注明适用条件。技能可用，并不意味着每项任务都必须使用它。保留具体的安全和产品不变量，同时缩小其流程适用范围。
• 对于重复性工作流，明确说明已有授权具体允许 Agent 自主完成哪些工作、满足什么条件时可以安全执行、可观察到的停止条件是什么，以及哪些操作需要审批。移除会在已授权工作达成结果前打断它的审核关卡。

工作流程

1. 阅读相关指令、当前仓库约定和用户决策。精简策略前先检查近期变更；将历史证据与现行规则分开。
2. 按关注点审查规则：保留、改写、迁移或移除。简要记录重要的策略变更和迁移；除非用户要求，否则无需制作逐行公开判定表。
3. 根据用户当前指示和仓库的权威策略解决矛盾。仅当剩余冲突会改变结果且没有明确的责任方时，才提问。
4. 在规范文件中编辑规则，并更新其引用。保留符号链接和工具生成的区块；避免创建会逐渐偏离的平行副本。
5. 检查重要不变量和实际命令是否仍可查阅、嵌套指令是否一致，以及已移除的规则是否被技能或记忆悄然重新引入。检查链接和行为变更；纯文案编辑无需运行会锁定措辞的测试。

规则应简短、具体；只有违规代价高昂时才使用强调。命令或示例只有在能避免实际歧义时才值得占用篇幅。针对有代表性的任务，优化加载材料的总量，而非只看行数，也不要将无条件的全文阅读简单转移到参考文档中。

完成标准：所请求的范围内每条规则都有唯一明确的归属文件，没有未解决的策略矛盾，并且验证工作与变更相称。报告变更内容和任何遗留限制，不要因此设立定期审计流程。