code-improver

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Improver

Improve any code target by running

/code-improver:improve

— a dynamic workflow that loops the named reviewer and a fixer subagent until a review reports zero critical/major findings, then strips its own residue. The loop, its ledger, and its guards live in the workflow; this skill collects the three inputs the generic entry requires and relays the outcome.

通过运行

/code-improver:improve

来改进任意代码目标——这是一个动态workflow，会循环调用指定的审查者和修复子Agent，直到审查报告显示无严重/重大问题，然后清除自身残留信息。该循环、问题记录及范围管控逻辑均内置在workflow中；本skill负责收集通用入口所需的三项输入并反馈执行结果。

Starting the loop

启动循环

The user provided:

$ARGUMENTS

(if empty, take the details from the conversation).

用户提供的参数：

$ARGUMENTS

（若为空，则从对话中提取详情）。

1. Collect the three required inputs — no guessing

1. 收集三项必填输入——禁止猜测

Target: the absolute path to the directory under improvement. Resolve relative paths against the working directory; verify the directory exists.
Reviewer: the installed skill or agent that performs every review. The user must name it — there is no default and no bundled reviewer. Determine the kind:
- a namespaced agent (e.g.
```
plugin-dev:skill-reviewer
```
  ) →
```
"kind": "agent"
```
- an installed skill (e.g.
```
pr-review-toolkit:review-pr
```
  ) →
```
"kind": "skill"
```
  If the name could be either, check the session's skill listing; if still ambiguous, ask the user. If no reviewer was named, ask — do not pick one.
Scope: repo-relative globs the loop may touch. The generic entry requires it explicitly; if the user did not give one, propose the target directory (
```
<repo-relative-target>/**
```
) and confirm before launching.

目标路径：待改进目录的绝对路径。将相对路径解析为工作目录下的绝对路径；需验证目录是否存在。
审查者：执行每轮审查的已安装skill或Agent。用户必须指定具体名称——无默认值，也无内置审查者。需确定类型：
- 带命名空间的Agent（例如
```
plugin-dev:skill-reviewer
```
  ）→
```
"kind": "agent"
```
- 已安装的skill（例如
```
pr-review-toolkit:review-pr
```
  ）→
```
"kind": "skill"
```
  若名称可能属于任意一种，需检查会话中的skill列表；若仍存在歧义，询问用户。若未指定审查者，需询问用户——不得自行选择。
范围：循环可修改的仓库相对路径通配符。通用入口要求明确指定范围；若用户未提供，建议使用目标目录（
```
<repo-relative-target>/**
```
）并在启动前确认。

2. Resolve the loop script

2. 解析循环脚本

The loop is the dynamic workflow

workflows/improve.js

in this plugin. Launch it by path:

scriptPath

takes a resolved absolute path, and the Workflow tool's

name

resolves built-in and project workflows, so a marketplace-installed one may not answer to

code-improver:improve

. Try in order, first hit wins — the home directories come before

so an installed copy beats a checkout of this marketplace:

Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"

Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js"

(if that variable is set instead)

Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

Use the path exactly as printed. Its plugin directory — the path with

/workflows/improve.js

removed — is

pluginRoot

. If all three come back empty, try

{name: "code-improver:improve"}

once; if that is unavailable too, stop and say the loop could not be located. Do not assemble a path by hand and do not improvise the loop.

循环逻辑位于本插件的

workflows/improve.js

动态workflow中。通过路径启动：

scriptPath

需传入解析后的绝对路径，而Workflow工具的

name

用于解析内置和项目workflow，因此市场安装的版本可能无法通过

code-improver:improve

调用。按以下顺序尝试，找到第一个有效路径即可——主目录优先级高于

，因此安装版本会优先于本地克隆的市场版本：

Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"

Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js"

（若该变量已设置）

Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

完全按照输出的路径使用。移除

/workflows/improve.js

后的路径即为

pluginRoot

。若上述三种方式均返回空，尝试使用

{name: "code-improver:improve"}

一次；若仍不可用，停止操作并告知无法找到循环脚本。不得手动拼接路径或自行编写循环逻辑。

3. Invoke the workflow

3. 调用workflow

Run it with the Workflow tool,

{scriptPath: "<the path from step 2>", args: {...}}

json

{
  "target": "<absolute target path>",
  "reviewer": { "kind": "agent|skill", "name": "<namespaced-name>", "notes": "<what the reviewer should know about the target>" },
  "scope": ["<repo-relative-glob>/**"],
  "pluginRoot": "<the plugin directory from step 2>",
  "maxRounds": 5
}

```
maxRounds
```
only if the user asked for a different cap.
```
pluginRoot
```
lets the run find its metrics collector; omit the key only if step 2 fell through to the workflow name — the workflow then searches for itself.
```
finalize
```
(
```
{"version_bump": bool, "narration_strip": bool, "docs_pass": bool}
```
) only to override the defaults: version bump when the target sits inside a plugin, narration strip and docs pass always.
```
decision
```
only on continuation (below).

The workflow runs in the background and needs no babysitting: it reviews, fixes, re-reviews, checks scope after every fix round, and can only complete on a clean review. It never commits; all changes stay in the working tree.

If the Workflow tool is unavailable or denied, stop and say so. Do not improvise the loop inline with direct edits — the ledger, scope guard, and escalation guarantees live in the workflow, and an inline imitation has none of them.

If the result is
halted: "reviewer-unavailable"
, relay it and stop. The named reviewer is not installed in this session; tell the user which plugin provides it and re-run after installing. Do not review the target yourself.

Do not end your turn while the loop is running. The Workflow tool returns a task id immediately; the result comes later. In an interactive session the completion notification re-invokes you — wait for it. In a non-interactive run (scripted, CI, eval) there is no later turn: stopping abandons the loop mid-round, so after launching, poll the task (TaskOutput with the returned task id, or sleep-and-recheck) until it completes, then relay the result. A session that answers "the loop is running, I'll report later" has lost the run.

使用Workflow工具运行，格式为

{scriptPath: "<步骤2获取的路径>", args: {...}}

：

json

{
  "target": "<绝对目标路径>",
  "reviewer": { "kind": "agent|skill", "name": "<命名空间名称>", "notes": "<审查者需了解的目标相关信息>" },
  "scope": ["<仓库相对路径通配符>/**"],
  "pluginRoot": "<步骤2获取的插件目录>",
  "maxRounds": 5
}

仅当用户要求不同上限时设置
```
maxRounds
```
。
```
pluginRoot
```
用于让运行实例找到其指标收集器；仅当步骤2退化为使用workflow名称时可省略该字段——此时workflow会自行搜索自身路径。
```
finalize
```
(
```
{"version_bump": bool, "narration_strip": bool, "docs_pass": bool}
```
)仅用于覆盖默认值：当目标位于插件内时自动升级版本，始终清除叙述信息并确保文档合规。
```
decision
```
仅用于后续的升级处理（见下文）。

该workflow在后台运行，无需人工干预：它会执行审查、修复、重新审查，每轮修复后检查范围，仅当审查无问题时才会完成。它不会提交更改；所有修改均保留在工作区中。

**若Workflow工具不可用或被拒绝，停止操作并告知用户。**不得直接通过在线编辑来模拟循环——问题记录、范围管控和升级保障均内置在workflow中，在线模拟无法实现这些功能。

**若结果为

halted: "reviewer-unavailable"

，反馈该信息并停止操作。**指定的审查者未在当前会话中安装；告知用户该审查者所属的插件，安装后重新运行。不得自行审查目标代码。

**循环运行期间不得结束会话。**Workflow工具会立即返回任务ID，结果稍后返回。在交互式会话中，完成通知会重新调用您——请等待结果。在非交互式运行（脚本、CI、评估）中，没有后续会话：停止操作会导致循环中途终止，因此启动后需轮询任务（使用返回的任务ID调用TaskOutput，或通过睡眠后重新检查）直至完成，然后反馈结果。若会话回复“循环正在运行，稍后报告”，则会丢失运行状态。

Relaying the result

反馈结果

The workflow returns a structured result. Report it honestly — the distinctions matter:

converged: true
— the last action was a review with zero critical/major findings. Report rounds used, remaining minor findings (
```
open_minor_count
```
), and the artifact paths (
```
ledger_path
```
,
```
metrics
```
).
capped: true
— the fix budget ran out and the FINAL review still found blocking issues. Say plainly: capped, NOT converged, and list
```
open_blocking
```
. Do not present this as success.
escalation
— the loop detected it was not converging (recurring findings, non-decreasing counts, or a fix relocating a problem). Relay the escalation message and finding ids to the user: this needs a design decision, not more rounds.
halted
— a guard fired (scope violation, unregistered new files, a dead or unavailable reviewer, or a finalize pass whose own edits failed the check that follows it). Relay the paths in
```
violations
```
/
```
new_untracked_files
```
, the sites in
```
finalize_regressions
```
, and the notes.
notes
always travel with the result — surface them; they include loud warnings such as "a git repository was initialized".

workflow会返回结构化结果。需如实报告——不同结果的区别至关重要：

converged: true
— 最后一次审查无严重/重大问题。报告使用的轮次、剩余的次要问题数量（
```
open_minor_count
```
）以及生成的文件路径（
```
ledger_path
```
,
```
metrics
```
）。
capped: true
— 修复次数已达上限，且最终审查仍发现阻塞性问题。需明确说明：已达上限，未收敛，并列出
```
open_blocking
```
中的问题。不得将此视为成功。
escalation
— 循环检测到无法收敛（重复出现的问题、问题数量未减少，或修复导致问题转移）。将升级消息和问题ID反馈给用户：这需要设计决策，而非更多轮次的修复。
halted
— 触发了管控机制（范围违规、未注册的新文件、审查者不可用，或finalize阶段的修改在后续检查中失败）。反馈
```
violations
```
/
```
new_untracked_files
```
中的路径、
```
finalize_regressions
```
中的问题位置以及备注信息。
notes
始终随结果返回——需展示这些信息；其中包含诸如“已初始化git仓库”之类的重要警告。

Continuing after an escalation

升级后的后续操作

The loop stops on escalation by design. When the user decides, start a fresh run with the same

target

and

reviewer

plus:

json

{ "decision": "<the user's ruling, verbatim>" }

The new run reloads the on-disk ledger, so every finding, rejection, and verdict carries over — rounds restart, re-derivation does not.

To stop a running loop, stop the workflow task (TaskStop); the ledger on disk is current to the last round and a re-run resumes from it.

循环会在触发升级时主动停止。当用户做出决策后，使用相同的

target

和

reviewer

启动新的运行，并添加：

json

{ "decision": "<用户的裁决原文>" }

新运行会重新加载磁盘上的问题记录，因此所有问题、拒绝和裁决都会保留——轮次重新开始，但无需重新推导。

要停止正在运行的循环，需终止workflow任务（TaskStop）；磁盘上的问题记录会更新至最后一轮，重新运行时会从该状态恢复。

When NOT to use

禁用场景

A Claude Code skill: use the
```
skill-improver
```
entry — it wires the right reviewer
A branch / pull request: use the
```
pr-improver
```
entry — it derives scope from the diff
One-time review: dispatch the reviewer directly; the loop's value is iteration
Quick single fixes: edit the file directly

Claude Code skill：使用
```
skill-improver
```
入口——它已配置了合适的审查者
分支/拉取请求：使用
```
pr-improver
```
入口——它会从差异中自动推导范围
一次性审查：直接调用审查者即可；循环的价值在于迭代执行
快速单次修复：直接编辑文件即可