Claude Codeで技術的負債を可視化して計画的に削減する方法

「リファクタしたいけど時間がない」「どこから手をつけるべきか分からない」。技術的負債は放置するほど返済コストが膨らみます。Claude Code を使えば、負債の可視化・優先順位付け・計画的な返済を低コストで回せます。

1. 負債を洗い出すコードスメル検出

まずは現状把握。コード全体を走査してスメルをリストアップします。

claude -p "
src/ 配下のコードスメルを洗い出してください。
以下の観点でチェック:

- 長すぎる関数（50行超）
- 深いネスト（4階層超）
- 重複コード（類似ロジック）
- God Class（責務過多）
- マジックナンバー
- 未使用のexport
- any型の使用箇所
- TODO / FIXME コメント

結果を docs/tech-debt/smells.md に以下の形式で出力:
| ファイル | 行 | スメル種別 | 深刻度(1-5) | 推奨対応 |
"

深刻度付きで一覧化されるので、議論の土台ができます。

2. 依存関係の負債を測る

古いライブラリやセキュリティ脆弱性も技術的負債です。

claude -p "
package.json と npm audit / npm outdated の結果を分析:

1. メジャー更新が必要なライブラリ
2. 既知の脆弱性があるライブラリ
3. メンテナンスが止まっているライブラリ
4. 重複しているライブラリ（例: moment と date-fns の混在）

docs/tech-debt/dependencies.md に
- 現在のバージョン
- 最新バージョン
- 破壊的変更の有無
- 更新優先度
を表形式で出力してください。
"

3. 優先順位を付ける（ICE スコア）

全部は直せないので、影響度×信頼度×容易さで優先度を決めます。

claude -p "
docs/tech-debt/smells.md と dependencies.md をもとに、
各項目を ICE スコアで評価してください:

- Impact (I): 直したら事業/開発速度にどれだけ効くか (1-10)
- Confidence (C): 効果が出る確度 (1-10)
- Ease (E): 修正の容易さ (1-10)

スコア = I × C × E の降順で並べ替えて、
docs/tech-debt/backlog.md として出力。

上位10件について、それぞれの見積もり工数（人日）も添えてください。
"

優先度が数値で出るので、プロダクトマネージャへの説明にも使えます。

4. 小さく返済する PR を自動生成

優先度トップの項目から、レビューしやすいサイズの PR を作ります。

claude -p "
docs/tech-debt/backlog.md の 1位項目について、
以下の手順で PR を作成:

1. ブランチを切る: refactor/tech-debt-001
2. 該当箇所を修正（ロジック変更なしのリファクタのみ）
3. 既存テストがすべて通ることを確認
4. 変更が大きい場合は複数コミットに分割
5. gh pr create で PR を作成

PR 本文には:
- 何が負債だったか
- なぜ返済するか
- ICE スコア
- 他コードへの影響範囲
を記載してください。
"

5. テスト未整備のエリアを特定

カバレッジが低い箇所は、将来の負債になります。

npm test -- --coverage --coverageReporters=json

claude -p "
coverage/coverage-summary.json を分析:

- カバレッジ 50% 未満のファイル一覧
- そのうち事業ロジックを含む重要ファイル
- テスト追加の優先順位

docs/tech-debt/coverage-gaps.md に出力し、
上位3ファイルについてテストケース案も提案してください。
"

テスト自動生成 と組み合わせると強力です。

6. 負債返済のダッシュボード化

進捗が見えないとチームは諦めます。週次レポートを自動生成。

claude -p "
直近1週間の技術的負債返済状況をレポート化:

- 解決した項目数（docs/tech-debt/backlog.md の完了マーク）
- 新たに発見された負債
- 未着手の深刻度5項目
- 依存ライブラリ更新の進捗

docs/tech-debt/weekly-report-$(date +%Y-%m-%d).md として出力。
チーム朝会で使える粒度でまとめてください。
"

Cron で毎週月曜朝に自動実行すれば、負債返済が定例化します。

7. 新規負債の流入を止める

返済と並行して、新しい負債を増やさない仕組みも必要です。CLAUDE.md にルール化。

## 技術的負債を増やさないルール

### 禁止事項
- any 型の新規追加（理由がある場合は // @ts-expect-error で明記）
- TODO コメントなしの暫定実装
- テストなしの新規ビジネスロジック

### PR チェック項目
- [ ] 新規コードのカバレッジ 80% 以上
- [ ] ESLint エラーゼロ
- [ ] 依存ライブラリ追加の妥当性説明

### 例外を認める条件
- 障害対応のホットフィックス（後追いチケット必須）
- POC コード（本番投入前に書き直す）

Pre-commit フックで自動チェックするとさらに堅牢です。Hooks ガイド を参照。

やってはいけないこと

❌ 一度に全部リファクタしようとする

「全部直す」PR は レビュー不可能 です。必ず 1 スメル = 1 PR に分割。

❌ 振る舞いを変える

リファクタ PR で機能追加やバグ修正を混ぜないこと。レビュー負荷が倍増します。

❌ テストなしで着手

既存テストが薄い箇所は、まずテストを書いてから リファクタ。安全網なしの作業は別の負債を生みます。

まとめ

• コードスメル・依存関係・テスト不足を Claude Code で可視化
• ICE スコアで優先順位を数値化
• 小さな PR に分割して段階的に返済
• 週次レポートで進捗を見える化
• CLAUDE.md で新規負債の流入を防ぐ
• 1 スメル = 1 PR の原則を守る

技術的負債は「いつか直す」ものではなく、「毎週少しずつ返す」ものです。Claude Code があれば返済サイクルのコストが激減します。

関連記事: リファクタリング自動化 / レガシーコード近代化 / コードレビューチェックリスト

公式ドキュメント: Anthropic Claude Code