improvement-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

The Improvement Loop

改进循环

Overview

概述

Improve the

.claude/

pipeline after resolving the issue at hand — never during. When a skill, agent, hook, or script produces bad output, work through to the correct solution first, then update the pipeline with what you learned.

Core principle: Fix first, understand fully, improve last. Premature edits encode partial understanding.

在解决当前问题之后再改进

.claude/

管道——绝不要在解决问题的过程中进行。当某个skill、agent、hook或脚本产生错误输出时，先找到正确的解决方案，再根据所学到的内容更新管道。

核心原则： 先修复问题，再充分理解，最后进行改进。过早的编辑会将片面的理解固化到管道中。

When to Use

适用场景

dot

digraph when_to_use {
    "Issue resolved successfully?" [shape=diamond];
    "Root cause in pipeline file?" [shape=diamond];
    "Worth encoding permanently?" [shape=diamond];
    "Run improvement cycle" [shape=box style=filled fillcolor=lightgreen];
    "Keep working on the issue" [shape=box];
    "Skip - not a pipeline problem" [shape=box];
    "Skip - one-off or too specific" [shape=box];

    "Issue resolved successfully?" -> "Root cause in pipeline file?" [label="yes"];
    "Issue resolved successfully?" -> "Keep working on the issue" [label="no - finish first"];
    "Root cause in pipeline file?" -> "Worth encoding permanently?" [label="yes"];
    "Root cause in pipeline file?" -> "Skip - not a pipeline problem" [label="no"];
    "Worth encoding permanently?" -> "Run improvement cycle" [label="yes"];
    "Worth encoding permanently?" -> "Skip - one-off or too specific" [label="no"];
}

Trigger conditions (suggest to user):

An agent produced incorrect output that required manual correction
A skill was missing guidance that caused a wrong approach
The same mistake has occurred more than once across sessions
A hook failed to catch something it should have
An orchestration script hit an unhandled edge case
A subagent asked questions that the agent definition should have answered
Review feedback repeatedly flags the same class of issue

Do NOT trigger:

While still debugging or iterating on the original issue
For one-off problems unlikely to recur
For issues outside the pipeline (user error, external service failures)
When the fix is a code change, not a pipeline change

dot

digraph when_to_use {
    "Issue resolved successfully?" [shape=diamond];
    "Root cause in pipeline file?" [shape=diamond];
    "Worth encoding permanently?" [shape=diamond];
    "Run improvement cycle" [shape=box style=filled fillcolor=lightgreen];
    "Keep working on the issue" [shape=box];
    "Skip - not a pipeline problem" [shape=box];
    "Skip - one-off or too specific" [shape=box];

    "Issue resolved successfully?" -> "Root cause in pipeline file?" [label="yes"];
    "Issue resolved successfully?" -> "Keep working on the issue" [label="no - finish first"];
    "Root cause in pipeline file?" -> "Worth encoding permanently?" [label="yes"];
    "Root cause in pipeline file?" -> "Skip - not a pipeline problem" [label="no"];
    "Worth encoding permanently?" -> "Run improvement cycle" [label="yes"];
    "Worth encoding permanently?" -> "Skip - one-off or too specific" [label="no"];
}

触发条件（建议用户）：

Agent产生了需要手动修正的错误输出
某个skill缺失指导，导致采取了错误的处理方式
同一错误在多个会话中出现超过一次
Hook未能捕获本应捕获的问题
编排脚本遇到了未处理的边缘情况
子Agent提出了Agent定义本应回答的问题
评审反馈反复指出同一类问题

请勿触发：

仍在调试或迭代原始问题时
针对不太可能再次发生的一次性问题
针对管道之外的问题（用户错误、外部服务故障）
当修复方案是代码变更而非管道变更时

The Gate: Is the Issue Resolved?

准入检查：问题是否已解决？

This check is mandatory before any improvement work.

dot

digraph gate_check {
    "Original task/issue complete?" [shape=diamond];
    "Tests passing?" [shape=diamond];
    "User confirmed resolution?" [shape=diamond];
    "GATE PASSED - proceed to improvement" [shape=box style=filled fillcolor=lightgreen];
    "STOP - return to the issue" [shape=box style=filled fillcolor=salmon];

    "Original task/issue complete?" -> "Tests passing?" [label="yes"];
    "Original task/issue complete?" -> "STOP - return to the issue" [label="no"];
    "Tests passing?" -> "User confirmed resolution?" [label="yes"];
    "Tests passing?" -> "STOP - return to the issue" [label="no"];
    "User confirmed resolution?" -> "GATE PASSED - proceed to improvement" [label="yes"];
    "User confirmed resolution?" -> "STOP - return to the issue" [label="no/unclear"];
}

Verify ALL of these before proceeding:

The original task or issue is functionally complete
All tests pass (or the fix is committed and verified)
The user considers the issue resolved (ask if unclear)

If ANY check fails, stop. Return to the issue. Do not start improvement work.

在进行任何改进工作之前，必须完成此检查。

dot

digraph gate_check {
    "Original task/issue complete?" [shape=diamond];
    "Tests passing?" [shape=diamond];
    "User confirmed resolution?" [shape=diamond];
    "GATE PASSED - proceed to improvement" [shape=box style=filled fillcolor=lightgreen];
    "STOP - return to the issue" [shape=box style=filled fillcolor=salmon];

    "Original task/issue complete?" -> "Tests passing?" [label="yes"];
    "Original task/issue complete?" -> "STOP - return to the issue" [label="no"];
    "Tests passing?" -> "User confirmed resolution?" [label="yes"];
    "Tests passing?" -> "STOP - return to the issue" [label="no"];
    "User confirmed resolution?" -> "GATE PASSED - proceed to improvement" [label="yes"];
    "User confirmed resolution?" -> "STOP - return to the issue" [label="no/unclear"];
}

在继续之前，请验证以下所有条件：

原始任务或问题已功能完成
所有测试通过（或修复已提交并验证）
用户认为问题已解决（如有疑问请询问用户）

如果任何一项检查不通过，请停止。 返回去解决问题，不要开始改进工作。

Proactive Detection

主动检测

When you observe improvement opportunities during normal work, do not act immediately. Instead:

Note the opportunity — mentally flag what went wrong and which pipeline file is involved
Finish the current task — complete whatever you're working on
Ask the user — suggest the improvement explicitly:

I noticed [specific problem] while working on [task]. The root cause appears to be
[skill/agent/hook/script name] which [lacks guidance on X / has an anti-pattern gap /
doesn't handle Y].

Would you like me to run an improvement cycle to update it? This would involve:
- [Specific change: e.g., "adding an anti-pattern entry for hardcoded minified variable names"]
- [Estimated scope: e.g., "a one-line addition to the agent's anti-patterns section"]

Always ask before starting. The user may want to defer, batch improvements, or handle it differently.

在日常工作中发现改进机会时，请勿立即采取行动。而是：

记录改进机会 —— 标记出哪里出了问题以及涉及哪个管道文件
完成当前任务 —— 完成手头正在进行的工作
询问用户 —— 明确提出改进建议：

我在处理[任务名称]时注意到[具体问题]。根本原因似乎是
[skill/agent/hook/脚本名称]存在[缺少X相关的指导/反模式漏洞/无法处理Y情况]的问题。

是否需要我执行改进循环来更新它？这将包括：
- [具体变更：例如，“在Agent的反模式部分添加针对硬编码压缩变量名的条目”]
- [预计范围：例如，“在Agent的反模式部分添加一行内容”]

开始之前务必询问用户。 用户可能希望推迟改进、批量处理或采用其他方式处理。

The Five-Step Cycle

五步改进循环

Step 1: Capture the Problem

步骤1：记录问题

Document what happened before details fade:

What went wrong: The specific incorrect output or behavior
Which pipeline file: The skill, agent, hook, or script involved
Root cause: Why the pipeline file led to the wrong outcome
Correct solution: What the right approach turned out to be
How you discovered it: The debugging path (helps write better guidance)

在细节遗忘之前记录发生的情况：

问题表现： 具体的错误输出或行为
涉及的管道文件： 相关的skill、agent、hook或脚本
根本原因： 管道文件为何导致错误结果
正确解决方案： 最终采用的正确处理方式
发现过程： 调试路径（有助于编写更好的指导内容）

Step 2: Classify the Improvement

步骤2：分类改进类型

Type	Target	Example
Anti-pattern	Agent definition	"NEVER hardcode minified variable names in sed patterns"
Missing guidance	Skill content	Add edge case handling to a technique skill
New trigger	Skill description	Add symptom that should invoke this skill
Hook gap	settings.json / hook script	Formatter not catching a file type
Script edge case	Orchestration script	Unhandled timeout in a stage
Missing skill	New skill file	Technique not documented anywhere
Missing agent	New agent file	Specialized role not defined

类型	目标	示例
反模式	Agent定义	"绝不要在sed模式中硬编码压缩后的变量名"
缺失指导	Skill内容	为技术skill添加边缘情况处理说明
新增触发条件	Skill描述	添加应调用此skill的症状
Hook漏洞	settings.json / Hook脚本	格式化工具未捕获某种文件类型
脚本边缘情况	编排脚本	阶段中存在未处理的超时问题
缺失Skill	新Skill文件	某项技术未在任何文档中记录
缺失Agent	新Agent文件	未定义特定角色

Step 3: Make the Minimal Change

步骤3：进行最小化变更

Write the smallest change that prevents the problem from recurring.

Anti-pattern? Add one entry to the agent's anti-patterns section
Missing guidance? Add one paragraph or code example to the skill
Hook gap? Add one condition to the hook script
Script edge case? Add one error handler to the orchestration script

Do NOT:

Rewrite entire files while you're "in there"
Add speculative guidance for problems that haven't occurred
Refactor surrounding code that isn't related to the issue

编写能防止问题再次发生的最小变更。

反模式问题？在Agent的反模式部分添加一条条目
缺失指导？在Skill中添加一段内容或代码示例
Hook漏洞？在Hook脚本中添加一个条件
脚本边缘情况？在编排脚本中添加一个错误处理程序

请勿：

在修改时重写整个文件
添加针对未发生问题的推测性指导
重构与当前问题无关的周边代码

Step 4: Verify the Change

步骤4：验证变更

Depending on the type of change:

Change Type	Verification
Agent anti-pattern	Grep for conflicting guidance in the agent file
Skill content	Read the skill end-to-end — does the new content fit?
Hook logic	Run the hook manually with test input
Orchestration script	Run relevant BATS tests
New skill/agent	Follow writing-skills or writing-agents skill (includes testing)

根据变更类型进行验证：

变更类型	验证方式
Agent反模式	在Agent文件中搜索是否存在冲突的指导内容
Skill内容	通读Skill内容——新增内容是否契合？
Hook逻辑	使用测试输入手动运行Hook
编排脚本	运行相关的BATS测试
新Skill/Agent	遵循writing-skills或writing-agents skill的流程（包含测试）

Step 5: Commit and Communicate

步骤5：提交并告知用户

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

Tell the user what was changed and why:

Updated [file] with [change]. This prevents [problem] which occurred during [task].

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

告知用户变更内容及原因：

已更新[文件]，进行了[变更内容]。这将防止在[任务]中出现的[问题]再次发生。

Routing to the Right Tool

路由到正确工具

What Needs Changing	How to Change It
Existing skill (small edit)	Edit directly
Existing agent (small edit)	Edit directly
New skill	Invoke `writing-skills` skill
New agent	Invoke `writing-agents` skill
Orchestration script	Dispatch `cc-orchestration-writer` agent via Task tool
Hook script	Dispatch `bash-script-craftsman` agent via Task tool
settings.json	Edit directly

For new skills and agents: The writing-skills and writing-agents skills have their own TDD cycles. Follow them — don't shortcut.

需要变更的内容	变更方式
现有Skill（小修改）	直接编辑
现有Agent（小修改）	直接编辑
新Skill	调用 `writing-skills` skill
新Agent	调用 `writing-agents` skill
编排脚本	通过Task工具调度 `cc-orchestration-writer` Agent
Hook脚本	通过Task工具调度 `bash-script-craftsman` Agent
settings.json	直接编辑

对于新Skill和Agent： writing-skills和writing-agents skill有各自的TDD流程。请遵循这些流程——不要走捷径。

Preventing Improvement Drift

防止改进偏离

Improvements can spiral. Guard against these anti-patterns:

Anti-Pattern	Prevention
Yak shaving — improving A leads to improving B leads to C...	One improvement per cycle. If you discover more, note them and ask the user about a separate cycle.
Speculative improvements — "while I'm here, let me also..."	Only fix the problem that actually occurred. YAGNI applies to pipeline improvements too.
Encoding partial understanding — improving before fully resolving	The gate check (Step 0) prevents this. Never skip it.
Over-engineering — turning a one-line anti-pattern into a new skill	Match the weight of the fix to the weight of the problem.
Stale improvements — guidance that was correct once but isn't anymore	When you notice outdated guidance during work, flag it as an improvement opportunity.

改进工作可能会失控。请防范以下反模式：

反模式	预防措施
偏离主题——改进A导致改进B，进而改进C...	每个循环只处理一项改进。如果发现更多改进机会，记录下来并询问用户是否需要单独的改进循环。
推测性改进——“既然我在这里，顺便也...”	只修复实际发生的问题。YAGNI（You Aren't Gonna Need It）原则同样适用于管道改进。
固化片面理解——在完全解决问题前进行改进	准入检查（步骤0）可防止此情况。绝不要跳过它。
过度设计——将一行反模式条目变成新Skill	让修复的规模与问题的严重程度匹配。
过时改进——曾经正确但现已失效的指导内容	在工作中发现过时指导时，将其标记为改进机会。

Batching Improvements

批量改进

When multiple improvement opportunities arise in one session:

Note each one as you encounter it (don't act)
Finish the current work completely
Present the batch to the user:

I identified 3 potential pipeline improvements during this session:

1. [agent-name]: Missing anti-pattern for [X] (occurred during task Y)
2. [skill-name]: Edge case not covered for [Z] (caused wrong approach in task W)
3. [hook]: Not catching [file type] (missed formatting on 2 files)

Would you like me to address these? I can handle them as:
a) One batch (fastest, ~5 min)
b) Individual cycles (most thorough)
c) Skip for now

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

记录每个机会（不要立即行动）
完全完成当前工作
向用户呈现批量改进建议：

我在本次会话中发现了3个潜在的管道改进点：

1. [Agent名称]：缺少针对[X]的反模式（在任务Y中出现）
2. [Skill名称]：未覆盖[Z]的边缘情况（在任务W中导致错误处理方式）
3. [Hook]：未捕获[文件类型]（遗漏了2个文件的格式化）

是否需要我处理这些改进？我可以采用以下方式：
a) 批量处理（最快，约5分钟）
b) 单独循环处理（最彻底）
c) 暂时跳过

Red Flags

警示信号

Improving while the issue is unresolved — STOP. Fix the issue first. This is the #1 violation.
Making changes without asking — Always ask the user before starting improvement work.
Improving after a single occurrence — One instance rarely justifies a pipeline change. Note it and watch for recurrence.
Rewriting instead of appending — Most improvements are additions (anti-patterns, guidance, examples), not rewrites.
Skipping verification — An untested improvement can introduce new problems.

在问题未解决时进行改进——停止。先修复问题。这是最常见的违规行为。
未询问就进行变更——开始改进工作前务必询问用户。
单次出现后就进行改进——单次事件很少值得进行管道变更。记录下来并观察是否会再次发生。
重写而非追加——大多数改进是添加内容（反模式、指导、示例），而非重写。
跳过验证——未测试的改进可能会引入新问题。

Key Insight

关键见解

"When a skill or agent produces bad output, don't immediately edit it. Work through to the correct solution first. Then update the skill with what you learned."

The instinct to jump into the pipeline file and tweak is strong. Resist it. Partial understanding encoded as guidance creates more problems than it solves. The improvement only becomes reliable after full resolution.

"当某个Skill或Agent产生错误输出时，不要立即编辑它。先找到正确的解决方案，再根据所学到的内容更新Skill。"

直接修改管道文件的冲动很强烈。请抵制这种冲动。将片面理解固化为指导内容会带来更多问题。只有在完全解决问题后，改进内容才会可靠。