tech-debt-tracker

技術的負債トラッカー

エージェントは、AST 解析、遅延コスト分析、トレンドダッシュボードを使用して、コードベース全体の技術的負債を特定、評価、優先順位付けし、追跡します。

主な機能

• 検出 — Python の AST 解析と、すべての言語を対象とする正規表現パターンマッチングにより、コード、アーキテクチャ、テスト、ドキュメント、依存関係、インフラストラクチャの 6 種類の負債を検出します。
• 深刻度のスコアリング — 各項目について、速度、品質、生産性、ビジネスへの影響をそれぞれ 1～10 で評価し、作業量（XS～XL）とリスクも見積もります。
• 遅延コスト — 利息率（Impact x Frequency）と遅延コスト（Interest x Sprints x Team Multiplier）を算出します。WSJF と RICE のフレームワークにも対応しています。
• 優先順位付け — 遅延コスト対作業量のマトリクスにプロットし、「即時対応」「計画的対応」「機会対応」「バックログ」に分類します。
• スプリント配分 — チームのベロシティに基づいて負債対機能の比率を適用し、負債対応のためのキャパシティを確保します。
• リファクタリング戦略 — ストラングラーフィグ、抽象化による分岐、機能トグル、並行実行に対応します。
• レポート — スキャンのスナップショットから、エグゼクティブ向けおよびエンジニアリング向けダッシュボード、トレンド分析、ベロシティ追跡、予測を作成します。

使用する場面

• リポジトリ全体の技術的負債を追跡し、定量化するとき。
• リファクタリング作業に優先順位を付け、遅延コストを算出するとき。
• 負債対応と機能開発の間で、スプリントのキャパシティ配分を計画するとき。
• 経営幹部向けに、負債の健全性やトレンド、投資に関する推奨事項を報告するとき。

事前に確認すること

スキャンやレポート作成の前に、以下の入力項目を確認してください。不明または曖昧な項目があれば、推測せずに質問してください。

• 対象コードベース — スキャンするディレクトリ（負債一覧の対象）
• 優先順位付けのフレームワークとチーム規模 — 遅延コスト／WSJF／RICE と人員数（--framework、--team-size。ランキングとスプリント配分に影響します）
• レポートの対象読者 — エグゼクティブ向けダッシュボードか、エンジニアリング向け一覧か（レポートの形式と詳細度を決定します）

停止ルール：出力に最も大きく影響する 2～3 項目だけを質問してください。ユーザーが「とりあえずドラフトを作って」と言った場合は作成を進め、成果物の冒頭に前提条件を記載してください。

ツール

ツール	目的	コマンド
debt_scanner.py	ディレクトリ内の負債の兆候をスキャンし、JSON の一覧とテキストレポートを出力します	python scripts/debt_scanner.py <dir> --output scan_results --format both
debt_prioritizer.py	一覧に遅延コスト／WSJF／RICE とスプリント配分を追加します	python scripts/debt_prioritizer.py scan_results.json --framework wsjf --team-size 8
debt_dashboard.py	スナップショット全体のトレンド分析、ベロシティ、予測、エグゼクティブ向け要約を作成します	python scripts/debt_dashboard.py --input-dir ./debt_scans/ --period quarterly

参考資料

タスクに合った参考資料を読み込みます。このファイルは簡潔に保ち、必要に応じて詳細を参照してください。

• references/methodology.md — 7 ステップのワークフロー、負債分類表、重大度評価フレームワーク、利息率／遅延コストの計算式、優先順位付けマトリクス、WSJF、スプリント配分比率、負債項目の JSON スキーマ、リファクタリング戦略、四半期計画が記載されています。評価、優先順位付け、計画を行う際に参照してください。
• references/tool-reference.md — 3 つのスクリプトすべてのパラメーター表、使用例、出力形式の詳細と、トラブルシューティング表が記載されています。スクリプトの実行時や出力のデバッグ時に参照してください。
• references/dashboards-and-examples.md — 経営陣向けおよびエンジニアリング向けダッシュボードのレイアウト、Python マイクロサービスのスキャン例、成功基準が記載されています。レポートの生成時や品質の検証時に参照してください。
• references/debt-classification-taxonomy.md — 各カテゴリの検出ヒューリスティクスを含む、複数の観点から負債を分類するための包括的な分類体系が記載されています。検出の調整や項目のラベル付けを行う際に参照してください。
• references/prioritization-framework.md — ビジネス価値、リスク、工数、戦略との整合性に基づく、詳細な優先順位付けのアプローチが記載されています。優先順位付けの基準を設計する際に参照してください。
• references/stakeholder-communication-templates.md — さまざまなステークホルダーグループに負債の状況、影響、推奨事項を伝えるためのテンプレートとガイドラインが記載されています。経営陣やプロダクトチームへの報告時に参照してください。

また、Technical Debt Quadrant（Fowler）と実装ロードマップの各フェーズについては、スキルのルートにある REFERENCE.md を参照してください。

対象範囲と制限事項

このスキルで対応すること：

• AST 解析（Python）と正規表現によるパターンマッチング（すべての言語）を通じた、コードレベル、アーキテクチャ、テスト、ドキュメント、依存関係、インフラストラクチャの負債の静的検出。
• 設定可能なチーム規模とスプリントのキャパシティを使用し、コスト遅延、WSJF、RICE のフレームワークに基づいて負債項目の優先順位を定量的に決定します。
• 複数のスキャンスナップショットからの履歴傾向分析、健全性スコアリング、負債の発生速度の追跡、経営陣向け／エンジニアリング向けダッシュボードの生成。
• キャパシティを考慮したバックログのスケジューリングと、負債の種類に応じた工数見積もりによるスプリント配分計画。

このスキルでは対応しないこと：

• 実行時のパフォーマンスプロファイリングや本番環境の監視については対象外です。該当する内容については engineering/performance-profiler と engineering/observability-designer を参照してください。
• 依存関係の脆弱性スキャン（CVE 検出）やソフトウェア構成分析については対象外です。セキュリティに重点を置いた依存関係のレビューについては engineering/dependency-auditor を参照してください。
• 自動リファクタリングやコード変換は行いません。このスキルは負債を特定して優先順位を付けますが、ソースコードは変更しません。
• データベーススキーマの負債、API コントラクトのドリフト、Infrastructure as Code のドリフト検出については対象外です。これらの分野については engineering/database-schema-designer、engineering/api-design-reviewer、engineering/migration-architect を参照してください。

統合ポイント

スキル	統合方法	データフロー
engineering/dependency-auditor	依存関係監査の結果を dependency_debt 項目としてスキャナーに取り込み、すべての負債を一つのインベントリに集約します。	依存関係監査の JSON -> スキャナー設定、または debt_inventory.json に手動で統合
engineering/performance-profiler	パフォーマンスのボトルネックと複雑度の高い負債項目を関連付け、品質と速度の両方を向上させるリファクタリングを優先します。	プロファイラーのボトルネックレポート -> ファイルパスを基にスキャナーの出力と相互参照
engineering/ci-cd-pipeline-builder	debt_scanner.py を CI パイプラインのステップとして追加し、ヘルススコアがしきい値を下回る場合や重大な負債の件数が増加した場合にビルドを失敗させます。	スキャナーの JSON 出力 -> summary.health_score に基づく CI ゲート条件
engineering/pr-review-expert	プルリクエストで変更されたファイルについて負債インベントリを検索し、コードレビュー中に関連する負債項目を提示します。	PR の変更ファイル一覧 -> file_path で debt_inventory.json を絞り込み
engineering/observability-designer	インフラストラクチャの負債項目（監視の欠如、環境の不整合など）を、可観測性スキルで特定された可観測性のギャップに対応付けます。	ダッシュボードの category_distribution -> 可観測性のギャップ分析
engineering/migration-architect	優先順位付けされたバックログを使用して、大規模な移行の範囲と順序を決定します。特に、計画対象の取り組みとして評価されたアーキテクチャカテゴリの負債が対象です。	優先順位付けツールの sprint_allocation -> 移行計画のタイムライン