agent-retro

Agent 复盘

找出本可以避免这些会话中麻烦的 Agent 环境变更。返回一份报告，不要做任何更改。

步骤

1. 在此技能的目录中运行 python3 scripts/collect.py --since <date>。如果没有指定时间范围，则检查当前会话。
2. 在通读日志前先搜索问题：用户更正、中断、被拒绝或失败的工具调用、审批和登录提示、浏览器自动化、用户粘贴的内容、已撤销的编辑、重复搜索、重复出现的审查发现，以及跨会话重复运行的命令或内联脚本。阅读每处问题的相关摘录。
3. 按原因对问题分组。跨多个会话时，只有在至少两个会话中出现的原因才予以保留。将子 Agent 或审查线程计入其发起会话。将每个原因标记为全局、特定于某个仓库，或特定于某种技术栈。
4. 对脚本列出的每个 Remove-When: 尾注，检查其条件是否成立，以及其提交说明中提到的原因是否再次出现。对于条件成立、现有更高层级的修复已覆盖，或会误触发的修复，建议删除。对于修复后再次出现的原因，建议采用更高层级的修复。
5. 根据以下类别，为每个原因提出修复，并放在其标签所指的位置。按优先顺序选择：配置或已安装的工具；脚本、lint 规则、编译器弃用警告或 CI 检查；harness 钩子；技能；始终加载的指令。若选择钩子或更低优先级的方案，请说明为何排除更高层级的修复。钩子会在某个 harness 中每次匹配调用时运行，因此要严格限定匹配范围，只在命中时输出，并说明其他 harness 会失去什么。为每项修复添加一个 Remove-When: 尾注，注明可在修复仍启用时检查的条件，例如工具、模型或上游变更；某个原因只要修复有效就不会出现，因此不能以其未再出现作为修复不再需要的依据。对你提出的任何指令应用 write-for-agents。
6. 按原因再次出现的频率和造成的代价，对候选项排序。为每项列出其类别、标签、证据（会话、日期和简短引文，并隐去机密信息）以及建议的修复。若某个原因的修复已存在，将其标为已修复，并说明如何确认修复已生效。列出脚本读取过的 harness，并引用脚本输出的任何错误。确保步骤 3 中的每个原因都有对应候选项，步骤 4 中的每个尾注都有处理结果。

类别

• navigation。Agent 花了很长时间才找到文件或事实，或者遗漏了文件之间隐藏的依赖关系。在 Agent 最先查找的位置添加指引。
• checks。Agent 犯了自动化检查本可发现的错误，或者仓库在合并前没有运行 lint、类型或测试检查。先查看仓库的检查命令和 CI；已存在但未接入或无法正常工作的检查，就是需要指出的问题。
• codify。Agent 在多个会话中重复执行机械性工作，例如轮询状态、编写 API 客户端、提取日志或运行设置步骤。建议在相关工作所属的仓库中添加已纳入版本控制的脚本或任务运行器目标，并确保失败时以非零状态码退出。
• review。审查 Agent 或技能遗漏了错误，或者反复指出同一个问题。对于机械性违规（例如使用禁用的 API 或不符合要求的导入形式），添加确定性检查：lint 规则、钩子或 CI 任务。判断性规则则保留给审查。
• instructions。Agent 忽略或误读了指令文件或技能；技能在不该触发时触发，或该触发时未触发；或者指令不起作用。在移动指令之前，先修正其措辞。
• tools。Agent 进行了代价高昂或重复的工具调用，或者某个工具或 MCP 服务浪费了 token。对于运行失败或要求登录、而同一服务的 CLI 可正常工作的 MCP 服务，建议移除该服务。
• access。Agent 缺少所需信息，例如服务端日志，或对某项服务的只读访问权限；或者通过浏览器自动化或用户粘贴的内容访问服务，而 MCP 服务或 CLI 本可完成相同工作。建议使用该服务的 MCP 服务；如果已有可用且已安装的 CLI，则建议使用 CLI，并注明所需的登录方式。