code-improver

Code Improver

コードの対象を改善するには、/code-improver:improve を実行します。これは、レビューで重大または主要な指摘がゼロになるまで、指定されたレビュアーと修正用サブエージェントを繰り返し実行し、その後自身の残骸を取り除く動的なワークフローです。ループ、その記録簿、ガードはワークフロー内にあり、このスキルは汎用エントリに必要な3つの入力を収集して結果を伝えます。

ループの開始

ユーザーから提供された内容：$ARGUMENTS（空の場合は、会話から詳細を取得します）。

1. 必須の入力を3つ収集する — 推測しない

1. 対象：改善対象のディレクトリの絶対パスです。相対パスは作業ディレクトリを基準に解決し、ディレクトリの存在を確認します。
2. レビュアー：すべてのレビューを実行する、インストール済みのスキルまたはエージェントです。ユーザーが指定する必要があります。デフォルトも、同梱のレビュアーもありません。種類を判定します。
   • 名前空間付きエージェント（例：plugin-dev:skill-reviewer）→ "kind": "agent"
   • インストール済みスキル（例：pr-review-toolkit:review-pr）→ "kind": "skill" 名前がどちらにも該当する可能性がある場合は、セッションのスキル一覧を確認します。それでも曖昧な場合は、ユーザーに尋ねます。レビュアーが指定されていない場合は、尋ねてください。選んではいけません。
3. スコープ：ループが変更できる、リポジトリ相対の glob です。汎用エントリでは明示的な指定が必要です。ユーザーが指定していない場合は、対象ディレクトリ（<repo-relative-target>/**）を提案し、起動前に確認します。

2. ループスクリプトを解決する

ループは、このプラグイン内の動的ワークフロー workflows/improve.js です。パスで起動します。scriptPath には解決済みの絶対パスが必要です。また、Workflow ツールの name は組み込みおよびプロジェクトのワークフローを解決するため、マーケットプレイスからインストールしたものは code-improver:improve で見つからない場合があります。以下の順に試し、最初に見つかったものを使用します。ホームディレクトリを . より先に確認するため、マーケットプレイスのチェックアウトよりインストール済みのコピーが優先されます。

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js"（その変数が設定されている場合）
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

出力されたパスをそのまま使用します。プラグインディレクトリ、つまり /workflows/improve.js を取り除いたパスが pluginRoot です。3つすべてが空の結果になった場合は、{name: "code-improver:improve"} を一度試します。それも利用できない場合は、停止してループを見つけられなかったことを伝えます。パスを手作業で組み立てたり、ループを独自に代用したりしてはいけません。

3. ワークフローを実行する

Workflow ツールで実行します。{scriptPath: "<the path from step 2>", args: {...}}：

{
  "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 は、ユーザーが別の上限を指定した場合にのみ設定します。
• pluginRoot を指定すると、実行時にメトリクスコレクターを見つけられます。ステップ 2 でワークフロー名にフォールバックした場合に限り、このキーを省略してください。その場合、ワークフローが自身を検索します。
• finalize（{"version_bump": bool, "narration_strip": bool, "docs_pass": bool}）は、デフォルトを上書きする場合にのみ指定します。バージョンの更新は対象がプラグイン内にある場合に行い、ナレーションの削除とドキュメントのパスは常に行います。
• decision は、継続する場合にのみ指定します（下記参照）。

ワークフローはバックグラウンドで実行され、付き添う必要はありません。レビュー、修正、再レビューを行い、修正ラウンドごとにスコープを確認し、レビューで問題がなくなるまで完了しません。コミットは行わず、すべての変更は作業ツリーに残ります。

Workflow ツールを利用できない場合、または使用を拒否された場合は、停止してその旨を伝えてください。 直接編集してループをその場で模倣しないでください。台帳、スコープガード、エスカレーションの保証はワークフローに組み込まれており、その場での模倣にはそれらがありません。

結果が halted: "reviewer-unavailable" の場合は、その結果を伝えて停止してください。 指定されたレビュアーはこのセッションにインストールされていません。どのプラグインがレビュアーを提供するかユーザーに伝え、インストール後に再実行してください。対象を自分でレビューしないでください。

ループの実行中にターンを終了しないでください。 Workflow ツールはタスク ID をすぐに返し、結果は後から届きます。対話セッションでは完了通知によって再度呼び出されるため、それまで待ってください。非対話型の実行（スクリプト、CI、評価）では後続のターンがありません。停止するとループがラウンドの途中で放棄されるため、起動後は完了するまでタスクをポーリングしてください（返されたタスク ID を使う TaskOutput、またはスリープして再確認）。「ループが実行中です。後で報告します」と回答した場合、実行は失われています。

結果の伝達

ワークフローは構造化された結果を返します。区別が重要なので、結果を正確に報告してください。

• converged: true — 最後のアクションはレビューで、重大または主要な指摘はゼロでした。使用したラウンド数、残っている軽微な指摘（open_minor_count）、成果物のパス（ledger_path、metrics）を報告してください。
• capped: true — 修正の予算を使い切り、最終レビューでもブロッキングな問題が見つかりました。はっきりと、上限に達したが、収束していないと伝え、open_blocking を列挙してください。成功したかのように伝えないでください。
• escalation — ループが収束していないこと（指摘の再発、件数の減少なし、または修正による問題の移動）を検出しました。エスカレーションメッセージと指摘 ID をユーザーに伝えてください。これはラウンドを重ねるのではなく、設計上の判断が必要な状況です。
• halted — ガードが作動しました（スコープ違反、未登録の新規ファイル、機能しないまたは利用できないレビュアー、あるいは後続のチェックに失敗する編集を行った finalize パス）。violations／new_untracked_files のパス、finalize_regressions の箇所、注記を伝えてください。
• notes は常に結果とともに伝えてください。「git リポジトリが初期化されました」のような重要な警告も含まれます。

エスカレーション後の継続

ループは仕様上、エスカレーション時に停止します。ユーザーが判断したら、同じ target と reviewer を指定し、次の内容で新しい実行を開始してください。

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

新しい実行ではディスク上の台帳が再読み込みされるため、すべての指摘、却下、判定が引き継がれます。ラウンド数はリセットされますが、再導出は行われません。

実行中のループを停止するには、ワークフロータスクを停止してください（TaskStop）。ディスク上の台帳は直近のラウンドまで更新されているため、再実行するとそこから再開します。

使用しないケース

• Claude Code のスキル：適切なレビュアーを設定する skill-improver エントリーを使用してください
• ブランチ／プルリクエスト：差分からスコープを導出する pr-improver エントリーを使用してください
• 単発のレビュー：レビュアーを直接呼び出してください。ループの利点は反復にあります
• 簡単な単発修正：ファイルを直接編集してください