필사 모드: 技術的負債 完全ガイド: 特定し、測り、返す

• はじめに
• 1. 比喩の本来の意味と誤用
  • 1-1. Fowler の四象限
  • 1-2. この区分が実務で果たす役割
  • 1-3. ここは意見が割れます
• 2. 負債でないもの
• 3. 負債の類型
  • 3-1. 外部の時計が付いた負債
  • 3-2. 運用負債は障害でしか請求されません
  • 3-3. 知識負債
• 4. どこにあるかを探す — 変更頻度と複雑度
  • 4-1. 悪いコードではなく高いコードを探します
  • 4-2. 計算時の落とし穴
  • 4-3. コードの外にある合図
  • 4-4. 静的解析の点数に意味はあるか — ここは意見が割れます
• 5. 利息を計算する方法
  • 5-1. 元本ではなく利息が本体です
  • 5-2. DORA 指標を利息の代理指標として使う
  • 5-3. 「負債を返すと遅くなる」というフレームが誤りである理由
  • 5-4. 測定時の注意
• 6. 負債リストを作って維持する
  • 6-1. リストが無ければ負債は感情の問題になります
  • 6-2. 維持の規則
  • 6-3. コードのコメントはリストではありません
• 7. 返済計画をロードマップへ組み込む方法
  • 7-1. ここは意見が割れます
  • 7-2. 返済もデプロイ可能な断片であるべきです
• 8. 返さないと決めることも決定です
  • 8-1. 返さなくてよい場合
  • 8-2. 無視と受容は違います
  • 8-3. 受容できないもの
• 9. 再び積み上がらないようにする装置
  • 9-1. 完了の定義に縮小フェーズを入れる
  • 9-2. レビューを基準線にする
  • 9-3. 自動化で締めるもの
  • 9-4. 設計文書で前段で止める
• クイズ: 理解度を確認しましょう
• おわりに
• 参考資料
• 関連記事

はじめに

このブログにはすでに 技術的負債をビジネスの言葉で があります。あの記事は 負債をステークホルダーにどう説明し、優先順位をどう交渉するか を扱います。つまり説得の記事です。

この記事はその手前の段階です。説得の対象になるには、まず 負債がどこにあるかを見つけ出し、そこに数字を付ける必要があります。根拠のない「コードが汚いです」は交渉の場で勝てません。したがってこの記事の主題は特定と測定、そしてリストを維持する手順です。

一文に縮めるとこうです。負債の存在を主張することと、負債の利息を見せることは別の行為であり、予算を動かすのは後者だけです。

1. 比喩の本来の意味と誤用

1-1. Fowler の四象限

Martin Fowler は技術的負債を二つの軸で分けます。意図的だったか偶発的だったか、そして無謀だったか慎重だったかです。

                    無謀 (reckless)              慎重 (prudent)
意図的        「設計する時間がない」        「今出荷して後で返す」
(deliberate)     代償を知らずに飛ばした         代償を理解して選んだ

偶発的        「レイヤ分離とは?」           「今ならどうすべきだったか分かる」
(inadvertent)    より良い方法を知らなかった     作ってみて初めて分かった

Fowler はとくに偶発的かつ慎重な象限を強調します。プロジェクトで 1 年ほどプログラミングして初めて、最良の設計アプローチが何だったかを理解する場合がある というのです。そしてこの比喩が意図的な二象限だけでなく、四つすべてに有効だというのが彼の要旨です。

1-2. この区分が実務で果たす役割

四象限は分類遊びではなく、処方が変わるから意味があります。

• 意図的・慎重: 返済の日程と条件をその場で一緒に決めます。決めなければ次の四半期には偶発的負債のように見えます。
• 意図的・無謀: プロセスの問題です。個人を責める代わりに、なぜその選択が可能だったのか、つまり締切とレビュー基準を見ます。
• 偶発的・無謀: 学習とレビューの問題です。同じ誤りが繰り返されるなら、足りないのは能力ではなくオンボーディングと指針です。
• 偶発的・慎重: 正常です。これを恥じるとチームは学んだことをコードに反映しなくなります。

1-3. ここは意見が割れます

「技術的負債」という比喩そのものが有用かについては本物の論争があります。反対側の主張は、この語が お粗末なエンジニアリングを金融用語で洗浄する というものです。負債という語は本来、意図的な選択と返済計画を前提にするのに、実務では何の計画もなく生まれた悪いコードにも同じ語が貼られるからです。賛成側は、この比喩が非技術のステークホルダーと会話できるほぼ唯一の共通言語だと見ます。

軸は三つです。実際に意図があったか、返済計画が文書として存在するか、そしてこの語が相手にどんな行動を促すかです。計画なしに使われれば反対側が正しく、計画とともに使われれば賛成側が正しくなります。

2. 負債でないもの

リストを作る前に除外が必要です。判別基準は一つです。将来の変更に追加コストを課すかどうかです。課さないなら負債ではありません。

• 好みの違い: 別のスタイルで書かれたコードは負債ではありません。スタイル論争をリストに入れるとリスト全体の信頼が落ちます。
• 古いが変わらないコード: 3 年間誰も触らず正常に動くモジュールの利息は 0 です。優先度も 0 です。
• まだ必要でない抽象の不在: 一般化しないことは負債ではなく判断です。三例目が現れる前の重複はたいてい正常です。
• バグ: 欠陥であって負債ではありません。欠陥は直すもので、負債は返すか返さないと決めるものです。
• 未完成の機能: それはバックログです。
• 意図的に単純に保った設計: 拡張性が無いことと、拡張性を諦めると決めたことは違います。

逆に、負債と認識されにくいのに負債であるものがあります。遅い CI、手作業のデプロイ前点検、ローカルで再現しない環境、新人が最初のコミットまで 2 週間かかる状態です。これらはコードに現れませんが、すべての変更に利息を課します。

3. 負債の類型

類型を分ける理由は 発見方法と返済方法が類型ごとに違うからです。

3-1. 外部の時計が付いた負債

多くの負債は返済時期を自分たちで決めますが、一部は外部が期限を決めます。この種の項目はリストで別に印を付けるべきです。

• セキュリティ仕様の変化: OAuth 2.0 のセキュリティ最良慣行である RFC 9700 は、リソースオーナーパスワードクレデンシャルグラントについて「使用してはならない (MUST NOT be used)」と定め、暗黙的グラントについては認可レスポンスでのアクセストークン注入が防止されない限り「使用すべきでない (SHOULD NOT)」と規定します。この種の項目は自分たちの日程ではなく監査や審査の日程に縛られます。
• 保存場所の問題: OWASP セッション管理チートシートは、認証トークン、セッション ID、JWT、リフレッシュトークンを localStorage や sessionStorage に保存しないよう求めます。これらの API は同一オリジンで実行されるすべての JavaScript から到達できるため、XSS 一つですべてのトークンが漏れるからです。選択肢の比較は JWT とセッション、いつどちらを にあります。

3-2. 運用負債は障害でしか請求されません

Google SRE Book は連鎖障害を「正のフィードバックの結果として時間とともに拡大する障害」と定義し、再試行は 常にランダム化した指数バックオフで予約するよう勧めます。再試行予算の例としてはプロセスあたり毎分 60 回を挙げます。さらに階層が重なると再試行が掛け算になり、三階層がそれぞれ 4 回再試行すればユーザーの一動作が 64 回の試行になると指摘します。

バックオフも予算もロードシェディングも無い状態は、平時には何のコストもありません。利息が障害の瞬間に一括で請求されるため、優先順位で後回しにされ続けます。この類型は利息を「発生確率 × 障害 1 回のコスト」として書かなければリストで生き残れません。

3-3. 知識負債

Design Docs at Google の記事は、設計文書も他のすべての文書と同様に 時間とともに現実とずれていく傾向があると書いています。対応は原本を更新するか、修正を追記するか、後続文書を結びつけることです。文書が古いという事実より危険なのは、古いかどうかを誰も把握していない状態です。

4. どこにあるかを探す — 変更頻度と複雑度

4-1. 悪いコードではなく高いコードを探します

負債探索で最もよくある誤りは 最も汚いファイルから探すことです。汚くても誰も触らないファイルの利息は 0 です。探すべきは、頻繁に変わり、かつ変えにくいコードです。

# 例 — バージョン管理履歴から変更頻度の高いファイルを抽出する
# 直近 12 か月、ファイル別コミット数の上位 30 件
git log --since='12 months ago' --name-only --pretty=format: \
  | grep -v '^$' | sort | uniq -c | sort -rn | head -30

# このリストを複雑度または行数と掛けてホットスポット点数を作る
# 点数 = 変更回数 x 複雑度指標
# 上位 10 件が今四半期の候補になる

4-2. 計算時の落とし穴

• 自動生成ファイルとロックファイル: コミット数は圧倒的でも人は読みません。まず除外します。
• 大量フォーマットのコミット: 一度のスタイル適用が全ファイルの変更回数を等しく押し上げます。該当コミットを除外します。
• ファイル名の変更: 履歴が途切れ、古いホットスポットが新しいファイルに見えます。
• サイズの偏り: 大きなファイルは単に頻繁に変わります。変更回数を行数で割った密度も併せて見ます。

4-3. コードの外にある合図

ホットスポット分析はコードの中しか見ません。次の合図はリストの候補をコードの外から教えてくれます。

• 同じファイルで繰り返す障害: 振り返り文書でファイル名を数えます。
• レビューで繰り返される指摘: 同じ指摘が三度出れば、それは個人ではなく構造の問題です。
• オンボーディングで繰り返される質問: 知識負債の最も正直な指標です。
• デプロイ前の手作業の数: 手順書で人が手で行う段階を数えます。
• 「そこは触らないでください」という言葉: この文が付くモジュールは例外なく候補です。

4-4. 静的解析の点数に意味はあるか — ここは意見が割れます

ツールが計算する負債点数や「返済に必要な時間」の推定を信じられるかは意見が割れます。有用だとする側は 傾向を見るには十分で、議論の出発点になると考えます。無意味だとする側は、その数字が規則違反の件数に任意の重みを掛けただけであり、最も高くつく設計結合と運用負債をまったく見られないと考えます。

軸は二つです。点数を絶対値として使うか傾向として使うか、そしてその点数が実際の変更コストと相関するかです。自分たちのリポジトリで点数と変更のリードタイムが一緒に動かないなら、その点数は自分たちにとって意味がありません。

5. 利息を計算する方法

5-1. 元本ではなく利息が本体です

負債項目に「直すのに 3 週間」とだけ書けばそれは元本です。元本だけでは優先順位を決められません。必要なのは 返さない間、毎月出ていくコスト、すなわち利息です。

[利息の推定 — 観測可能な量だけで書く]
利息(月) = (この負債のせいで一度の変更に余計にかかる時間)
         x (その領域の月あたり変更回数)
         + (この負債による月平均の障害時間 x 障害 1 時間のコスト)

例
- 決済モジュールの二重スキーマ: 変更ごと +4 時間、月 6 回 → 月 24 時間
- 不安定な E2E テスト: 再実行の待機 1.5 時間 x 週 5 回 → 月 30 時間
- 手作業のデプロイ点検: デプロイごと 40 分 x 月 20 回 → 月 13 時間

元本(返済見積り)は範囲で書く。例: 10〜15 人日
回収期間 = 元本 / 利息。上の決済モジュールなら約 4〜6 か月

5-2. DORA 指標を利息の代理指標として使う

チーム単位で利息を観測する最も手軽な方法はデプロイ指標です。DORA は変更のリードタイムを「変更がバージョン管理にコミットされてから本番にデプロイされるまでの時間」、変更失敗率を「デプロイ後に即時の介入を要したデプロイの割合」、失敗したデプロイの復旧時間を「即時の介入を要するデプロイ失敗から復旧するまでの時間」と定義します。手戻り率は本番障害によって発生した計画外デプロイの割合です。

負債が積もるとこれらの指標が先に動きます。とくに変更失敗率と復旧時間はテスト負債と運用負債に直接反応します。

5-3. 「負債を返すと遅くなる」というフレームが誤りである理由

DORA は研究の結果、速度と安定性がトレードオフではなく、多くのチームでは両指標がむしろ相関すると報告しています。DORA の表現どおり、長期的に見た本当のトレードオフは 「より良いソフトウェアをより速く」と「より悪いソフトウェアをより遅く」の間にあります。

この結果は負債の議論でよく使われる「品質か速度かを選べ」というフレームを直接反駁します。交渉の場で使える最も強い根拠でもあります。詳しい説得方法は 技術的負債をビジネスの言葉で にあります。

5-4. 測定時の注意

• 絶対値より傾向を見ます。他チームや他リポジトリとの比較はほぼ常に誤った結論へ向かいます。
• 指標を個人評価に使いません。使った瞬間に記録が歪みます。
• 利息の推定は観測値だけで埋めます。根拠のない数字が一つ混じるとリスト全体の信頼が崩れます。
• 回収期間がチームの計画地平より長ければ、その項目は今返す項目ではありません。

6. 負債リストを作って維持する

6-1. リストが無ければ負債は感情の問題になります

リストの目的は記録ではなく 比較です。項目同士を比較できて初めて、優先順位が論争ではなく計算になります。

# 例 — 負債項目一つの最小フィールド
id: DEBT-114
title: 注文テーブルの通貨列に二重書き込みが残存
type: data # code | design | test | dependency | data | ops | knowledge
location: services/order/**
quadrant: deliberate-prudent # Fowler の四象限
symptom: 注文関連の変更のたびに両方の列を直す必要、ロールバック時に不整合の危険
interest: 変更ごと +4 時間、月 6 回 → 月 24 時間 # 観測値
principal: 10-15 人日 # 見積り、範囲で
payoff: 縮小フェーズの実行 (読みの移行完了を確認して旧列を削除)
risk_if_unpaid: スキーマ変更が不可逆になりロールバック不能
external_clock: none # あれば日付を書く
owner: order-team
review_by: 2026-11-01 # 再評価の時点

6-2. 維持の規則

• 項目数に上限を置きます。200 件のリストはリストではなく倉庫です。上限を超えたら利息の低い項目から閉じます。
• 定期再評価の時点をフィールドにします。その日付に利息を再観測できなければ項目を閉じます。
• 観測値の無い項目は候補に留めます。「感覚的に問題」と「月 24 時間」が同じリストにあってはいけません。
• 閉じた項目の履歴を残します。返さないと決めた理由が次の議論の出発点になります。

6-3. コードのコメントはリストではありません

コード内の TODO や FIXME は見つけやすい利点がありますが、優先順位も所有者も期限もありません。実務上の折衷は二つを結ぶことです。コメントにはリスト項目の識別子だけを残し、利息と計画はリストに置きます。こうすればコードから項目へ辿れますし、項目が閉じればコメントも一緒に消えます。

7. 返済計画をロードマップへ組み込む方法

[四つの組み込み方 — 前提と失敗モード]

1. 固定比率      毎スプリントの容量の N% を負債に割り当てる
   前提: 負債が複数領域に分散している
   失敗: 比率が「余った時間」と解釈されると常に 0 になる

2. 専用期間      四半期ごとに 1〜2 週間を負債だけに使う
   前提: 負債が一領域に集中し、大きな塊になっている
   失敗: 期間が終われば元の速度に戻り、根本原因はそのまま

3. 機能に束ねる  その機能が通る経路の負債だけを一緒に返す
   前提: 負債とロードマップの領域が重なる
   失敗: どの機能も通らない領域の負債は永遠に残る

4. ゲート化      特定の負債の返済を新機能の前提条件にする
   前提: その負債が次の作業を実際に塞いでいる
   失敗: 濫用するとすべての機能が人質になり信頼を失う

7-1. ここは意見が割れます

専用の負債スプリントと固定比率のどちらが良いかは決着していません。専用期間を支持する側は、大きな構造変更が細切れの時間では不可能だと考えます。固定比率を支持する側は、専用期間が 負債を「特別なイベント」にしてしまい、普段はやらなくてよいことだと認識させる と見ます。

軸は三つです。負債が集中しているか分散しているか、組織の計画周期がどれほど硬直しているか、そしてチームが自律的に時間を使える信頼があるかです。実務では分散した負債に固定比率を、集中した大きな塊に専用期間を当てる混合がよく観察されます。この組み合わせの推奨は上記資料ではなくこの記事の整理です。

7-2. 返済もデプロイ可能な断片であるべきです

負債の返済はたいていリファクタリングの形を取ります。したがって リファクタリング完全ガイド の規則がそのまま当てはまります。どの時点で止めてもデプロイ可能であること、インターフェース変更は拡張・移行・縮小に分けること、大きな返済は戻せる断片に切ることです。3 週間の負債返済ブランチは、負債を返す代わりに新しい負債を作ります。

システム規模の返済が必要なら Strangler Fig パターン完全ガイド がその構造を扱い、投資判断そのものは リファクタリングの経済学 にあります。

8. 返さないと決めることも決定です

8-1. 返さなくてよい場合

• 利息が観測されない項目: 6 か月間その領域の変更が 0 だったなら利息は 0 です。
• まもなく廃止されるコード: 廃止日程が確定していれば返済は無駄です。ただし「まもなく」が 2 年目に入っていないか確認が要ります。
• 回収期間が計画地平より長い項目: 回収に 3 年かかるのにサービス寿命が 1 年なら、返さないのが正しいです。
• 返済自体のリスクが利息を上回る項目: 安全網の無い領域での大規模リファクタリングがここに当たります。

8-2. 無視と受容は違います

無視は記録が無いことで、受容は 誰が、いつ、どんな根拠で、いつまで返さないと決めたかが書かれていることです。受容した項目はリストから削除せず状態だけ変えます。再評価日が来たら利息を再観測し、利息が増えていれば再び開きます。

8-3. 受容できないもの

外部の時計が付いた項目は受容の対象ではありません。サポートが終了したランタイム、規定で禁止された認証方式、すでに公開された脆弱性は、自分たちの判断で先送りできる項目ではありません。3-1 節で見た仕様の項目がここに当たります。この区別をリストのフィールドにしておけば議論が短くなります。

9. 再び積み上がらないようにする装置

9-1. 完了の定義に縮小フェーズを入れる

技術的負債が再び積み上がる最もよくある経路は 拡張と移行だけ行い縮小をしないことです。インターフェースを並行に広げたまま旧経路を取り除かなければ、その瞬間から利息が付き始めます。完了の定義に「旧経路の削除チケットが作られ、期限がある」を入れるのが最も安価な防御です。

9-2. レビューを基準線にする

Google のコードレビュー基準は、レビュアーが変更が完璧でなくとも 対象システムの全体的なコードの健全性を確実に改善する状態なら承認する側を選ぶべきだとまとめます。この基準をそのまま使えば、レビューが負債の流入を止める関門になります。同じ文書は必須でない仕上げの提案に「Nit: 」を付けることを勧め、レビュー要請への応答にかかってよい最大時間を営業日一日と定めます。

レビュー速度が重要な理由は別にあります。同じ資料は、遅いレビューが コードの整理やリファクタリング、既存の変更へのさらなる改善を萎縮させると書いています。つまりレビューが遅い組織では負債の返済が構造的に起こりません。

9-3. 自動化で締めるもの

- リント例外リスト: 件数が増えたらビルド失敗。減ることだけを許す
- 非推奨警告: 日付を決めて警告をエラーに昇格させる予定を先にコミットする
- 依存の更新: 自動 PR を有効にし、滞留件数をダッシュボードに出す
- フラグの期限: 期限を過ぎた機能フラグは CI で失敗として扱う
- カバレッジ下限: 全体の数値ではなく「変更されたファイル」のカバレッジに掛ける
- 手作業のデプロイ手順: 手順書の手作業の数を指標として追跡する

9-4. 設計文書で前段で止める

Design Docs at Google の記事は設計文書を、コーディング前に書く非公式の文書と定義し、高水準の実装戦略と主要な設計判断をトレードオフに力点を置いて収めるものだと説明します。そして解法が自明で意味のあるトレードオフが無いなら文書は飛ばせと言います。トレードオフ分析の無い、事実上の実装マニュアルになった文書は、そのままコーディングを始めよという合図だというのです。

この基準は負債予防にそのまま使えます。戻しにくい判断にだけ文書を要求すれば、文書に費やすコストの地点と、後で最も高くつく負債が生まれる地点が一致します。

クイズ: 理解度を確認しましょう

おわりに

技術的負債で最も難しいのは直すことではありません。どこにあるかを見つけ出し、そこに比較可能な数字を付け、その数字を更新し続けることです。この作業ができていれば返済の決定はおおむね簡単で、できていなければどんな説得技法も長続きしません。

手順を一行に縮めるとこうです。負債でないものを除外し、頻繁に変わり変えにくい場所を探し、利息を観測値で書き、リストで比較し、返済をデプロイ可能な断片に切り、返さないと決めたものは根拠と再評価日とともに記録します。そして縮小フェーズを完了の定義に入れ、再び積み上がらないようにします。

参考資料

• Technical Debt Quadrant — Martin Fowler — 意図的/偶発的と無謀/慎重の二軸、四象限の性格、プロジェクトで 1 年ほど経って初めて最良の設計が分かるという記述、そして比喩が四象限すべてに有効という要旨を引用しました。2026-08-15 確認。
• DORA metrics: the four keys — DORA — 変更のリードタイム、変更失敗率、失敗したデプロイの復旧時間、手戻り率の定義と、「速度と安定性はトレードオフではない」という結論を引用しました。2026-08-15 確認。
• Addressing Cascading Failures — Google SRE Book — 連鎖障害の定義、ランダム化した指数バックオフの推奨、毎分 60 回の再試行予算の例、三階層 4 回の再試行が 64 回になる計算を引用しました。2026-08-15 確認。
• Design Docs at Google — Industrial Empathy — 設計文書の定義とトレードオフ中心という性格、自明な解法では文書を飛ばせという助言、そして文書が時間とともに現実とずれるという記述を引用しました。2026-08-15 確認。
• Code Review Developer Guide — Google — 全体的なコードの健全性を確実に改善するなら完璧でなくとも承認するという基準と「Nit: 」の慣行を、そして レビュー速度の文書 から遅いレビューが整理とリファクタリングを萎縮させるという記述と営業日一日の基準を引用しました。2026-08-15 確認。
• RFC 9700 — OAuth 2.0 Security Best Current Practice — リソースオーナーパスワードクレデンシャルグラントを使用してはならないという規定と、暗黙的グラントへの勧告を引用しました。2026-08-15 確認。
• OWASP Session Management Cheat Sheet — 認証トークンとセッション識別子をブラウザのストレージに置かないという勧告とその理由を引用しました。2026-08-15 確認。
• 2 節の負債の判別基準、3 節の類型表、4 節のホットスポット計算と落とし穴、5 節の利息推定式、6 節の項目テンプレートと維持規則、7 節の四つの組み込み方、8 節の受容基準、9 節の自動化一覧は、上記資料ではなくこの記事で整理した手順です。

関連記事

• このブログの関連記事: 技術的負債をビジネスの言葉で
• このブログの関連記事: リファクタリングの経済学、いつコストが回収されるか
• このブログの関連記事: SLI/SLO/エラーバジェットに基づく信頼性エンジニアリング
• このブログの関連記事: Strangler Fig パターン完全ガイド
• このブログの関連記事: JWT とセッション、いつどちらを
• 関連ツール: SLO エラーバジェット計算ツール

完全ガイドシリーズ

• 前の記事: リファクタリング完全ガイド: 振る舞いを保ったまま構造を変える手順