retro

# 回溯 **再也不用重复输入相同的纠正信息。** 你的编码代理一直犯同样的错误。你一直输入相同的纠正信息。每次错误都被记录在没人看的记录中。 每次你运行的 Claude Code 会话都存储在 `~/.claude/projects/` 中，包含完整的记录。在这些文件中，精确记录了代理每次出错的情况：每次“不对，不是这样”，每次你中途按下的 Esc 键，每次它重试了五次，每次你在失败后愤怒退出。 `retro` 读取这些记录并闭环： ``` 你的失败 → 聚类 → 证据 → 具体的CLAUDE.MD差异 ``` 这是 Replit 式的自我改进循环（生产失败 → 聚类 → 证据 → 补丁），应用于你已经拥有的工具。无需微调，无需 API 密钥，无需遥测。在你可以实际更改的层面上进行持续学习。 ## 这难道不是 /insights 么？ Claude Code 内置的 `/insights` 为你提供了优秀的 30 天使用情况报告，并附有建议。`retro` 是一个用于不同任务的不同工具： - **证据，而非总结。** 每个提出的规则都附有来自记录的逐字引用，注明日期。你可以清楚地看到哪些失败本可以通过某个规则避免，并且可以否决它。 - **/insights 未挖掘的信号。** 代理承认“你是对的”（在我最近的 45 天里有 69 次），你大声规定的规则（“记住，从现在开始...”），Esc 中断以及你在之后说的内容。 - **闭环。** `retro` 不仅提供建议：它还会草拟 CLAUDE.MD 差异，你确认后，它会应用。 - **可检查和可黑客。** 一个标准的 Python 库文件，确定性，双语（EN/RU）且带有可插拔的语言包，可自定义窗口（`7d`/`90d`/`all`），JSON 输出可以传递到任何地方。 同时使用两者：`/insights` 用于大局，`/retro` 用于将失败转化为规则。 ## 那关于 netresearch/retro-skill 呢？ 公平的问题 — [netresearch/retro-skill](https://github.com/netresearch/retro-skill) 是一个单独的项目，包含相同的 `/retro` 命令和相同的核心思想（挖掘记录，提出 CLAUDE.MD 规则，批准每个规则）。我们独立构建了它；如果两个团队同时开发了这个项目，显然这个项目有发展潜力。它们是适用于不同用户的不同工具： - **它是框架** — 约 37 个信号，涵盖流程卫生（DCO 签名，工作在主分支，约定提交，工具调用效率），路由到六个目的地，包括对技能存储库和 CI 引导的 PR。依赖于 `jq`、`gh`/`glab`、`git`，一个可选的 SQLite 教练插件，并通过插件市场/Composer 安装。如果您运行具有严格 git 约定的团队，则非常适合。 - **这是一个脚本** — 一个标准的 Python 库文件，零依赖，您可以从头到尾阅读。它专注于**人为**摩擦：您输入的纠正，代理回复的“你是对的”，Esc 中断，您大声规定的规则 — 并且支持双语（EN/RU）且带有可插拔的语言包。适用于个人开发人员日常使用。 如果您想要企业级支持，请使用他们的。如果您想要一个可以捕捉您不断重复输入的内容的小工具，那么您就在对的地方。 ## 安装 ```bash git clone https://github.com/craftwork-design/retro.git && cd retro && ./install.sh ``` 手动安装（也适用于更新）： ```bash TMP=$(mktemp -d) && git clone https://github.com/craftwork-design/retro.git "$TMP" \ && rm -rf ~/.claude/skills/retro && mkdir -p ~/.claude/skills \ && cp -r "$TMP/skill" ~/.claude/skills/retro ``` 需要 Python 3.8+（仅标准库，无依赖）。在 Windows 上，请使用 Git Bash 运行上述命令，并使用 `python` 代替 `python3`。如果您使用自定义的 `CLAUDE_CONFIG_DIR`，安装程序和扫描器都会尊重它。 **仅适用于 Claude Code。** `retro` 读取 `~/.claude/projects/` 记录。Cursor、Codex 和 Zed 正在开发中，目前不支持。如果您是 `retro` 的新手或使用的是新机器？请从 `/retro all` 开始 — 一个全新的项目几乎没有历史记录，因此在您使用了一段时间之前，单个项目视图将为空。 ## 使用 在任何 Claude Code 项目中： ``` /retro # 当前项目，过去 30 天 /retro 7d # 过去一周 /retro all # 此机器上的所有项目 ``` 代理扫描您的记录，聚类重复的摩擦，并向您展示带有证据和拟议的 CLAUDE.MD 差异。在您确认之前，任何内容都不会被应用。 仅需数字，无需代理？直接运行扫描器： ```bash python3 ~/.claude/skills/retro/scripts/scan.py # 漂亮的终端报告 python3 ~/.claude/skills/retro/scripts/scan.py --all # 所有项目 python3 ~/.claude/skills/retro/scripts/scan.py --format json ``` ## 它检测到什么 | 信号 | 含义 | |---|---| | 纠正 | 您告诉代理它错了：明确的（“不是这样”，错误报告（“它又崩溃了”），重试请求（“更短”，“поправь хедер”） | | 承认 | 代理本身说“你是对的”或“我错了”。捕捉没有关键词列表永远无法捕捉的纠正 | | 重复请求 | 跨越 2+ 个不同会话的相同指令。每个集群都是一个现成的 CLAUDE.MD 规则 | | 规则请求 | 您大声规定了一个规则：“记住，从现在开始总是……” | | 中断 | 您在它正在执行某些操作时按下了 Esc 键，以及您之后说的内容 | | 推动 | 您输入了一个裸的“continue”，因为代理在任务中途卡住了 | | 拒绝 | 您拒绝了权限提示 | | 重试循环 | 相同的调用在一个会话中失败了 3+ 次 | | 放弃会话 | 会话在失败后立即结束。 这是其中最昂贵的信号 | ### 语言 大约一半的信号在构造上与语言无关：中断，无推动的重复指令（令牌聚类），重复粘贴，拒绝，错误，重试循环，放弃会话。词法检测器（纠正，承认，规则请求，推动）附带英语和俄语模式，具有形态意识。 其他语言通过 JSON 模式包插入，无需代码更改： ```bash python3 skill/scripts/scan.py --patterns skill/patterns/example-es.json ``` 查看 [skill/patterns/example-es.json](skill/patterns/example-es.json) 以了解格式。语言包的 PR 非常受欢迎。 扫描器是确定性和高召回率的；技能（模型）进行判断：哪些候选者是真正的模式，根本原因是什么，以及可以防止它们的最小规则，钩子或权限更改。 ## 示例 ``` # 回溯：my-app — 过去 30 天 扫描了 42 个会话。最大的问题：测试运行器混淆。 ## 模式 1：错误的测试命令（9 次失败，6 个会话） 证据：`npm test` 在 6 月 12 日，14 日，19 日等时失败，提示“缺少脚本” 根本原因：存储库使用 pnpm + vitest，CLAUDE.MD 从未说明 修复：添加规则“使用 `pnpm vitest run` 运行测试，而不是 `npm test`” ## 提议的 CLAUDE.MD 差异 + ## 命令 + - 使用 `pnpm vitest run` 运行测试，而不是 `npm test` + - 开发服务器已经在 :3000 上运行，永远不要启动第二个 ``` 查看 [examples/report-example.md](examples/report-example.md) 以获取完整报告。 ## 隐私 所有操作都在您的机器上运行。扫描器是一个带有零依赖的标准 Python 库文件。没有网络调用，没有遥测，任何内容都不会离开您的笔记本电脑。您的记录属于您。 ## 路线图 - [ ] 您实际上可以分享的 HTML 报告（仅数字，无记录内容） - [ ] 从拒绝模式生成的钩子建议 - [ ] 报告历史：上周的修复是否减少了本周的纠正？ - [ ] **适用于团队的 retro**：一组工程师共享的经验教训，同步的规则注册表，您的存储库的每周 PR，附带证据。如果这听起来像您的团队，请在此存储库上提出问题。 ## 许可证 MIT --- 独立的开源项目。 与 Anthropic 或 id Software 无关，不受其支持或赞助。Claude 和 Claude Code 是 Anthropic 的商标；DOOM 是 id Software LLC 的商标。