tech-debt

技術的負債の分析

8 つのカテゴリにわたってコードベースを調査し、各項目の影響度と作業量を評価して、優先順位を付けた TECH_DEBT.md の改善計画を作成します。4 つのカテゴリは直接分析し、残りの 4 つは専門スキルに委任します。

前提条件の確認

git --version 2>/dev/null && git rev-parse --is-inside-work-tree 2>/dev/null

Git リポジトリではない場合は警告を出して続行してください。Git 履歴の分析はできませんが、ほかのチェックは実施できます。

ステップ 1：プロジェクトのコンテキスト

分析の前に、ベースラインとなるメトリクスを収集します。

echo "Project: $(basename $(pwd))"
echo "Files: $(find . -type f -name '*.go' -o -name '*.js' -o -name '*.ts' \
  -o -name '*.py' -o -name '*.rs' -o -name '*.cs' | grep -v node_modules \
  | grep -v vendor | grep -v .git | wc -l)"
echo "Branch: $(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
echo "Last commit: $(git log -1 --format='%h %s' 2>/dev/null)"

存在する設定ファイルから、プロジェクトの種類（Go、Node、Python、.NET、Rust、混在）を検出します。

ステップ 2：委任するカテゴリ

専門スキルが対応するカテゴリについては、作業を委任するか、今後の委任に向けて記録します。

コード品質 — scout スキルが利用可能な場合は、最近変更されたファイルに対して実行します。Scout は Impact x Low-Risk のスコアリングに基づき、ファイルごとに改善の機会を上位 3 件特定します。

Lint — lint-fix スキルが利用可能な場合は、その検出モード（ステップ 1 のみ）を実行して、設定済みの lint ツールと不足しているツールを特定します。修正パイプライン全体は実行しないでください。

セキュリティ — security-audit スキルが利用可能な場合は、OWASP Top 10 の分析、シークレットの検出、サプライチェーンの評価、脅威モデリングを実行します。技術的負債のスコアカードにセキュリティスコアを含めます。

依存関係 — dep-upgrade スキルが利用可能な場合は、その監査手順（ステップ 1～2 のみ）を実行して、古くなったパッケージや脆弱性のあるパッケージを優先度別に特定します。技術的負債のスコアカードに依存関係の健全性スコアを含めます。

設計原則 — design-principles スキルが利用可能な場合は、コードベース全体に対して委任モードで実行します。SOLID、DRY、YAGNI、KISS、デメテルの法則、関心の分離、継承よりコンポジション、そして 12-Factor のうちコードに関連する項目に照らして監査します。設計全体の健全性スコアを技術的負債のスコアカードに含め、P1 の指摘事項を改善ロードマップに取り込みます。

ステップ 3：アーキテクチャ分析（直接）

コードベースを調査し、構造上の問題を特定します。詳細なパターンについては、references/analysis-patterns.md を参照してください。

1. 巨大なファイルを確認 — 500 行を超え、複数の責務が混在するファイルを見つけます
2. 結合度を確認 — 10 を超えるパッケージをインポートしているファイルを見つけます
3. レイヤー違反を確認 — 不適切なレイヤーにあるデータベース／HTTP ロジックを探します
4. 循環依存を確認 — インポートのパターンを追跡します
5. 影響の大きいアーキテクチャ上の問題を 3～5 件特定 — 新機能の開発を妨げる、またはバグの原因となる問題に焦点を当てます

ステップ 4：テスト分析（直接）

テストの健全性を測定します。詳細なパターンについては、references/analysis-patterns.md を参照してください。

1. カバレッジを測定 — 利用可能な場合はカバレッジツールを実行します
2. テスト／コード比率を算出 — テストファイルとコードファイルの数を数えます
3. 重要な未テスト経路を特定 — エントリーポイントをたどり、各段階にテストカバレッジがあるか確認します
4. テストのアンチパターンにフラグを付ける — アサーションがないテスト、sleep による同期、共有状態、実装のテスト
5. 不足しているテストの種類を確認 — ユニットテストしかないか、統合テストや E2E テストがあるか確認します

ステップ 5：ドキュメント分析（直接）

ドキュメントの網羅性を確認します。詳細なパターンについては、references/analysis-patterns.md を参照してください。

1. 必須ファイル — README.md、CONTRIBUTING.md、CHANGELOG.md、アーキテクチャドキュメント、API ドキュメント
2. API ドキュメントの網羅率 — ドキュメント化された公開関数／型の数と全体数の比率
3. 古くなったドキュメント — すでに存在しないファイル、関数、パターンへの言及
4. 不足している ADR — 判断の根拠が記録されていない、重要なアーキテクチャ上の決定

ステップ 6：インフラストラクチャ分析（直接）

運用への準備状況を評価します。詳細なパターンについては、references/analysis-patterns.md を参照してください。

1. CI/CD — ワークフロー設定、テストの自動化、デプロイの自動化を確認します
2. デプロイ — Dockerfile、コンテナー設定、デプロイスクリプトを確認します
3. 可観測性 — 構造化ログ、エラー追跡、メトリクス、アラートを確認します
4. 設定 — 環境変数とハードコードされた値の使い分け、シークレット管理を確認します

Step 7: 各カテゴリを採点する

references/scoring-guide.md の採点基準を使って、すべてのカテゴリを 0～10 で採点します。各指摘に影響度（LOW/MEDIUM/HIGH/CRITICAL）と工数（S/M/L/XL）を割り当てます。

優先度を算出します。P1（影響度が高く、工数が少ない）から P4 （影響度が低く、工数が多い）までです。

Step 8: TECH_DEBT.md を生成する

references/scoring-guide.md のテンプレートを使ってレポートを作成します。 以下を含めます。

• 総合健全性スコア（9 カテゴリの合計、90 点満点）を含むエグゼクティブサマリー
• 9 カテゴリすべてを含むスコアカード表
• 各カテゴリの、根拠と修正方法を含む詳細な指摘
• 優先度別（P1 → P4）に整理した修正ロードマップ
• 現在値と目標値を含む成功指標

生成したファイルに対して markdownlint を実行します。

Step 9: 概要を提示する

ユーザーに以下を提示します。

1. スコアカード表（8 カテゴリ、スコア、各カテゴリの主な問題）
2. 総合健全性スコア（X/80）
3. 早急な対応が必要な P1 項目
4. 修正の優先事項トップ 5 と推定工数
5. どの項目から対応するかを尋ねます