Claude Codeで技術負債を洗い出す方法

Claude Codeを使うと、既存コードベースから技術負債を効率的に検出できます。

単純なコード品質チェックだけでなく、保守性低下、責務肥大化、依存関係の複雑化、設計崩壊なども分析できるため、大規模プロジェクトの改善にも活用できます。

技術負債とは

技術負債とは、短期的な開発優先によって将来的な保守コストや改修コストが増大している状態を指します。

代表的な例として以下があります。

・巨大なController
・重複コード
・密結合設計
・循環依存
・古いライブラリ
・テスト不足
・責務分離不足
・例外処理の欠如
・コメント不足
・暫定実装の放置

技術負債を放置すると、開発速度低下や障害増加につながります。

Claude Codeで技術負債を分析するメリット

Claude Codeを使うと、人間レビューだけでは見つけにくい構造的問題を継続的に分析できます。

特に以下のような分析に向いています。

・責務集中の検出
・アーキテクチャ崩壊の兆候分析
・依存関係の複雑化確認
・保守性低下箇所の特定
・設計ルール違反検出
・テスト不足分析
・例外処理漏れ検出

継続的に分析することで、技術負債が深刻化する前に対処しやすくなります。

CLAUDE.mdに分析ルールを書く

技術負債分析では、プロジェクト固有の問題を定義しておくことが重要です。

CLAUDE.mdへ負債検出ルールを書くことで、Claude Codeが継続的に分析しやすくなります。

# Technical Debt Rules

- Fat Controllerを検出する
- 500行以上のファイルを警告する
- 循環依存を検出する
- 重複コードを指摘する
- TODOコメント放置を検出する
- テスト不足を確認する
- Domain層へのFramework依存を禁止する
- Repository以外のDBアクセスを検出する

チーム独自の技術負債定義を明文化することが重要です。

技術負債分析用のプロンプト例

Claude Codeへ分析依頼する際は、単にレビューを依頼するだけでは不十分です。

技術負債の観点を具体的に指定すると、より実用的な分析結果になります。

このコードベースの技術負債を分析してください。

以下を重点的に確認してください。

- 責務肥大化
- 循環依存
- 保守性低下
- テスト不足
- 例外処理不足
- 重複コード
- 密結合設計
- 暫定実装
- 古い設計パターン

重大度が高い順に出力してください。
改善優先度も提示してください。

優先順位まで出力させると、改善計画を立てやすくなります。

Fat Controllerを検出する方法

技術負債として最も多い問題の一つがFat Controllerです。

Controllerにビジネスロジックが集中すると、保守性が急激に低下します。

Claude Codeには以下のような観点で分析させます。

・Controller行数
・DBアクセス有無
・外部API呼び出し
・分岐数
・責務混在
・複数ユースケース混在

一定以上の複雑度を検出した場合に警告を出す運用が効果的です。

依存関係の複雑化を分析する

技術負債は依存関係の複雑化として現れることが多くあります。

特に以下の問題を重点的に分析すると効果的です。

・循環依存
・双方向依存
・巨大Service依存
・Domain層のFramework依存
・Utilityクラス乱立

依存関係が複雑になるほど、機能追加や修正時の影響範囲が拡大します。

TODOコメントや暫定実装を検出する

長期間放置されたTODOコメントは、代表的な技術負債です。

Claude Codeを使うと、以下のような暫定実装を自動検出できます。

・TODO
・FIXME
・HACK
・temporary
・暫定対応
・あとで修正

特に古いTODOコメントは、設計崩壊の原因になるケースがあります。

テスト不足を分析する方法

テスト不足も大きな技術負債になります。

Claude Codeでは、以下のような観点で分析できます。

・テスト未作成機能
・例外系未テスト
・境界値テスト不足
・E2E不足
・Mock依存過多
・巨大テストケース

テストが不足すると、安全なリファクタリングが難しくなります。

改善優先度を決める方法

技術負債はすべて同時に解消できるわけではありません。

Claude Codeには、以下の観点で優先順位を出させると実用的です。

・障害リスク
・変更頻度
・影響範囲
・保守コスト
・開発速度への影響
・セキュリティ影響

優先度を定義しておくことで、重要な負債から段階的に改善できます。

Pull Requestで技術負債を増やさない運用

既存負債の分析だけでなく、新しい負債を増やさない運用も重要です。

GitHub ActionsとClaude Codeを組み合わせると、PR作成時に新規技術負債を検出できます。

name: Technical Debt Check

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  debt-check:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Claude Debt Analysis
        run: |
          claude review --focus technical-debt

新しいFat Controllerや循環依存をPR段階で防止できるようになります。

定期分析を自動化する

技術負債は継続的に監視することが重要です。

週次や日次でClaude Codeを実行し、負債レポートを自動生成する運用も効果的です。

たとえば以下のようなレポートを出力できます。

・巨大ファイルランキング
・TODO件数推移
・テストカバレッジ低下
・循環依存一覧
・責務集中ランキング

継続監視することで、負債の増加を早期に把握できます。

人間レビューとの使い分け

Claude Codeは技術負債分析に非常に便利ですが、すべてを自動判断できるわけではありません。

特に以下は人間判断が重要です。

・ビジネス優先順位
・改善コストとのバランス
・将来ロードマップ
・組織事情
・リリース計画

AIは負債候補の洗い出しを担当し、改善判断は人間が行う運用が現実的です。

まとめ

Claude Codeを使うと、技術負債を効率的に洗い出せます。

CLAUDE.mdに分析ルールを定義し、責務肥大化、循環依存、テスト不足、重複コードなどを継続的に分析することで、保守性低下を早期発見できます。

GitHub Actionsと連携すれば、Pull Request段階で新規技術負債を防止することも可能です。

人間レビューと組み合わせながら運用することで、長期的なコード品質改善につながります。