用途:改进 AGENTS.md 与局部智能体指令文件,在不削弱仓库操作契约的前提下减少指令冗余、澄清混乱规则、补充近期教训、删除过时或重复内容、重组指令以提升检索效果,以及更新提交、PR、验证、技能或证据收集规则。不要为追求固定 token 目标而优化,即使冗长也应保留编码了仓库特定安全、验证或工作流约束的规则。
权威依据:编辑前先收集证据,如 git log --oneline -20、git diff main...HEAD --stat、git log --oneline -- AGENTS.md、find .agents/skills -name 'SKILL.md' | sort。来源冲突时按仓库层级判断:src/ 代码与可执行行为、git 历史、按作用域的 AGENTS.md、docs 与 skills。应更新过时文字,而非让代码迁就过时文档。
编辑规则:保留能防止真实失败的具体规则;用一条精确规则替代多条重叠提醒;保留仓库现有约定,如 Bun 优先、gh 操作 GitHub、约定式提交、按范围验证、目录边界、模块命名与技能触发指引;仅在用 rg 验证后删除已退役表面的引用;不引入仓库中不存在的公共验证 CLI;不用通用建议替换操作规则;不添加宽泛的“总是运行一切”门禁。
工作流:确定目标作用域(根 AGENTS.md、嵌套 AGENTS.md、技能局部指令或全部);修改前搜索,如 rg -n "stale-term|removed-command|old-path" AGENTS.md docs skills src package.json;将候选编辑分类为删除、合并、澄清、新增;窄幅编辑,并在指令影响文档、技能、PR、提交或验证策略时同步相关文档;验证使用 git diff --check -- AGENTS.md 与 rg 检查。仅文档指令编辑通常无需可执行验证,应在最终回复中明确说明;若改动脚本、技能契约、模式或运行时指引,则运行受影响的定向测试。
压缩模式:偏好紧凑可测试的指令,例如提交信息使用约定式提交,多行正文优先 git commit -F /tmp/message.txt,正文行不超过 100 字符;避免“简洁并正确提交”这类模糊压缩;仅在便于扫读时使用表格。
学习更新:在发生具体失败时新增或细化规则,如 commitlint 拒绝、清理后仍残留的过时命令路径、评审中发现的验证缺口、工具行为误解、仓库边界违规;规则应写成可执行约束而非日记,并附验证命令。
最终回复:报告更改的文件、澄清或删除的规则、运行的过时引用检查、运行的验证或跳过可执行验证的原因。