tech-debt

技術的負債

概要

このファイルのルーターが振り分ける、技術的負債に対する相補的な2つのアプローチです。

• モード A — 予防： 変更を加えている最中に、意図する最終状態に向けて作り直します。不要な互換性パスは残さず、削除します。
• モード B — トリアージ： 既存コードを評価している最中に、負債を分類、スコアリングし、優先順位を付けて、改善計画にまとめます。

両者は負債のライフサイクルにおける異なる段階で使います。コードを書くときは予防し、計画を立てるときはトリアージします。トリアージの結果は、1項目ずつ予防に反映されます。

使用する場面

次の場合はモード A を使用します。

• 機能、修正、リファクタリングの実装、仕上げ、レビューを行っていて、ユーザーが変更をきれいに仕上げたいと考えている。
• フォールバック、エイリアス、モードフラグ、ラッパーを「念のため」残そうとしている。まず呼び出し元があるか確認します。
• ユーザーが「きちんとやって」「その場しのぎは不要」「技術的負債はゼロにして」「散らかったままにしないで」と言っている。

次の場合はモード B を使用します。

• ユーザーが技術的負債の監査、コードの健全性レビュー、または「何をリファクタリングすべきか」を求めている。
• ユーザーが保守／リファクタリングのバックログやロードマップの優先順位付けを望んでいる。
• 負債が蓄積し、何から修正すべきか誰も判断できない。

使用しない場面：

• 構造的な観点のない、明らかで局所的な修正が1つだけある場合は、そのまま修正します。負債のフレームワークを使う必要はありません。
• スタイルやフォーマットの細かな問題は、ここではなくリンターやフォーマッターを案内します。
• 意図する最終状態が本当に不明なグリーンフィールドでは、モード A はまだ定義されていない状態を目標にできません。

このスキルの仕組み — ルーター

このスキルはルーターです。 このファイルは、薄いオーケストレーターのままにします。モードを1つだけ（または A→B→A の連鎖）選び、該当する references/*.md を読み込んで、その指示に従います。 具体的な手順、ルール、例は2つのリファレンスドキュメントに記載されています。

リファレンスドキュメントの本文をインラインで含めてはいけません。 分岐の説明が2～3行を超える場合は、references/ に記載します。どの分岐を選ぶかの判断は、ここに残します。

理由：ルーターを薄く保つことで内容をすばやく把握でき、モードが確定してから分岐の本文を読み込むことで、選択されなかった分岐にコンテキストを使わずに済みます。

振り分け

判断基準は、タスクのブール値プロパティ1つです。ユーザーは今、変更を加えているか（コードを書いている／編集している、差分がある）？ yes → モード A、no → モード B。連鎖のルール：トリアージした項目の実装に着手したら、その変更にはモード A に切り替えます。

digraph tech_debt_route {
  rankdir=TB;
  node [shape=box];

  start  [label="User task touches tech debt" shape=oval];
  q      [label="Actively making a change\n(writing/editing code, has a diff)?" shape=diamond];
  a      [label="MODE A — PREVENT\nRework THIS change to the\nintended end state"];
  b      [label="MODE B — TRIAGE\nCategorize + score the\nwhole codebase's debt"];
  loadA  [label="Load references/prevent-during-change.md"];
  loadB  [label="Load references/triage-backlog.md"];
  chain  [label="Implementing a triaged item?\nSwitch to Mode A for that change" shape=diamond];

  start -> q;
  q -> a [label="yes"];
  q -> b [label="no — assessing existing code"];
  a -> loadA;
  b -> loadB;
  loadB -> chain;
  chain -> loadA [label="yes, per item"];
}

振り分け表

ユーザーの状況	モード	読み込むもの
機能、修正、リファクタリングを実装／仕上げていて、変更をきれいにしたい	A	references/prevent-during-change.md
フォールバック／エイリアス／フラグを「念のため」残そうとしている	A	references/prevent-during-change.md
技術的負債の監査／「何をリファクタリングすべきか」／コードの健全性レビューを求めている	B	references/triage-backlog.md
保守またはリファクタリングのバックログの優先順位付けを求めている	B	references/triage-backlog.md
トリアージで挙がった項目を修正している	A（項目ごと）	references/prevent-during-change.md

モード A — 予防（変更中）

現在のパッチに至った経緯ではなく、意図する最終状態を起点に変更を作り直します。存在すべきコードを優先し、不要な互換性パスは改善するのではなく削除します。モードフラグを使うより、明確なコンポーネント／フローを1つにまとめることを優先します。

references/prevent-during-change.md を読み込み、その指示に従います。

モード B — トリアージ（バックログの監査）

コードベース全体にある既存の負債を体系的に特定、分類し、優先順位を付けます。工数の見積もりと、機能開発と並行して進められる段階的な改善計画を添えた、優先順位付きリストを作成します。

references/triage-backlog.md を読み込み、その指示に従います。

要点

コードを変更するときは新たな負債を予防し、何を修正するか計画するときは既存の負債をトリアージします。