tech-debt

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow

技術的負債

すべての AskUserQuestion 呼び出しは .claude/docs/automation-modes.md に従います （協調型では常に質問し、ガイド付きでは主要な項目のみ質問し、自律型では記録して続行します。 automation_always_ask カテゴリでは常に質問します）。

フェーズ 1：サブコマンドを解析する

引数からモードを判定します。

• scan — コードベースをスキャンして技術的負債の兆候を探します
• add — 技術的負債の項目を手動で追加します
• prioritize — 既存の負債レジスターの優先順位を見直します
• report — 現在の負債状況の概要レポートを作成します

サブコマンドが指定されていない場合は、使用方法を出力して終了します。判定：FAIL — 必須のサブコマンドがありません。

---

フェーズ 2A：スキャンモード

コードルート（.claude/docs/code-root-resolution.md に従って解決します。 エンジンに応じて src/、Assets/、または Source/）を検索し、負債の兆候を探します。

• TODO コメント（数を数え、分類する）
• FIXME コメント（負債を装ったバグです）
• HACK コメント（適切な解決策が必要な回避策です）
• @deprecated マーカー
• 重複コードブロック（複数のファイルにある類似パターン）
• 500 行を超えるファイル（ゴッドオブジェクトの可能性）
• 50 行を超える関数（複雑性が高い可能性）

各検出項目を分類します。

• アーキテクチャ上の負債：不適切な抽象化、パターンの欠如、結合の問題
• コード品質の負債：重複、複雑性、命名、型の欠如
• テストの負債：テストの欠如、不安定なテスト、未テストのエッジケース
• ドキュメントの負債：ドキュメントの欠如、古いドキュメント、文書化されていない API
• 依存関係の負債：古いパッケージ、非推奨の API、バージョンの競合
• パフォーマンスの負債：既知の低速処理、最適化されていないクエリ、メモリーの問題

何かを提示する前に、スキャン対象が存在することを確認してください。 スキャンで実際に対象としたソースファイルの数を数えます。コードルートを解決できない場合は、 NOT ASSESSED — code root unresolved と報告し、以下に従って終了します。 その数が ゼロ の場合（コードルートが存在しない、またはソースファイルを含まない場合）は、次のように報告します。

NOT ASSESSED — no source files to scan. コードルートにコードがないため、 「負債の兆候は見つかりませんでした」という記述はコードベースについてではなく、 空の検索についてのものになります。実装が進んでから、もう一度実行してください。

その後、終了します。レジスターには書き込まず、COMPLETE 判定も出力しないでください。

この区別こそがスキャンの要点です。400 ファイルを対象に検出項目がゼロなら 健全なコードベースですが、ファイルがゼロで検出項目もゼロなら情報は何もありません。 どちらも「COMPLETE — scan findings written to register」と表示すると、 前者の意味に受け取られます。検出項目を報告する場合は、数が多く、 実際にゼロだった場合も含め、必ず分母を示してください。

検出項目をユーザーに提示します。

「これらの検出項目を docs/tech-debt-register.md に書き込んでもよいですか？」と尋ねます。

承認された場合は、既存の内容を上書きせずにレジスターを更新します。追加前に照合します。 既存の Open 項目と同じファイルで、同じ種類の負債を示す検出項目がある場合は、 重複して追加せず、既存の項目を更新します。ファイル内に該当パターンがなくなった既存の Open 項目は、 Resolved [date] として提案します。それらを列挙し、同じ承認の対象に含めます。 判定：COMPLETE — スキャン結果をレジスターに書き込みました。

承認されなかった場合は、ここで終了します。判定：BLOCKED — ユーザーが書き込みを拒否しました。

---

フェーズ 2B：追加モード

ユーザーに説明と該当ファイルを尋ねます（プレーンテキストのプロンプト）。

サブエージェントとして実行しますか？ lead-programmer はこのスキルを事前に読み込みますが、サブエージェントには AskUserQuestion がありません。以下の3つの質問（カテゴリ、作業量、影響）を、それぞれ選択肢を短いリストにして1回の返信で返し、そこで終了します。呼び出し元がユーザーに尋ねます。回答が戻るまで、レジスターには何も追加しません。

次に、AskUserQuestion を使ってカテゴリを尋ねます：

• プロンプト：「この技術的負債はどのカテゴリに該当しますか？」
• 選択肢：
  • [A] Architecture Debt — 誤った抽象化、欠落しているパターン、結合の問題
  • [B] Code Quality Debt — 重複、複雑さ、命名、型の不足
  • [C] Test Debt — テスト不足、不安定なテスト、未テストのエッジケース
  • [D] Documentation Debt — ドキュメントの不足・古さ、文書化されていない API
  • [E] Dependency Debt — 古いパッケージ、非推奨 API、バージョンの競合
  • [F] Performance Debt — 既知の低速処理、メモリの問題、最適化されていないクエリ

次に、AskUserQuestion を使って修正に必要な推定作業量を尋ねます：

• プロンプト：「この項目の修正に必要な作業量の見積もりはどのくらいですか？」
• 選択肢：
  • [A] S — 小（1日未満）
  • [B] M — 中（1〜3日）
  • [C] L — 大（3〜7日）
  • [D] XL — 特大（1週間超）

次に、AskUserQuestion を使って未修正のままにした場合の影響（/tech-debt prioritize がスコアを付けるレジスターの Impact 列）を尋ねます：

• プロンプト：「この項目を修正しないままにした場合、どのような損失がありますか？」
• 選択肢：[A] Low / [B] Med / [C] High / [D] Critical

追加する新しい項目をすべてユーザーに提示します。

追加前に一致を確認： 同じファイルと同じカテゴリを持つ既存の Open 項目がある場合は、その項目をユーザーに提示し、新しい項目を重複して追加する代わりに既存項目を更新するか尋ねます。

次のように尋ねます：「この項目を docs/tech-debt-register.md に追加してもよろしいですか？」（一致する項目がある場合は、「代わりに既存の項目を更新してもよろしいですか？」）

はいの場合、項目を追加（または一致した項目を更新）します。判定：完了 — 項目をレジスターに追加しました。

いいえの場合、ここで終了します。判定：ブロック — ユーザーが書き込みを拒否しました。

---

フェーズ 2C：優先順位付けモード

docs/tech-debt-register.md の負債レジスターを読み込みます。存在しない場合： 判定：未評価 — docs/tech-debt-register.md にレジスターがありません。先に /tech-debt scan を実行してください。終了します。

各項目について、各項目自身の列を使ってスコアを計算します：impact ÷ effort。Impact は Low が 1、 Med が 2、High が 3、Critical が 4、Effort は S が 1、M が 2、L が 3、XL が 4 とし、小数第1位に丸めて Priority に記入します。スコアの高い順に並べます。同点の場合は、Added の日付が古い項目を先にします。Impact または Effort が — の項目にはスコアを付けません。推測で値を補うのではなく、スコア付きの項目の後に「スコアなし — [column] 未評価」として記載します。

レジスターを優先順位スコア順に並べ替え、次のスプリントに含める項目（スプリントのない workflow: minimal では、次に着手する項目）を推奨します。

優先順位を付け直したレジスターをユーザーに提示します。

次のように尋ねます：「優先順位を付け直したレジスターを docs/tech-debt-register.md に書き戻してもよろしいですか？」

はいの場合、更新したファイルを書き込みます。判定：完了 — レジスターの優先順位を付け直し、保存しました。

いいえの場合、ここで終了します。判定：ブロック — ユーザーが書き込みを拒否しました。

---

フェーズ 2D：レポートモード

負債レジスターを読み込みます。存在しない場合：判定：未評価 — レポート対象の レジスターがありません。先に /tech-debt scan を実行してください。終了します。

次の概要統計を作成します：

• カテゴリ別の Open 項目数と、それらの修正に必要な推定作業量の合計
• 現在のスプリント中に追加された項目と解決された項目。各項目の Added 日付と Resolved [date] ステータスを使います
• 推移の方向（増加／横ばい／減少）— その期間に追加された数と解決された数

レジスターに3スプリントを超えて記載されている項目にフラグを付けます。

レポートをユーザーに出力します。このモードは読み取り専用で、ファイルへの書き込みは行いません。判定：完了 — 負債レポートを作成しました。

フェーズ 3：次のステップ

• /sprint-plan を実行して、優先度の高い負債項目を次のスプリントに組み込みます（workflow: minimal ではスプリントがないため、代わりにブリーフのビルド順序に追加します）。
• 負債の傾向を継続的に把握するため、各スプリントの開始時に /tech-debt report を実行します。

負債レジスターの形式

## Technical Debt Register
Last updated: [Date]
Total items: [N] | Estimated total effort: [T-shirt sizes summed]

| ID | Category | Description | Files | Effort | Impact | Priority | Status | Added | Sprint |
|----|----------|-------------|-------|--------|--------|----------|--------|-------|--------|
| TD-001 | [Cat] | [Description] | [files] | [S/M/L/XL] | [Low/Med/High/Critical] | [Score] | [Open / Resolved YYYY-MM-DD / Accepted — reason] | [YYYY-MM-DD] | [Sprint to fix or "Backlog"] |

行を追加するすべてのスキル（このスキルと、負債として逸脱を記録する /story-done）は、次の順序ですべての 10 列に記入します。また、ファイルを作成するスキルは、最初に上記のヘッダーと表の見出しを記入します。

• ID — TD- に 3 桁の数字を続けた形式で、レジスター内の最大 ID の 1 つ上の番号を使います（新規の場合は TD-001）。ID は再利用しません。
• Category — Scan Mode の 6 つのカテゴリのいずれかを、「Debt」を付けずに記入します。Architecture、Code Quality、Test、Documentation、Dependency、Performance の表記を使います。これは /story-done が記入する表記であり、Report Mode でカテゴリが重複して集計されるのを防ぎます。
• Description — 負債の内容と、それを引き受けた理由を記入します。
• Files — 影響を受けるパスをカンマ区切りで記入します。特定のファイルがない場合は — を記入します。
• Effort — Add Mode と同様に S、M、L、XL のいずれかを記入します。未見積もりの場合は — を記入します。
• Impact — 修正しない場合のコストを Low、Med、High、Critical のいずれかで記入します。未評価の場合は — を記入します。
• Priority — /tech-debt prioritize が記入するスコアを記入します。実行されるまでは — を記入します。
• Status — 追加時は Open と記入します。Resolved YYYY-MM-DD は負債を修正した日付を記録し、Accepted — reason は意識的に維持する判断とその理由を記録します。
• Added — 行を記入した日付を YYYY-MM-DD 形式で記入します。Report Mode は、この日付と Resolved の日付から追加・解決された項目を集計します。
• Sprint — 修正を予定しているスプリント、または Backlog を記入します。

ルール

• 技術的負債は必ずしも悪いものではありません。これはツールです。レジスターでは、意識的な判断を記録します。
• すべての負債項目に、それを受け入れた理由（期限、プロトタイプ、情報不足など）を必ず記載します。
• 新たな負債を見つけるため、「Scan」は少なくとも各スプリントに 1 回実行します。
• 3 スプリント以上、対応されずに残っている項目は、修正するか、理由を文書化したうえで意識的に受け入れます。