結論：技術的負債は「一気に作り直す」のではなく、テストで守りながら「毎日少しずつ」返すのが最も安全で確実です。Claude Code を使えば、負債の棚卸し・優先順位づけ・小さな安全な修正・依存更新までを、人のレビューを前提に半自動化できます。
- 要点1：まず「棚卸し」。重複・複雑な関数・テスト不足・古い依存・命名の乱れを洗い出し、勝手に直さず一覧化する。
- 要点2：「リスク×変更頻度×返済コスト」で優先順位をつけ、上位から1件ずつ手を付ける。
- 要点3：テストがないコードはまずテストから。小さく直し、テストと人のレビューで安全を担保し、一度に大きく変えない。
対象読者：動いてはいるが負債が溜まったコードを抱える開発者・チームリード。今日やること：後述の「棚卸しプロンプト」を1つ実行し、負債を1ページの一覧にするところまで。
「動いてるんだから触らないでくれ」——そう言いたくなるコードベース、ありますよね。正直、僕も受託開発で何度も向き合ってきました。テストがほとんどなくて、同じようなロジックが3箇所にコピペされていて、関数名は doProcess2_final みたいになっている。動くけど、機能追加のたびに別の場所が壊れる。これがまさに技術的負債です。
技術的負債（technical debt）という言葉は、Ward Cunningham が提唱し、Martin Fowler が整理した概念です。「とりあえず動かす」ために取った近道は、利子（＝後から払う追加コスト）がついて回る、という比喩ですね。問題は、この利子が複利で効いてくること。放置するほど、1つの変更にかかる時間も、壊すリスクも増えていきます。
この記事では、Claude Code を使って技術的負債を「漸進的に」返済する実践手順を、プロンプトとコード例付きで解説します。レガシーコードを丸ごと別言語・別フレームワークに移行する大規模リファクタは別記事（Claude Codeでレガシーコード移行・大規模リファクタ）で扱っているので、こちらは「動いている既存コードを、日々少しずつ綺麗にしていく」アプローチに絞ります。なお本記事の Claude Code の機能・コマンドは2026年6月時点の公式ドキュメントを基準にしています。
技術的負債とは何か — 「悪いコード」とは限らない
最初に誤解を解いておきます。技術的負債＝「下手なコード」ではありません。Martin Fowler は負債を「無謀 / 慎重」「意図的 / 不注意」の4象限で整理しました（参考：Technical Debt Quadrant）。たとえば「納期のために、後でリファクタする前提でショートカットを取る」のは慎重かつ意図的な負債で、これは戦略として正しいこともあります。問題になるのは、それを返済しないまま放置することです。
現場でよく見る負債の正体は、だいたい次の5種類に分けられます。これがそのまま「棚卸しの対象」になります。
- 重複（Duplication）：同じロジックがコピペで複数箇所に。1箇所直すと他を直し忘れる。
- 複雑な関数：1関数が200行、ネストが深い、責務が多すぎる。読むのに時間がかかる。
- テスト不足：変更の安全網がない。直すのが怖くて誰も触らなくなる。
- 古い依存：ライブラリ・ランタイムが数年前で止まっている。脆弱性・互換性のリスク。
- 命名の乱れ：
data2tmpFlaghandleStuffなど、意図が読み取れない。
ポイントは、これらを「気づいたら全部直す」のではなく、一覧化して優先順位をつけてから手を付けること。次の章から、Claude Code を使って順番にやっていきます。
ステップ1：負債の棚卸し — まず「直さず洗い出す」
負債返済で最初にやるべきは、修正ではなく可視化です。いきなり「リファクタして」と頼むと、Claude Code は親切に色々直そうとしてしまい、レビューしきれない巨大な差分が出てきます。まずは「直さずに、負債のリストだけ作って」と明示的に指示するのがコツです。
Claude Code はプロジェクト全体を読んで横断的に分析できるので、棚卸しはまさに得意分野です。次のプロンプトを使います。
このリポジトリの技術的負債を「修正せずに」棚卸ししてください。
コードは一切変更しないこと。以下の5カテゴリで一覧表にまとめてください。
1. 重複コード（同じロジックが複数箇所にあるもの。ファイルと行を明記）
2. 複雑な関数（行数が多い・ネストが深い・責務過多のもの）
3. テスト不足（重要なのにテストが無い／薄いモジュール）
4. 古い依存（package.json 等を見て、メジャー更新が止まっているもの）
5. 命名の乱れ（意図が読み取れない変数・関数名）
各項目に「ファイルパス」「概要」「想定される影響」を付けてください。
この時点では優先順位はつけず、事実だけを列挙してください。「修正せずに」「コードは一切変更しないこと」を必ず入れてください。これがないと、棚卸しのつもりが勝手に修正へ進むことがあります。安全のため、棚卸し作業はリポジトリを git status がクリーンな状態で始めるのがおすすめです。
重複の機械的な検出と組み合わせると精度が上がります。たとえば JavaScript/TypeScript なら jscpd のような重複検出ツールの結果を Claude Code に渡して、「この重複レポートのうち、本当に共通化すべきものはどれか優先度をつけて」と相談する流れが効きます。
# 重複検出ツールの例（jscpd）。結果を Claude Code に読ませて相談する
npx jscpd ./src --reporters json --output ./reports
# その後 Claude Code に依頼
# 「./reports/jscpd-report.json を読んで、共通化の価値が高い重複を上位5件だけ挙げて」棚卸しのアウトプットは、CLAUDE.md やリポジトリ内の docs/tech-debt.md のような形でコミットしておくと、チームで共有でき、次の優先順位づけにそのまま使えます。
ステップ2：返済の優先順位づけ — リスク×頻度×コスト
棚卸しで負債リストができたら、次は「どれから返すか」です。全部やろうとすると挫折します。僕がいつも使う判断軸は3つ。
- リスク：そこが壊れたときの被害の大きさ（課金・認証・データ整合性まわりは高リスク）。
- 変更頻度：そのファイルが最近どれだけ触られているか。よく触る場所ほど負債の利子が高い。
- 返済コスト：直すのにかかる手間。テストがあれば安く、なければ高い。
変更頻度は感覚ではなく、Git の履歴から客観的に出せます。「よく変わるのに複雑」なファイルは、負債返済の費用対効果が最も高いホットスポットです。
# 直近1年で変更回数が多いファイルTOP20を出す
git log --since="1 year ago" --name-only --pretty=format: \
| grep -v '^$' | sort | uniq -c | sort -rn | head -20このリストと棚卸し結果を Claude Code に渡して、優先順位を相談します。
docs/tech-debt.md（棚卸し結果）と、以下の「変更頻度が高いファイル一覧」を突き合わせてください。
【変更頻度TOP20】
（git log の出力を貼る）
各負債項目に「リスク（高/中/低）」「変更頻度（高/中/低）」「返済コスト（高/中/低）」を付け、
"変更頻度が高く・リスクが高く・コストが低い" ものから順に並べた返済ロードマップを提案してください。
今週着手すべきトップ3も挙げてください。コードはまだ変更しないこと。ここで出てくる「今週のトップ3」を返済対象にします。注意点として、AI が出した優先順位を鵜呑みにせず、ドメイン知識のある人が最終判断してください。Claude Code はコードは読めますが、「この機能はもうすぐ廃止予定」といった事業文脈までは知りません。
ステップ3：テストで守りながら、小さく安全に直す
ここからが返済の本番です。鉄則は1つ、テストがないコードは、まずテストを書いてから直す。これはレガシーコード改善の古典『レガシーコード改善ガイド』でも繰り返し語られる原則で、AI 時代でもまったく変わりません。むしろ AI が変更するからこそ、振る舞いを固定する安全網が必須です。
手順はこうです。
- 対象コードの現在の振る舞いを固定する「特性テスト（characterization test）」を書く（今のバグも含めて、現状の挙動をそのまま記録する）。
- テストが緑（パス）であることを確認する。
- 振る舞いを変えずに、内部だけをリファクタする（重複の共通化・関数分割・命名修正）。
- テストが緑のままであることを再確認する。
- 人がコードレビューしてからマージする。
まず特性テストを Claude Code に書いてもらいます。
src/billing/calculate.js の calculateInvoice 関数について、
「現在の振る舞いを固定する特性テスト」を書いてください。
- リファクタ前の安全網が目的です。今の挙動を変えないこと。
- 正常系・境界値・例外系を網羅し、現時点の出力を期待値として記録してください。
- 既存のテストフレームワーク（jest）に合わせてください。
このステップでは本体コードは変更しないでください。テストが緑になったら、いよいよリファクタ。1コミット＝1つの小さな変更に絞るのが安全のコツです。
calculateInvoice の特性テストが緑であることを前提に、リファクタしてください。
- 振る舞いは一切変えないこと（テストは緑のまま）。
- 今回は「重複している税計算ロジックの共通化」だけに絞ること。
- 変更は最小限に。複数の改善を1度に詰め込まないこと。
- 変更後、なぜその変更が安全かを1〜2文で説明してください。「今回は◯◯だけに絞る」という制約が重要です。これがないと、命名修正・分割・共通化を全部一気にやってしまい、差分が膨らんでレビューできなくなります。負債返済は「小さく・頻繁に・確実に」が勝ち筋です。
失敗パターン：よくある事故と回避策
- ❌ テストがないまま「とりあえずリファクタして」と丸投げ → ⭕ 先に特性テストを書き、緑を確認してから着手する。
- ❌ 1つのPRで命名・分割・共通化・依存更新を全部やる → ⭕ 1PR＝1種類の負債に絞り、差分を小さく保つ。
- ❌ AI の差分を読まずにそのままマージ → ⭕ 必ず人がレビュー。AI は意図しない振る舞い変更を混ぜることがある。
- ❌ 「動いてるから」と最高リスク箇所（課金・認証）を最初に触る → ⭕ 練習として低リスク・高頻度の場所から始め、手順を固めてから核心へ。
ステップ4：依存関係の更新と影響確認
古い依存は、放置するほど一気更新が怖くなる典型的な負債です。これも「少しずつ」が原則。メジャーバージョンを2つ3つ飛ばして一気に上げると、何が原因で壊れたか切り分けられなくなります。
まず現状把握。多くのエコシステムに「古い・脆弱な依存」を出すコマンドがあります。
# npm の例
npm outdated # 更新可能なパッケージ一覧
npm audit # 既知の脆弱性
# その結果を Claude Code に渡して相談
# 「npm outdated と npm audit の結果から、優先して上げるべき依存を
# "脆弱性あり > メジャー差大 > よく使う" の順で並べて」更新は1パッケージずつ、テストを回しながら進めます。Claude Code には、移行ガイドの読み解きと breaking change の影響箇所特定を任せられます。
パッケージ「○○」を v3 から v4 に上げたいです。
1. v4 の公式 CHANGELOG / マイグレーションガイドの breaking change を要約してください。
2. このリポジトリ内で、その breaking change の影響を受ける箇所を列挙してください。
3. 必要な修正を提案してください（ただしコードはまだ変更しないこと）。
4. 更新後に確認すべきテスト・動作項目のチェックリストを作ってください。影響箇所を把握してから、実際の更新→テスト→人のレビューに進みます。ここでも一度に大きく変えないこと。CI でテストが回る状態を保ちながら、依存を1つずつ緑にしていくのが、結局いちばん早くて安全です。脆弱性対応は特に、後回しにすると負債というより事故の火種になるので、棚卸しの優先度を一段上げて扱うのがおすすめです。
ステップ5：負債を増やさない仕組みをつくる
返済だけしていても、入ってくる負債のほうが多ければ残高は減りません。最後は「これ以上ためない仕組み化」です。ここを Claude Code の運用設定に組み込むと、チーム全体で効いてきます。
① CLAUDE.md にプロジェクトの規約を書く。Claude Code はリポジトリ直下の CLAUDE.md を自動で読み込み、毎回のコンテキストにします（参考：公式の memory ドキュメント）。命名規則・テスト方針・「新規コードには必ずテストを」といったルールを書いておくと、AI が生成するコードの負債が最初から減ります。
# CLAUDE.md（抜粋）
## コーディング規約
- 新しい関数には必ずテストを書く（テストなしのコードはマージしない）
- 関数は50行以内を目安に。超えるなら分割を検討する
- 変数・関数名は意図が伝わる英語にする（data2 / tmp などNG）
- 同じロジックを2箇所に書きそうになったら共通化を提案すること
## リファクタの進め方
- 1PR＝1種類の改善に絞る（命名・分割・共通化を混ぜない）
- 振る舞いを変える変更と、変えない変更を同じPRにしない② レビューを習慣化する。負債返済のPRも新機能のPRも、AI が書いたものは必ず人が読む。Claude Code 自身にレビューさせるのも有効で、「このPRに、テスト漏れ・命名の乱れ・重複が混ざっていないか負債観点でレビューして」と頼めば、人間レビューの前さばきになります。
③ 継続の仕組みにする。「金曜の午後30分は負債返済タイム」のように時間を固定したり、スプリントごとに docs/tech-debt.md から1〜2件返済する、とルール化すると残高が着実に減ります。一気に返そうとせず、複利を逆回転させるイメージです。
仕組み化まわりの詳しい設定や、Claude Code を実務で使い倒すテクニック全般は、Claude Code実践テクニック完全ガイドにまとめています。テストや品質保証を自動化に寄せたい場合は、Claude CodeでQA・テスト自動化を加速する実践ガイドも合わせてどうぞ。大きなコードベースをそもそも把握しきれていない場合は、大規模コードベースの理解・オンボーディングガイドから入ると、負債の棚卸しもやりやすくなります。
まとめ：負債返済は「小さく・確実に・続ける」
技術的負債の返済は、ヒーロー的な大リファクタではなく、地味な積み重ねで決まります。改めて流れを整理すると——棚卸しで可視化し、リスク×頻度×コストで優先順位をつけ、テストで守りながら1件ずつ小さく直し、依存も1つずつ上げ、CLAUDE.md とレビューで増やさない。この5ステップを回し続けるだけです。
Claude Code は、棚卸し・影響調査・テスト生成・リファクタ提案という「人間がやると時間のかかる部分」を肩代わりしてくれます。ただし最終的な安全は、テストと人のレビューが担保するもの。AI に直させて、テストで守って、人が確認する。この三点セットを崩さなければ、怖がっていたあのコードベースも、少しずつ確実に綺麗になっていきます。
まずは今日、この記事の「棚卸しプロンプト」を1つ実行して、自分のリポジトリの負債を一覧にしてみてください。可視化した瞬間、「思っていたより返せそう」と感じるはずです。
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援を手がける。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載を7回執筆。Claude Code を使った受託開発・チーム導入支援の現場知見を発信中。
