SuperAPI AI 工具集

retro

编程与开发

查看项目

更新于 11-08 20:55

技能介绍

Retro 是一个针对编码会话的复盘工具,适合在一次会话进展糟糕或缓慢之后,帮助用户找出下一次应当调整的环境因素。它的重点不是修改上次会话产生的代码,而是改善下一个智能体所处的工作环境。复盘依据是会话日志,产出是一份简短、按严重程度排序的环境改动清单,每项都足够具体,可一步落地。

核心原则:检查优于规则。凡是机器能检测出来的错误,就应该做成检查项(lint 规则、类型检查、测试、钩子、CI 作业)。CLAUDE.md 中的文字说明是最后手段,因为其中的每一行都会在每次会话中加载,而且只能以概率方式被遵守。

使用方式上,第一步是读取一手来源,即实际的日志而非对会话的回忆。Claude Code 按项目保存日志,技能提供脚本仅读取当前项目的日志:

python3 <this skill>/scripts/session_log.py list # 列出当前工作目录所属项目的会话 python3 <this skill>/scripts/session_log.py show latest # 或使用 list 中的 SESSION_ID python3 <this skill>/scripts/session_log.py show <id> --full # 包含智能体的叙述文本

不要用通配符扫描 ~/.claude/projects/ 下的其他目录,那些是无关项目的私人会话。该脚本会根据项目路径推导出唯一目录,应使用它而不是在父目录上执行 find/grep。如果用户提供的是书面日志或笔记,也可以以此为依据。日志中可能包含粘贴的密钥和令牌,复盘时不得引用任何秘密值,只能指出其泄露位置。show 摘要会标出常见的浪费:文件被反复读取、命令被重复执行、工具调用失败,以及首次编辑出现在会话的多晚阶段。

第二步是寻找候选项。针对日志中的每个摩擦点,判断哪一类别能在下次消除它:自动检查(智能体犯了工具能捕获的错误,或仓库根本没有护栏,如没有钩子、没有运行 lint/类型/测试的 CI);审查规则(错误属于判断问题而审查未发现);导航(长时间搜索文件或事实,文件之间存在隐藏耦合);精简指令(CLAUDE.md 中不改变行为的行,或已被检查强制执行的规则);工具经济性(昂贵或重复的工具调用,嘈杂的 CLI 或 MCP);信息获取(智能体需要但看不到的事实,如服务器日志、仪表盘、schema);技能(每次会话都重新推导的同一多步流程)。在给出建议前先分类:机械性违规一律用检查,并指明具体规则及其位置,不要再为此加 CLAUDE.md 行;判断性问题应加入审查规则,因为审查在上下文压力较小的差异上进行,而实现智能体才是被上下文淹没的一方;只有既非机械也非判断、且每次会话都需要的,才放入 CLAUDE.md,通常作为指向文档的导航提示。

第三步是为指导文件做预算。CLAUDE.md / AGENTS.md(仓库级和用户全局)在每一轮都会消耗上下文,复盘通常应让它们更短。统计提案新增和删除的行数;如果净增为正,则每新增一行都必须论证其不可强制执行且具有普遍性。向 CLAUDE.md 添加清单、文件地图或“记得……”列表是最常见的错误修复方式。

第四步是报告。按严重程度呈现候选项(对下一次会话的成本 × 复现可能性),每项包含证据(日志时刻,或脱敏后的引用)、改动(确切文件与编辑、规则配置或命令)和类别。结尾给出指导文件的净行数变化。未经用户同意不得应用任何改动。如需记录,可保存至 docx/retros/YYYY-MM-DD-<slug>.md。

常见错误包括:把被违反的规则加粗加进 CLAUDE.md(规则本已存在或显而易见,应建立检查);建议“考虑添加 lint”(应指明规则、配置文件及运行位置);凭会话记忆给建议(应读日志并引用步骤);搜索所有项目的日志(应只用 session_log.py 查当前项目);提议新文档而不先找现成的;以及把检查项写成规则。

该技能改编自 mattpocock/skills 中的 retro(MIT 许可),详见 references/NOTICE.md。