Claude Codeで技術的負債を安全に減らす実践ガイド

「技術的負債を返したい」と言いながら、毎週のスプリントでは新機能に押し流される。気づくと any、古い依存関係、落ちるテスト、巨大なファイル、誰も意味を覚えていない TODO が増えている。

Claude Code は、この状態を一気に魔法で直す道具ではありません。むしろ強みは、負債を棚卸しし、根拠を付け、レビューできる小さなPRに分解するところにあります。自動リファクタリングはリスクゼロではないので、テスト、差分レビュー、権限設定、チームの合意をセットで扱います。

この記事では、チームで使える技術的負債返済の流れを、コピペで試せるプロンプトと Node.js スクリプト付きでまとめます。Claude Code の一般的なリファクタリングやテストの使い方は公式の Common workflows、プロジェクト知識の残し方は Memory、安全な運用設定は Settings も合わせて確認してください。社内ルールを CLAUDE.md に残す方法は CLAUDE.mdベストプラクティス、テスト設計は Claude Codeテスト戦略、権限運用は Approval and Sandbox Guide が参考になります。

全体像：大掃除ではなく返済サイクルにする

技術的負債は「いつかまとめて直す」と言った瞬間に失敗しやすくなります。大きすぎるブランチはレビューされず、テスト範囲も曖昧になり、結局リリース直前に戻されます。

チームで回すなら、次のような短いループにします。

flowchart LR
  A["棚卸し"] --> B["証拠を集める"]
  B --> C["ICE/RICEで優先順位"]
  C --> D["小さなPRに分割"]
  D --> E["テストとレビュー"]
  E --> F["負債台帳を更新"]
  F --> A

ここでいう棚卸しは、匂いを感覚で語ることではありません。ファイル行数、 TODO/FIXME、any、重複ロジック、依存関係の古さ、 flaky test（時々失敗する不安定なテスト）など、あとから議論できる証拠を集めます。

進め方	向いている場面	危険な点	Claude Codeでの使い方
大規模一括リファクタ	フレームワーク移行など境界が明確な時	差分が巨大でレビュー不能	事前調査と移行計画だけ任せる
小さな返済PR	日常的な負債削減	効果が見えにくい	台帳、スコア、PRチェックリストで可視化
依存関係更新スプリント	セキュリティ更新やEOL対応	破壊的変更を見落とす	changelog確認とテスト範囲の洗い出し
テスト安定化	CIが信用されていない時	原因を見ずにリトライで隠す	失敗ログの分類と再現手順の作成

ユースケース1：コードスメルを棚卸しする

code smell は「バグではないが、将来の変更を難しくする匂い」です。初心者向けに言えば、読みにくい巨大関数、責務が多すぎるクラス、同じ処理のコピペ、意味が説明されていない数値などです。

まず Claude Code に、修正ではなく棚卸しだけを依頼します。

claude -p "
src/ と tests/ を読んで、技術的負債の棚卸しをしてください。
まだファイルは変更しないでください。

観点:
- 80行を超える関数
- 300行を超えるファイル
- 4段以上のネスト
- 重複している入力検証、日付処理、権限チェック
- TypeScript の any、as any、@ts-ignore
- TODO / FIXME / HACK コメント
- テストがない分岐、または名前だけのテスト

出力は docs/tech-debt/register.md に貼れるMarkdown表にしてください。
列は ID, File, Line, Debt type, Evidence, Risk, Suggested first PR, Confidence としてください。
"

ポイントは「まだ変更しない」と明記することです。最初から直させると、根拠の薄い変更が混ざります。Claude Code には調査、分類、仮説出しを任せ、人間が優先順位を決めます。

ユースケース2：依存関係の負債を見つける

古いライブラリ、メンテナンス停止、重大な脆弱性、同じ用途のライブラリ併用も負債です。npm audit の件数だけで判断すると、実害の薄い警告に時間を使い、逆に EOL 直前の主要ライブラリを見逃します。

claude -p "
package.json, lockfile, npm outdated, npm audit の結果を前提に、依存関係の負債を分類してください。

分類:
1. セキュリティ修正が必要
2. major update が必要だが破壊的変更が大きい
3. メンテナンス停止または代替推奨
4. 同じ用途のライブラリ重複
5. 今は保留でよいもの

各項目について、影響範囲、先に読むべきchangelog、必要なテスト、最小PRの作り方を書いてください。
自動更新してよいものと、人間レビュー必須のものを分けてください。
"

依存関係更新は「通ったからOK」ではありません。日付処理、認証、暗号、ビルドツール、ルーティングは小さな API 差分が本番障害につながります。Claude Code には changelog の要約、影響ファイルの候補、テストコマンドの整理をさせます。

ユースケース3：flaky test と重複ロジックを返済候補にする

flaky test は CI への信頼を削ります。失敗しても「もう一度回せば通る」と思われた時点で、テストは安全装置ではなくなります。

Claude Code には、CIログやローカルの失敗履歴を渡して分類させます。

claude -p "
直近20件のCI失敗ログを読み、flaky test候補を分類してください。

分類軸:
- 時刻、タイムゾーン、ランダム値に依存
- ネットワークまたは外部APIに依存
- テスト間で共有状態が漏れている
- 非同期処理の待ち方が不安定
- 実装バグの可能性が高く、flaky扱いしてはいけない

各候補について、再現コマンド、最小修正案、追加すべきアサーションを書いてください。
"

重複ロジックも同じです。たとえば権限チェックが3箇所にコピペされているなら、最初のPRでは共通関数を作るだけにします。次のPRで1箇所ずつ置き換えます。すべてを一度に置き換えると、レビューアが「挙動が同じか」を追えません。

コピペで使える簡易スキャナ

Claude Code の調査と合わせて、機械的に拾える負債はスクリプトにします。次のファイルを scripts/debt-scan.mjs として保存し、node scripts/debt-scan.mjs src で実行できます。

import fs from "node:fs";
import path from "node:path";

const root = process.argv[2] || "src";
const maxLines = Number(process.env.MAX_LINES || 300);
const extensions = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
const findings = [];

function walk(dir) {
  if (!fs.existsSync(dir)) return;

  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const fullPath = path.join(dir, entry.name);

    if (entry.isDirectory()) {
      if ([".git", "node_modules", "dist", "build", ".next", "coverage"].includes(entry.name)) continue;
      walk(fullPath);
      continue;
    }

    if (entry.isFile() && extensions.has(path.extname(entry.name))) {
      scanFile(fullPath);
    }
  }
}

function add(file, line, type, severity, detail) {
  findings.push({ file, line, type, severity, detail });
}

function scanFile(file) {
  const text = fs.readFileSync(file, "utf8");
  const lines = text.split(/\r?\n/);

  if (lines.length > maxLines) {
    add(file, 1, "large-file", 3, `${lines.length} lines`);
  }

  lines.forEach((line, index) => {
    const lineNumber = index + 1;

    if (/\b(FIXME|TODO|HACK)\b/i.test(line)) {
      add(file, lineNumber, "unsafe-comment", /FIXME|HACK/i.test(line) ? 4 : 3, line.trim());
    }

    if (/\.(ts|tsx)$/.test(file) && /(:\s*any\b|as\s+any\b|<any>)/.test(line)) {
      add(file, lineNumber, "typescript-any", 4, line.trim());
    }
  });
}

walk(root);

console.log("| file | line | type | severity | detail |");
console.log("| --- | ---: | --- | ---: | --- |");
for (const item of findings.sort((a, b) => b.severity - a.severity || a.file.localeCompare(b.file))) {
  const detail = item.detail.replaceAll("|", "\\|");
  console.log(`| ${item.file} | ${item.line} | ${item.type} | ${item.severity} | ${detail} |`);
}

if (findings.length === 0) {
  console.error("No obvious debt markers found.");
}

このスクリプトは万能ではありません。重複ロジックや設計の歪みは完全には検出できません。それでも、TODO、FIXME、any、巨大ファイルのような「議論の入り口」を毎週同じ基準で集められます。

負債台帳テンプレート

棚卸し結果は、Issue ではなく一度台帳にまとめると優先順位を比べやすくなります。

# Technical Debt Register

| ID | Area | Evidence | User or team impact | ICE | RICE | Owner | Next PR | Status |
| --- | --- | --- | --- | ---: | ---: | --- | --- | --- |
| TD-001 | Auth permissions | src/auth/guard.ts duplicates role checks in 4 places | New role changes take 2 days and often miss one path | 420 | 1680 | Backend | Extract pure canAccess() with tests | Ready |
| TD-002 | Dependencies | vite is 2 major versions behind | Security patches and plugin updates are blocked | 280 | 900 | Platform | Upgrade in isolated branch and run build/test | Investigating |

## Scoring note

- ICE = Impact x Confidence x Ease
- RICE = Reach x Impact x Confidence / Effort
- Keep evidence links concrete: file path, line, CI run, or user-facing incident.

ICE は速く並べるための指標です。RICE は影響人数や工数を入れたい時に向きます。どちらも正解を出す計算式ではなく、会話をそろえるための道具です。スコアが高くても、テストがない領域なら「先に観測とテストを足す」が最初のPRになることがあります。

安全なリファクタ計画を作らせるプロンプト

返済対象が決まったら、Claude Code に実装前の計画を作らせます。

claude -p "
TD-001 を安全に返済する計画を作ってください。まだ編集しないでください。

対象:
- src/auth/guard.ts
- src/auth/roles.ts
- tests/auth/guard.test.ts

制約:
- 外部APIの挙動を変えない
- 既存テストを先に確認する
- テストが不足していれば、挙動固定テストを先に追加する
- PRは300行以内を目標にする
- リスク、ロールバック方法、レビュー観点を書く

出力:
1. 現状の挙動まとめ
2. 変更しないこと
3. 最初のPRの差分案
4. 実行するテストコマンド
5. レビュー依頼文
"

「変更しないこと」を書かせるのが重要です。Claude Code は改善案を広げられる反面、範囲の境界が曖昧だと親切心で余計な整理をします。PRごとの境界をプロンプトに入れておくと、レビューしやすい差分になります。

リファクタPRチェックリスト

## Refactor PR checklist

- [ ] This PR changes structure, not product behavior.
- [ ] Existing behavior is covered by tests before the refactor.
- [ ] New helper names describe domain behavior, not implementation detail.
- [ ] Public API, response shape, permissions, and logging are unchanged or explicitly documented.
- [ ] The diff is small enough to review in one sitting.
- [ ] Rollback is simple: revert this PR without reverting unrelated work.
- [ ] The debt register is updated with status and follow-up PRs.

このチェックリストは、Claude Code に PR 本文を作らせる時にも使えます。公式 Common workflows でも、リファクタ、テスト、PR作成は小さく検証しながら進める流れとして紹介されています。

具体的な落とし穴

1. 自動修正を信じすぎる Claude Code が提案した差分でも、型が通るだけでは安全とは言えません。特に認可、課金、日付、非同期処理、DBマイグレーションは、挙動固定テストと人間レビューを必須にします。

2. TODOを全部消そうとする TODO には「今すぐ危険な未実装」と「将来の改善メモ」が混ざります。TODO: remove before release、FIXME: bypass auth のような危険語を優先し、単なるメモは台帳に残すだけで十分です。

3. 依存関係更新をまとめすぎる 10個の major update を1PRに入れると、失敗時に原因を切り分けられません。ビルドツール、UI、認証、テストランナーは分けます。

4. スコアを政治に使う ICE/RICE は会話のための道具です。高いスコアを付けた人の勝ちにすると、誰も信用しません。証拠、影響、工数をセットで書きます。

5. チームの記憶を残さない 「このプロジェクトでは小さなPRにする」「権限まわりは必ず承認を取る」などのルールは CLAUDE.md や設定に残します。Claude Code の Memory と Settings を使うと、毎回プロンプトで説明する負担を減らせます。

チーム運用の型

おすすめは、週1回30分の負債レビューです。新しい負債を責める会ではなく、返済可能な最小PRを選ぶ会にします。

1. スキャナと Claude Code の棚卸し結果を見る
2. 上位10件だけ ICE/RICE を更新する
3. 次スプリントで1件だけ返済PRを作る
4. flaky test とセキュリティ依存は通常より高く扱う
5. 完了後、台帳に「何が楽になったか」を1行で残す

ClaudeCodeLab では、研修・テンプレート・相談メニューでこの運用をチームに合わせて整えています。負債台帳、PRチェックリスト、権限設定、CLAUDE.md の初期テンプレートをまとめて導入したい場合は Claude Codeトレーニング/テンプレート/相談 を確認してください。

まとめ

Claude Code で技術的負債を減らすコツは、「大きく直す」ではなく「証拠を集め、小さく返す」です。コードスメル、依存関係、flaky test、重複ロジック、危険な TODO を同じ台帳に置き、ICE/RICE で会話をそろえ、PRを300行程度に分ける。これだけで、負債返済は特別な大掃除から日常の開発作業に変わります。

この記事で紹介した内容を実際に試した結果、Masa の小規模プロジェクトでは、最初の棚卸しで「すぐ直すべき負債」と「今は記録だけでよい負債」が分かれました。特に any と古い TODO を小さなPRに分けたことで、レビュー時間を大きく増やさずに不安な箇所を減らせました。一方で、依存関係の major update は予想より検証が重く、Claude Code に任せきりにせず、テスト追加とリリース手順の確認を先に置く方が安全でした。