fix-debt

概要

このスキルは debt-analysis の分析基準を用いてコードベースの技術的負債を自動修正する。 分析 → 修正 → テスト実行 → 再分析 のループを、🔴高severity問題がゼロになるまで繰り返す。

Step 1: 分析基準のロード

以下を順に読み込む（全て必須）。debt-analyser サブエージェントは使用しない（このスキルが直接参照する）:

1. references/conditional-branch.md — 条件分岐改善パターン（早期return、else排除）
2. references/encapsulation.md — カプセル化違反の8つの検出基準
3. references/soc-overview.md — 関心の分離の概要
4. references/soc-patterns-main.md — SoCの主要3パターン
5. references/soc-patterns-additional.md — SoCの追加2パターン
6. references/soc-analysis-guide.md — SoC分析の5ステップガイド

Step 2: 対象の特定

• 引数が指定されていればそのパスを対象とする
• tdd-cycleから呼び出されていた場合は修正したファイルを対象とする
• 指定なしの場合は現在のワーキングディレクトリ（CWD）全体

Step 3: 初期分析

対象コードを全3基準で分析し、以下の形式で問題リストを作成する:

問題リスト:
ID | 🔴/🟡/🟢 | 基準 | ファイル:行 | 問題の概要
─────────────────────────────────────────
1  | 🔴 高   | 条件分岐 | src/foo.py:23 | 3段ネストのif文
2  | 🔴 高   | カプセル化 | src/bar.py:10 | publicフィールド + 貧血モデル
3  | 🟡 中   | SoC | src/baz.py:50 | 3つの異なる責務が混在

深刻度判定（references/soc-analysis-guide.md の基準に従う）:

• 🔴 高: 5つ以上の関心事 / God Object / 重大なカプセル化違反 / 4段以上のネスト
• 🟡 中: 3-4の関心事 / 中程度のネスト / 貧血モデル / Primitive Obsession
• 🟢 低: 軽微なネスト / 命名問題 / Demeter法則の軽微な違反

Step 4: 修正ループ（最大5イテレーション）

ループ継続条件: 🔴高severity問題が残っている かつ イテレーション < 5

各イテレーションで以下を実行:

4a. 問題の選択

高severity問題の中から、影響範囲が最も小さいもの（単一ファイル内で完結する問題）から優先的に選択する。

4b. 修正方針の決定

選択した問題の基準に応じて references/ から対応パターンを参照し、具体的な修正コードを決定する:

• 条件分岐 → conditional-branch.md のパターン（早期return、ガード節）
• カプセル化 → encapsulation.md の該当項目（完全コンストラクタ、Value Object等）
• SoC → soc-patterns-main.md / soc-patterns-additional.md の対応パターン

4c. コードの修正

Edit または Write ツールで実際にコードを修正する。修正時の制約:

• 1ファイルあたり最大3問題を1回のイテレーションで修正（過度な変更を防ぐ）。複数ファイルを同一イテレーション内で修正してよい
• 修正後もコンパイル/文法エラーが起きないことを優先する
• 型シグネチャやAPIの変更は呼び出し元も更新する
• テストファイルの扱い: ソースのインターフェース変更に伴う既存テストの Edit/Replace（更新）は許可。テストの Delete（削除）は禁止

4d. テスト実行

修正後、プロジェクトの言語に応じてテストを実行する:

# Python
pytest              # または python -m pytest
python -m unittest  # pytestがなければ

# Go
go test ./...

# Rust
cargo test

# JavaScript / TypeScript
npm test            # または bun test, yarn test

# Java
mvn test            # または gradle test

テストファイルが見つからない場合は「テストが存在しないため、リグレッション確認ができません」とユーザーに伝え、修正は続行する。

4e. テスト結果の処理

テスト成功 → その問題に「✅ 修正済み」フラグを立てて次の問題へ

テスト失敗 → その修正をリバートしてから、問題に「⚠️ 修正不可（テスト失敗）」フラグを立てて次の問題へ。リバートは該当ファイルを修正前の状態に戻すことで行う。

4e-extra. 中間状態の保存

テスト結果を処理した後、~/.claude/reports/fix-debt-state.json へ現在の状態を書き出す（セッション中断時の再開用）:

{
  "iteration": <現在のイテレーション番号>,
  "target": "<対象パス>",
  "remaining_high": ["<ファイル:行>", ...],
  "fixed": ["<ファイル:行>", ...],
  "unfixable": ["<ファイル:行>", ...]
}

4f. 再分析（Uncorrelated Evaluator）

全高severity問題を試みたら、以下の3エージェントを並列起動して再評価を委任する。 修正したエージェント自身が再評価すると Self-leniency（甘い評価）が生じるため、必ず独立したエージェントに委任すること。

並列実行:
  ├── debt-analyser サブエージェント
  │     入力: 対象ファイルパス
  │     指示: 修正の副作用チェック — 新たに発生した高severity問題（条件分岐・カプセル化・SoC）を報告せよ
  │
  ├── code-reviewer サブエージェント
  │     入力: 対象ファイルパス
  │     指示: コード品質（設計・可読性・TDD・パフォーマンス）の観点で Critical 問題を報告せよ
  │
  └── security-reviewer サブエージェント
        入力: 対象ファイルパス
        指示: OWASP Top 10・インジェクション・シークレット漏洩を確認し Critical 問題を報告せよ

3エージェントのいずれかで Critical が検出された場合は、次のイテレーションの問題リストに追加する。

Step 5: 完了チェック

ループ終了後、以下の順で確認:

1. 高severity問題がゼロ → ✅ 完了。最終レポートを生成する
2. イテレーション上限（5回）到達 → ⚠️ 上限到達。残存問題を含む最終レポートを生成する
3. 全高severity問題が修正不可 → ❌ 自動修正困難。手動対応が必要な問題を含む最終レポートを生成する

Step 6: 最終レポートの生成

出力先: ~/.claude/reports/fix-debt-YYYYMMDD-HHMMSS.md（絶対パス。~/ はホームディレクトリ）

~/.claude/reports/ ディレクトリが存在しない場合は作成する。

~/.claude/skills/fix-debt/references/report-template.md が存在すればその形式を使う。存在しない場合は以下の形式で直接生成する:

# fix-debt レポート YYYYMMDD-HHMMSS

## 完了ステータス
✅ 完了 / ⚠️ 上限到達 / ❌ 修正不可

## 修正済み問題
| ID | ファイル:行 | 基準 | 適用パターン | Iter |
|---|---|---|---|---|

## 残存問題（中・低severity）
- ...

## 修正不可だった問題
- ...（なければ「なし」）

## 推奨アクションプラン
- ...