code-refinement

コード改善ワークフロー

6つの観点から、継続的に変化するコードの品質を分析し、改善します。

クイックスタート

/refine-code
/refine-code --level 2 --focus duplication
/refine-code --level 3 --report refinement-plan.md

使用する場面

• AI を活用した短期開発スプリントの後
• メジャーリリースの前（品質ゲート）
• コードは「動くが、何か問題がありそう」なとき
• 既存モジュールをリファクタリングして明確にしたいとき
• 継続的に変化するコードの技術的負債を減らすとき

使用しない場面

• 不要なコードや未使用コードを削除するとき（conserve:bloat-detectorを使用してください）

分析の観点

#	観点	モジュール	検出する問題
1	重複と冗長性	duplication-analysis	ほぼ同一のブロック、類似した関数、コピー＆ペースト
2	アルゴリズム効率	algorithm-efficiency	O(n)で済む処理のO(n^2)、不要な反復
3	クリーンコード違反	clean-code-checks	長すぎるメソッド、深いネスト、適切でない命名、マジック値
4	アーキテクチャとの適合性	architectural-fit	パラダイムの不一致、結合度の違反、漏れのある抽象化
5	アンチスロップパターン	clean-code-checks	時期尚早な抽象化、エンタープライズのコスプレ、実体のないパターン
6	エラー処理	clean-code-checks	裸のexcept、握りつぶされたエラー、正常系のみの処理
7	追加バイアス	imbue:justify	根本的な修正より回避策を優先すること、テストの改ざん、不要な追加

プラグイン固有のパターン

標準的なコード品質のヒューリスティクスでは構造上の問題を見落としやすい、プラグインやスキルのコードベース向けの検出パターンです。

委譲スタブの本体

「Xに委譲する」と宣言しながら、テンプレート本体全体も保持しているスキルは、二重の役割を担っています。委譲するスキルは、対象へ処理を振り分ける30行未満の薄いラッパーにしてください。本体が50行を超える委譲スキルにはフラグを立てます。

モジュールの肥大化

コンテンツの40％以上が重複しているモジュールファイルを10個以上持つスキルには、フラグを立てます。兆候：異なる切り口から同じAPIの範囲を扱う2つのモジュール（例：同じ設定オプションや同じCLIフラグを両方が説明している）。

単一モジュールの肥大化

500行を超える個々のモジュールファイルには、分割または縮小の候補としてフラグを立てます。大きなモジュールでは段階的な読み込みが機能せず、一部の情報を得るためにファイル全体を読み込む必要があります。

Pythonの参照切れ

Pythonコマンド（python -m module.nameまたはpython -c "from module import ..."）を参照しているものの、参照先のモジュールがプラグインのsrc/ディレクトリに存在しないスキルです。これらは、名前変更または削除されたコードへの古い参照です。

段階的な読み込み

改善の対象に応じてモジュールを読み込みます。

• modules/duplication-analysis.md（約400トークン）：重複の検出と集約
• modules/algorithm-efficiency.md（約400トークン）：計算量の分析と最適化
• modules/clean-code-checks.md（約450トークン）：クリーンコード、アンチスロップ、エラー処理
• modules/architectural-fit.md（約400トークン）：パラダイムの整合性と結合度

徹底的に改善する場合は、すべて読み込みます。対象を絞って作業する場合は、関連するモジュールのみを読み込みます。

必須のTodoWrite項目

1. refine:context-established：対象範囲、言語、フレームワークの検出
2. refine:scan-complete：すべての観点にわたる検出結果
3. refine:prioritized：影響度と作業量に基づく検出結果の順位付け
4. refine:plan-generated：変更前と変更後を示す具体的なリファクタリング計画
5. refine:evidence-captured：imbue:proof-of-workに従ったエビデンスの付録
6. refine:findings-verified：citation_verifier.pyによる引用の確認
7. refine:execution-complete：対象ウェーブに列挙された候補をすべて解決、または理由を記録済み（呼び出しに「execute findings」以上の指示が含まれる場合のみ必須。Step 6を参照）

ワークフロー

Step 1：コンテキストの確立（refine:context-established）

プロジェクトの特性を検出します。

# Language detection
find . -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  \( -name "*.py" -o -name "*.ts" -o -name "*.rs" -o -name "*.go" \) \
  | head -20

# Framework detection
ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null

# Size assessment
find . -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  \( -name "*.py" -o -name "*.ts" -o -name "*.rs" \) \
  | xargs wc -l 2>/dev/null | tail -1

Step 2：観点別スキャン（refine:scan-complete）

関連するモジュールを読み込み、ティアレベルに応じて分析を実行します。 観点7（追加バイアス）では、Skill(imbue:justify)を実行してバイアススコアを算出し、Iron Lawへの準拠を確認したうえで、不要な追加や回避策にフラグを立てます。

ステップ 3：優先順位付け（refine:prioritized）

指摘事項を次の基準で順位付けします。

• 影響度：品質がどの程度向上するか（HIGH/MEDIUM/LOW）
• 作業量：変更する行数、変更対象ファイル数（SMALL/MEDIUM/LARGE）
• リスク：バグを引き起こす可能性（LOW/MEDIUM/HIGH）

優先順位は、影響度 HIGH ＋ 作業量 SMALL ＋ リスク LOW の指摘事項を最優先にします。

ステップ 4：計画の生成（refine:plan-generated）

各指摘事項について、以下を提示します。

• ファイルパスと行範囲
• アンカー：引用した行のソーステキスト（原文のまま）
• 現在のコードスニペット
• 改善案
• 根拠（該当する原則／評価軸）
• 推定作業量

ステップ 5：エビデンスの記録（refine:evidence-captured）

imbue:proof-of-work が利用可能な場合は、以下を記録します。

• 各指摘事項の [E1]、[E2] 参照
• 測定可能な場合は、変更前／変更後のメトリクス
• 該当する原則への違反

代替手段：imbue がインストールされていない場合は、TodoWrite との連携を使わず、同じ [E1] 参照形式でレポート内にエビデンスを記録します。

ステップ 6：指摘事項の実行（refine:execution-complete）

ステップ 1～5 で計画を作成します。ステップ 6 で完了処理を行います。どちらもこのスキルの一部です。ユーザーが明示的に「plan only」と指定しない限り、計画の作成だけで実行を終了しません。

実行モードの判定

ユーザーの指示を次の表に照らし合わせ、実行範囲を決定します。

ユーザーの指示	モード	停止条件
/code-refinement（指定なし）	計画のみ	ステップ 5 の後
--dry-run または「just plan」	計画のみ	ステップ 5 の後
「execute findings」／「apply fixes」	計画を作成し、Wave 1 を実行	作業量 SMALL かつリスク LOW の指摘事項をすべて完了した後
「execute all findings」／「all phases」／「all waves」	計画を作成し、すべての Wave を実行	すべての指摘事項（または各 Wave に列挙された候補）が、コミットによって完了するか、統合レポートに項目ごとの明確な理由が記載された後
「ignore scope guard」	ブランチサイズの制限を解除	ブランチのメトリクスによる実行制限は適用されません。RED ゾーンを越えて続行します。
「do not stop until complete」／「until ALL ... complete」	タスク途中の要約を行わない	統合レポートで、各 Wave に列挙された候補がすべて完了または理由付きで見送りとなった場合にのみ、完了を宣言します。

トリガーは組み合わせて適用されます。--tier 3 --execute all findings --ignore-scope-guard の場合、ブランチサイズにかかわらず、Wave 2 と Wave 3 の候補をすべて完了まで実行します。

完了条件（実行モードが有効な場合）

以下のすべてを満たすまで、タスクは完了ではありません。

1. Wave 2 の候補（統合レポートの「Wave 2 Candidates」セクションに記載）：すべての項目について、完了を示すコミットがあるか、実行できない理由が統合レポートに項目ごとに明記されていること。
2. Wave 3 の候補（統合レポートの「Wave 3 Candidates」セクションに記載）：同じ条件を適用します。ユーザーが「execute all」と指示した場合、LARGE の作業を「専用 PR が必要」などの一般的な理由で先送りしてはいけません。機械的に実行できる項目（split-by-class、mixin-package、module-merge）は実行し、「保留」とするのはアーキテクチャレベルの判断が必要な項目（スキーマ変更、新しい依存関係の宣言、新しい venv レイアウト）に限ります。
3. 統合レポートの更新：docs/refinement/<date>/00-synthesis.md に、各完了項目のコミット SHA と、見送った各項目の一文の理由を記録します。

エージェント自身のアンチパターン検知

実行中に次のいずれかを行おうとしていることに気づいた場合、これは停止フックの漏れです。指摘事項の実行に戻ってください。

アンチパターン	判定
「Wave 2 が完了しました。Wave 3 に移ります。」（途中での要約）	早すぎるターン完了の合図です。作業を続けてください
機械的に実行できる項目をすべて終える前に、「理由を添えて見送り項目を記録する」	書類上の記録を口実に実行を回避しています
完了または理由付きで見送りになっていない候補が 1 件以上ある状態で、完了要約を書く	完了条件への違反です
指示に「do not stop」が含まれているのに、ユーザーへ「続けますか？」と再確認する	途中で要約しないという明示的な指示を無視しています

ゲートが判定するもの

ゲートは、エージェント自身の作業報告ではなく、記録を読み取ります。 .review/findings.json と引用検証ツールの終了コード（次のセクションを参照）により、どの候補が解決済みかが示され、残りは統合結果に記載されます。実行は max_waves（デフォルトは 3。未解決の候補を確認するパスごとに 1 ウェーブ）によって制限されます。予算を使い切った場合、またはハーネスが停止シグナルを発した場合、実行を停止します。残っているすべての候補を、解決に必要な内容とともに統合結果のギャップとして記録し、ターンを終了してください。停止シグナルを受けた後に再開してはいけません。ハーネスによる停止は実行の外部からのシグナルであり、それを無視する実行は、自らの完全性を自分で判定することになります。これは、逸脱すると測定された構成です（arXiv 2607.17641）。

検出結果が根拠に基づいていることを検証する（refine:findings-verified）

検出結果を .review/findings.json に書き込み、引用検証ツール（Skill(imbue:review-core) のステップ 5）を実行し、検証ツールが却下したものは削除するか UNVERIFIED とラベル付けしてください。

終了基準

• 6 つすべての分析観点について、対象範囲の判定（検出結果または「問題は検出されませんでした」）がある。
• 各検出結果に、ファイルパス、行範囲、逐語的な Anchor（該当行の正確なソーステキスト）が含まれている。
• 報告されたすべての検出結果に、citation_verifier.py によって確認された Location と逐語的な Anchor が含まれている（終了コード 0）。または、未検証の検出結果が削除されているか、UNVERIFIED とラベル付けされている。

階層別分析

階層	所要時間	対象範囲
1: クイック（デフォルト）	2-5 分	複雑さのホットスポット、明らかな重複、命名、マジック値
2: 対象を絞った分析	10-20 分	アルゴリズム分析、重複の全件スキャン、アーキテクチャとの整合性
3: 詳細分析	30-60 分	上記すべてに加え、モジュール間の結合、パラダイムへの適合性、綿密な計画

プラグイン間の依存関係

依存関係	必須？	代替手段
imbue:proof-of-work	任意	レポート内に証拠を記載
conserve:code-quality-principles	任意	組み込みの KISS/YAGNI/SOLID チェック
archetypes:architecture-paradigms	任意	原則に基づくチェックのみ（パラダイムの検出なし）

関連モジュール

• コード品質分析 - 重複検出コマンドと統合戦略

任意のプラグインがインストールされていない場合、スキルは機能を適切に縮小して動作します。

• imbue がない場合：証拠はインラインで記録され、TodoWrite による作業証明はありません
• conserve がない場合：組み込みのクリーンコードチェック（サブセット）を使用します
• archetypes がない場合：パラダイム固有の整合性確認を省略し、結合と凝集の原則のみを使用します