improvement-loop

用途

Improvement Loop 用于在解决完手头的问题之后改进 .claude/ 流水线——绝不在问题解决过程中改进。当某个技能、agent、hook 或脚本产生了错误输出时，先完整地走到正确解决方案，再用学到的经验更新流水线。

核心原则：先修复，充分理解，最后改进。过早的编辑会把不完整的理解固化下来。

何时使用

触发条件（向用户建议）：

• 某个 agent 产生了需要人工纠正的错误输出
• 某个技能缺少指引，导致采用了错误的方法
• 同一错误在多个会话中发生过不止一次
• 某个 hook 未能捕获它本应捕获的东西
• 某个编排脚本遇到了未处理的边界情况
• 某个子 agent 提出了 agent 定义本应回答的问题
• 评审反馈反复指出同一类问题

不要触发：

• 仍在调试或迭代原始问题时
• 对于不太可能复现的一次性问题
• 对于流水线之外的问题（用户错误、外部服务故障）
• 当修复是代码改动而非流水线改动时

门禁：问题是否已解决？

在任何改进工作之前，此检查是强制性的。

在继续之前验证以下全部条件：

• 原始任务或问题在功能上已完成
• 所有测试通过（或修复已提交并验证）
• 用户认为问题已解决（如不明确则询问）

如果任一检查失败，停止。回到问题本身。不要开始改进工作。

主动检测

当你在正常工作期间观察到改进机会时，不要立即行动。而是：

1. 记录机会——在脑中标记出了什么问题以及涉及哪个流水线文件
2. 完成当前任务——完成你正在做的任何事情
3. 询问用户——明确建议该改进：

我在处理 [任务] 时注意到 [具体问题]。根本原因似乎是 [技能/agent/hook/脚本名称]，它 [缺少关于 X 的指引 / 存在反模式缺口 / 未处理 Y]。

你希望我运行一次改进循环来更新它吗？这将涉及：

• [具体改动：例如“为该 agent 的反模式部分添加一条针对硬编码压缩变量名的条目”]
• [预估范围：例如“对该 agent 反模式部分的一行添加”]

始终在开始前询问。用户可能希望推迟、批量改进或以不同方式处理。

五步循环

第 1 步：捕获问题

在细节淡忘之前记录发生了什么：

• 出了什么问题：具体的错误输出或行为
• 哪个流水线文件：涉及的技能、agent、hook 或脚本
• 根本原因：为什么该流水线文件导致了错误结果
• 正确解决方案：正确的做法最终是什么
• 你是如何发现的：调试路径（有助于写出更好的指引）

第 2 步：分类改进

类型	目标	示例
反模式	Agent 定义	“绝不在 sed 模式中硬编码压缩变量名”
缺失指引	技能内容	为某项技术技能添加边界情况处理
新触发	技能描述	添加应调用此技能的症状
Hook 缺口	settings.json / hook 脚本	格式化器未捕获某种文件类型
脚本边界情况	编排脚本	某个阶段未处理的超时
缺失技能	新技能文件	某项技术在任何地方都未记录
缺失 agent	新 agent 文件	未定义的专业角色

第 3 步：做最小改动

写出能防止问题复现的最小改动。

• 反模式？向 agent 的反模式部分添加一条条目
• 缺失指引？向技能添加一段或一个代码示例
• Hook 缺口？向 hook 脚本添加一个条件
• 脚本边界情况？向编排脚本添加一个错误处理器

不要：

• 趁“顺手”重写整个文件
• 为尚未发生的问题添加推测性指引
• 重构与问题无关的周边代码

第 4 步：验证改动

改动类型	验证方式
Agent 反模式	在 agent 文件中 grep 查找冲突的指引
技能内容	从头到尾阅读该技能——新内容是否契合？
Hook 逻辑	用测试输入手动运行该 hook
编排脚本	运行相关的 BATS 测试
新技能/agent	遵循 writing-skills 或 writing-agents 技能（包含测试）

第 5 步：提交并沟通

git add .claude/[changed-file]
git commit -m "improve: [file] - [what was added and why]"

告诉用户改了什么以及为什么：

已用 [改动] 更新 [文件]。这防止了在 [任务] 期间发生的 [问题]。

路由到正确的工具

需要改动什么	如何改动
现有技能（小编辑）	直接编辑
现有 agent（小编辑）	直接编辑
新技能	调用 writing-skills 技能
新 agent	调用 writing-agents 技能
编排脚本	通过 Task 工具派发 cc-orchestration-writer agent
Hook 脚本	通过 Task 工具派发 bash-script-craftsman agent
settings.json	直接编辑

对于新技能和 agent：writing-skills 和 writing-agents 技能有自己的 TDD 循环。遵循它们——不要走捷径。

防止改进漂移

改进可能失控。防范以下反模式：

反模式	预防
扯闲篇——改进 A 导致改进 B 导致 C……	每个循环只做一项改进。如果发现更多，记录下来并询问用户是否单独开一个循环。
推测性改进——“既然我在这，让我也……”	只修复实际发生的问题。YAGNI 同样适用于流水线改进。
固化不完整的理解——在完全解决之前就改进	门禁检查（第 0 步）防止这一点。绝不要跳过它。
过度工程——把一行反模式变成一个新技能	让修复的权重与问题的权重相匹配。
过时的改进——曾经正确但现在不再正确的指引	当你在工作中注意到过时的指引时，将其标记为改进机会。

批量改进

当一个会话中出现多个改进机会时：

1. 在遇到每一个时记录下来（不要行动）
2. 完全完成当前工作
3. 向用户呈现这一批：

我在本次会话中识别出 3 个潜在的流水线改进：

1. [agent-name]：缺少针对 [X] 的反模式（发生在任务 Y 期间）
2. [skill-name]：未覆盖 [Z] 的边界情况（在任务 W 中导致错误方法）
3. [hook]：未捕获 [文件类型]（漏掉了 2 个文件的格式化）

你希望我处理这些吗？我可以按以下方式处理： a) 一批处理（最快，约 5 分钟） b) 逐个循环（最彻底） c) 暂时跳过

危险信号

• 在问题未解决时改进——停止。先修复问题。这是头号违规。
• 未经询问就做改动——在开始改进工作前始终询问用户。
• 单次出现后就改进——一次实例很少能证明流水线改动合理。记录下来并观察是否复现。
• 重写而非追加——大多数改进是添加（反模式、指引、示例），而非重写。
• 跳过验证——未经测试的改进可能引入新问题。

关键洞见

“当某个技能或 agent 产生错误输出时，不要立即编辑它。先走到正确的解决方案。然后用你学到的东西更新该技能。”

跳进流水线文件并调整的冲动很强烈。抵制它。把不完整的理解固化为指引，制造的问题比解决的还多。只有在完全解决之后，改进才变得可靠。