tech-debt-analyzer

Tech Debt Analyzer

体系的な技術的負債の棚卸し、優先順位付け、解消計画。 信頼度スコアとエビデンスに基づく調査結果を用いた、複数パスの分析です。

対象範囲： 負債の棚卸しと追跡のみです。コードレビュー（review）、リファクタリングの実行、依存関係の更新は対象外です。

正式な用語

用語	定義
debt item	カテゴリ、重大度、信頼度、エビデンスを含む、個別の技術的負債の調査結果
category	負債の分類：設計、テスト、ドキュメント、依存関係、インフラストラクチャ
severity	影響度：CRITICAL、HIGH、MEDIUM、LOW
confidence	項目ごとのスコア（0.0～1.0）。>=0.7 は報告、0.3～0.7 は要確認として提示、<0.3 は破棄
complexity	循環的複雑度（分岐経路）または認知的複雑度（人間にとっての理解の難しさ）
dead code	コードベース内で参照されていない関数、クラス、インポート
staleness	依存関係の現行バージョンが置き換えられてからの日数
inconsistency	同じパターンがファイル間で異なる形で実装されている状態
remediation	工数の見積もりとリスクレベルを含む、具体的な修正アクション
debt score	全項目の（重大度の重み x 信頼度）の合計である総合指標
baseline	経時比較のために `~/.{gemini
heatmap	ファイルまたはディレクトリごとの負債項目の密度を視覚化したもの
risk x effort	影響度と解消コストを比較する優先順位付けマトリクス

ディスパッチ

$ARGUMENTS	モード
scan または scan <path>	コードベース全体の負債の棚卸し（または指定したパスを対象に実行）
analyze <file/dir>	特定のファイルまたはディレクトリを対象とした詳細分析
prioritize	すべての負債項目をリスク x 工数マトリクスで順位付け
roadmap	段階的な解消計画を作成
report	ダッシュボードの視覚化を表示
track	現在のスキャン結果を前回のベースラインと比較
空	説明と使用例を含むモードメニューを表示

モード：Scan

コードベース全体の負債を棚卸しします。4つの分析スクリプトをすべて実行し、結果を集約してカテゴリと重大度を割り当てます。

Scan Step 1：プロジェクトのプロファイル

uv run python scripts/complexity-scanner.py <path> を実行し、複雑度の指標を取得します。 JSON 出力を解析します。cyclomatic_complexity > 10 の関数には HIGH、> 5 の関数には MEDIUM を割り当てます。

Scan Step 2：デッドコードの検出

uv run python scripts/dead-code-detector.py <path> を実行し、未使用のコードを検出します。 JSON 出力を解析します。未使用の各項目を負債項目にします（カテゴリ：設計、重大度：信頼度に基づいて決定）。

Scan Step 3：依存関係の陳腐化

uv run python scripts/dependency-staleness-checker.py <path> を実行し、古くなったパッケージを確認します。 JSON 出力を解析します。非推奨のパッケージは CRITICAL とします。陳腐化が365日を超える場合は HIGH とします。

Scan Step 4：パターンの一貫性

uv run python scripts/pattern-consistency-checker.py <path> を実行し、不整合を検出します。 JSON 出力を解析します。不整合ごとに負債項目を作成します（カテゴリ：設計）。

Scan Step 5：AI による分析の拡張

スクリプトによる検出後、追加の分析を実施します。

1. ドキュメントの不足 — ドキュメント化されていない公開 API、不足している README セクション、古くなったコメントを調査します
2. テストカバレッジの不足 — 未テストのモジュール、欠落しているエッジケース、テストとコードの比率を Grep で調査します
3. インフラストラクチャの負債 — 古くなった CI 設定、リンターの不足、一貫性のないツールを調査します
4. 設計上の問題 — 神クラス、機能への過度な執着、ショットガン手術のパターンを調査します

調査結果ごとに信頼度スコア（0.0～1.0）を割り当てます。HIGH/CRITICAL の項目は、Grep とコードベースのエビデンスを用いて調査・検証します。

Scan Step 6：集約と分類

すべての調査結果を統合した一覧にまとめます。

• スクリプトの出力間で重複を排除します
• 負債の分類体系（references/debt-taxonomy.md）からカテゴリを割り当てます
• 負債スコアを計算します：（重大度の重み x 信頼度）の合計
• ベースラインを ~/.{gemini|copilot|codex|claude}/tech-debt/<project-slug>-<date>.json に保存します

調査結果をカテゴリごとにまとめ、各カテゴリ内で重大度の高い順に並べて提示します。

モード：分析

特定のファイルまたはディレクトリを対象に、詳細な分析を行います。対象を絞って4つのスクリプトをすべて実行します。 同じ6ステップのスキャンプロセスを適用しますが、関数ごとの分析をさらに詳しく行います。 以下を含めます：関数単位の複雑度の内訳、インラインのデッドコード、ローカルなパターン違反。

モード：優先順位付け

リスクと工数のマトリックスを使って、技術的負債の項目をランク付けします。references/prioritization-framework.mdを読み込みます。

	低工数	中工数	高工数
高リスク	P0：直ちに修正	P1：次のスプリントで実施	P2：次の四半期に計画
中リスク	P1：次のスプリントで実施	P2：次の四半期に計画	P3：バックログ
低リスク	P2：簡単に対応できる項目をまとめて処理	P3：バックログ	P4：許容または延期

各負債項目について、以下を見積もります。

• リスク：影響範囲 × 深刻度 × 確信度
• 工数：影響を受けるLOC × 複雑度 × 依存関係の数

優先度ラベル（P0～P4）を付けて、順位付けしたリストを出力します。

モード：ロードマップ

段階的な修正計画を作成します。事前のスキャンが必要です（~/.{gemini|copilot|codex|claude}/tech-debt/からベースラインを読み込みます）。

フェーズ構成：

1. クイックウィン（P0＋低工数のP1）：リスクを最小限に抑えた即時修正
2. 構造改善（残りのP1＋高リスクのP2）：設計改善、リファクタリング
3. 保守（P2＋P3）：ドキュメント、テストカバレッジ、依存関係の更新
4. 戦略的改善（P3＋P4）：アーキテクチャの変更、長期的な改善

各フェーズには、項目、推定工数、依存関係、成功基準を含めます。

モード：レポート

ダッシュボードのビジュアライゼーションを生成します。事前のスキャンが必要です。

1. ~/.{gemini|copilot|codex|claude}/tech-debt/から最新のベースラインを読み込みます
2. templates/dashboard.htmlを一時ファイルにコピーします
3. 調査結果のJSONを<script id="data">タグに挿入します
4. ブラウザーで開くか、パスを報告します

ダッシュボードのセクション：カテゴリ別円グラフ、複雑度ヒートマップ、推移グラフ（ベースラインが複数ある場合）、優先順位付きバックログテーブル。

モード：追跡

現在のスキャン結果を前回のベースラインと比較し、長期的な推移を追跡します。

1. 新たにスキャンを実行します（モード：スキャンの手順1～6）
2. ~/.{gemini|copilot|codex|claude}/tech-debt/<project-slug>-*.jsonから前回のベースラインを読み込みます（最新のもの）
3. 差分を算出します：新規項目、解決済み項目、深刻度の変更、スコアの推移
4. 推移の指標を含む比較レポートを提示します

状態管理

• 状態ディレクトリ：~/.{gemini|copilot|codex|claude}/tech-debt/
• 初回使用時にmkdir -pでディレクトリを作成します
• ファイル名：<project-slug>-<YYYY-MM-DD>.json
• プロジェクトスラッグ：プロジェクトルートディレクトリのベース名をサニタイズしたもの
• 各スキャンの後に保存します。追跡モードでは過去のベースラインを読み込みます
• スキーマ：{ "project": str, "date": str, "score": float, "items": [...], "summary": {...} }

参照ファイル

一度に読み込む参照ファイルは1つだけにしてください。すべての参照ファイルをコンテキストに事前読み込みしないでください。

ファイル	内容	読み込むタイミング
references/debt-taxonomy.md	5つの負債カテゴリとサブカテゴリ、修正テンプレート	スキャン手順6、調査結果の分類時
references/complexity-metrics.md	循環的複雑度と認知的複雑度の定義、しきい値、解釈	複雑度スキャナーの出力を解釈する時
references/prioritization-framework.md	リスクと工数のマトリックス、スコアリング基準、優先度の定義	優先順位付けモード
references/remediation-templates.md	問題の種類ごとの修正パターン、工数見積もり、リスク評価	ロードマップモード、修正計画の作成時

スクリプト	実行するタイミング
scripts/complexity-scanner.py	スキャン手順1、分析モード
scripts/dead-code-detector.py	スキャン手順2、分析モード
scripts/dependency-staleness-checker.py	スキャン手順3
scripts/pattern-consistency-checker.py	スキャン手順4、分析モード

テンプレート	描画するタイミング
templates/dashboard.html	レポートモード — 調査結果のJSONをデータタグに挿入

負債項目の構造

すべての負債項目は、次の形式に従います。

1. 場所: [file:line] または [file:start-end] — 正確なソースの場所
2. カテゴリ: 設計 | テスト | ドキュメント | 依存関係 | インフラストラクチャ
3. 重大度: CRITICAL | HIGH | MEDIUM | LOW
4. 信頼度: 根拠に基づく 0.0～1.0 のスコア
5. 説明: 負債の内容（1～2 文）
6. 影響: 重要である理由（影響範囲、リスク）
7. 解消方法: 推奨する修正方針と工数の見積もり

重要なルール

1. 指摘を提示する前に、4 つすべての分析スクリプトを実行してください。部分的なスキャンは、その旨を明記します
2. すべての指摘には、根拠（スクリプトの出力またはコードベースの検索結果）に裏付けられた信頼度スコアが必要です
3. 信頼度が 0.3 未満の場合は破棄し、0.3～0.7 の場合は不確かな指摘として示し、0.7 以上の場合は報告してください
4. 解消作業は実行しないでください。このスキルの目的は、負債の棚卸しと計画であり、修正ではありません
5. 完全なスキャンの後は、毎回ベースラインを保存してください。時系列の追跡にはこれが必要です
6. スタイル上の好みを負債として報告しないでください。構造、動作、保守性に関する問題のみを扱います
7. スクリプトの出力間で重複を排除し、同じ file:line を重複して表示しないでください
8. 優先順位付けモードでは、以前のスキャン結果が必要です。ベースラインがない場合は、まずスキャンを実行するようユーザーに促してください
9. スキャン結果には、必ず負債スコア（集計指標）を含めてください
10. 追跡モードでは、差分（新規／解消／変更）を示してください。比較のない単なる数値には意味がありません
11. デッドコードの検出には高い信頼度（0.8 以上）が必要です。誤検出は信頼を損ないます
12. 参照ファイルは一度に 1 つだけ読み込んでください。すべての参照ファイルを事前に読み込まないでください