Initial commit

commands/tech-debt.md

@@ -0,0 +1,185 @@
+## Tech Debt
+
+プロジェクトの技術的負債を定量的に分析し、健全性スコアと開発効率への影響を可視化します。トレンド分析により改善状況を追跡し、時間的コストを算出して優先順位付けされた改善計画を作成します。
+
+### 使い方
+
+```bash
+# プロジェクトの構成を確認して技術的負債を分析
+ls -la
+「このプロジェクトの技術的負債を分析して改善計画を作成して」
+```
+
+### プロジェクト健全性ダッシュボード
+
+```text
+プロジェクト健全性スコア: 72/100
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 カテゴリ別スコア
+├─ 依存関係の鮮度: ████████░░ 82% (最新: 45/55)
+├─ ドキュメント充実度: ███░░░░░░░ 35% (README, API 文書不足)
+├─ テストカバレッジ: ██████░░░░ 65% (目標: 80%)
+├─ セキュリティ: ███████░░░ 78% (脆弱性: 2 件 Medium)
+├─ アーキテクチャ: ██████░░░░ 60% (循環依存: 3 箇所)
+└─ コード品質: ███████░░░ 70% (複雑度高: 12 ファイル)
+
+📈 トレンド (過去 30 日)
+├─ 総合スコア: 68 → 72 (+4) ↗️
+├─ 改善項目: 12 件 ✅
+├─ 新規負債: 3 件 ⚠️
+├─ 解消負債: 8 件 🎉
+└─ 改善速度: +0.13/日
+
+⏱️ 負債の時間的影響
+├─ 開発速度低下: -20% (新機能開発が通常の 1.25 倍の時間)
+├─ バグ修正時間: +15% (平均修正時間 2h → 2.3h)
+├─ コードレビュー: +30% (複雑性による理解時間増加)
+├─ オンボーディング: +50% (新メンバーの理解に要する時間)
+└─ 累積遅延時間: 週 40 時間相当
+
+🎯 改善による期待効果 (時間ベース)
+├─ 即座の効果: 開発速度 +10% (1 週間後)
+├─ 短期効果: バグ率 -25% (1 ヶ月後)
+├─ 中期効果: 開発速度 +30% (3 ヶ月後)
+├─ 長期効果: メンテナンス時間 -50% (6 ヶ月後)
+└─ ROI: 投資 40 時間 → 回収 120 時間 (3 ヶ月)
+```
+
+### 基本例
+
+```bash
+# 健全性スコアの詳細分析
+find . -name "*.js" -o -name "*.ts" | xargs wc -l | sort -rn | head -10
+「プロジェクト健全性スコアを算出して、カテゴリ別に評価して」
+
+# TODO/FIXME の負債インパクト分析
+grep -r "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" . --exclude-dir=node_modules --exclude-dir=.git
+「これらの TODO を負債インパクト (時間×重要度) で評価して」
+
+# 依存関係の健全性チェック
+ls -la | grep -E "package.json|Cargo.toml|pubspec.yaml|go.mod|requirements.txt"
+「依存関係の鮮度スコアを算出し、アップデートのリスクと効果を分析して」
+```
+
+### Claude との連携
+
+```bash
+# 包括的な技術的負債分析
+ls -la && find . -name "*.md" -maxdepth 2 -exec head -20 {} \;
+「このプロジェクトの技術的負債を以下の観点で分析して：
+1. コード品質 (複雑度、重複、保守性)
+2. 依存関係の健全性
+3. セキュリティリスク
+4. パフォーマンス問題
+5. テストカバレッジ不足」
+
+# アーキテクチャの負債分析
+find . -type d -name "src" -o -name "lib" -o -name "app" | head -10 | xargs ls -la
+「アーキテクチャレベルの技術的負債を特定し、リファクタリング計画を提案して」
+
+# 優先順位付けされた改善計画
+「技術的負債を以下の基準で評価して表形式で提示：
+- 影響度 (高/中/低)
+- 修正コスト (時間)
+- 技術的リスク (システム障害、データ損失の可能性)
+- 改善による時間削減効果
+- 推奨実施時期」
+```
+
+### 詳細例
+
+```bash
+# プロジェクトタイプの自動検出と分析
+find . -maxdepth 2 -type f \( -name "package.json" -o -name "Cargo.toml" -o -name "pubspec.yaml" -o -name "go.mod" -o -name "pom.xml" \)
+「検出されたプロジェクトタイプに基づいて、以下を分析：
+1. 言語・フレームワーク固有の技術的負債
+2. ベストプラクティスからの逸脱
+3. モダナイゼーションの機会
+4. 段階的な改善戦略」
+
+# コードの品質メトリクス分析
+find . -type f -name "*" | grep -E "\.(js|ts|py|rs|go|dart|kotlin|swift|java)$" | wc -l
+「プロジェクトのコード品質を分析し、以下のメトリクスを提示：
+- 循環的複雑度が高い関数
+- 重複コードの検出
+- 長すぎるファイル/関数
+- 適切なエラーハンドリングの欠如」
+
+# セキュリティ負債の検出
+grep -r "password\|secret\|key\|token" . --exclude-dir=.git --exclude-dir=node_modules | grep -v ".env.example"
+「セキュリティに関する技術的負債を検出し、修正優先度と対策を提案して」
+
+# テスト不足の分析
+find . -type f \( -name "*test*" -o -name "*spec*" \) | wc -l && find . -type f -name "*.md" | xargs grep -l "test"
+「テストカバレッジの技術的負債を分析し、テスト戦略を提案して」
+```
+
+### 負債の優先順位マトリクス
+
+```text
+優先度 = (影響度 × 発生頻度) ÷ 修正コスト
+```
+
+| 優先度              | 開発への影響 | 修正コスト | 時間削減効果 | 投資対効果        | 対応期限   |
+| ------------------- | ------------ | ---------- | ------------ | ----------------- | ---------- |
+| **[P0] 今すぐ対応** | 高           | 低         | > 5 倍       | 投資 1h→削減 5h+  | 即座       |
+| **[P1] 今週中**     | 高           | 中         | 2-5 倍       | 投資 1h→削減 2-5h | 1 週間以内 |
+| **[P2] 今月中**     | 低           | 高         | 1-2 倍       | 投資 1h→削減 1-2h | 1 ヶ月以内 |
+| **[P3] 四半期中**   | 低           | 低         | < 1 倍       | 投資=削減時間     | 3 ヶ月以内 |
+
+### 負債タイプ別の評価基準
+
+| 負債タイプ             | 検出方法                  | 開発への影響                   | 修正時間 |
+| ---------------------- | ------------------------- | ------------------------------ | -------- |
+| **アーキテクチャ負債** | 循環依存、密結合          | 変更時影響範囲大、テスト困難   | 40-80h   |
+| **セキュリティ負債**   | CVE スキャン、OWASP       | 脆弱性リスク、コンプライアンス | 8-40h    |
+| **パフォーマンス負債** | N+1、メモリリーク         | 応答時間増加、リソース消費     | 16-40h   |
+| **テスト負債**         | カバレッジ < 60%          | バグ検出遅延、品質不安定       | 20-60h   |
+| **ドキュメント負債**   | README 不足、API 文書なし | オンボーディング時間増加       | 8-24h    |
+| **依存関係負債**       | 2 年以上未更新            | セキュリティリスク、互換性問題 | 4-16h    |
+| **コード品質負債**     | 複雑度 > 10               | 理解・修正時間増加             | 2-8h     |
+
+### 技術的負債の影響度算出
+
+```text
+影響度 = Σ(各要素の重み × 測定値)
+
+📊 測定可能な影響指標：
+├─ 開発速度への影響
+│  ├─ コード理解時間: +X% (複雑度に比例)
+│  ├─ 変更時の影響範囲: Y ファイル (結合度で測定)
+│  └─ テスト実行時間: Z 分 (CI/CD パイプライン)
+│
+├─ 品質への影響
+│  ├─ バグ発生率: 複雑度 10 毎に +25%
+│  ├─ レビュー時間: 行数 × 複雑度係数
+│  └─ テスト不足リスク: カバレッジ 60% 未満で高リスク
+│
+└─ チーム効率への影響
+   ├─ オンボーディング時間: ドキュメント不足で +100%
+   ├─ 知識の属人化: 単一貢献者率 >80% で要注意
+   └─ コード重複による修正箇所: 重複率 × 変更頻度
+```
+
+### 時間ベースの ROI 計算
+
+```text
+ROI = (削減時間 - 投資時間) ÷ 投資時間 × 100
+
+例：循環依存の解消
+├─ 投資時間: 16 時間 (リファクタリング)
+├─ 削減効果 (月次):
+│  ├─ コンパイル時間: -10 分/日 × 20 日 = 200 分
+│  ├─ デバッグ時間: -2 時間/週 × 4 週 = 8 時間
+│  └─ 新機能追加: -30% 時間短縮 = 12 時間
+├─ 月次削減時間: 23.3 時間
+└─ 3 ヶ月 ROI: (70 - 16) ÷ 16 × 100 = 337%
+```
+
+### 注意事項
+
+- プロジェクトの言語やフレームワークを自動検出し、それに応じた分析を行います
+- 健全性スコアは 0-100 点で評価し、70 点以上を健全、50 点以下を要改善とします
+- 時間的コストと改善効果を具体的に算出し、データに基づいた意思決定を支援します
+- 金銭換算が必要な場合は、チームの平均時給やプロジェクト固有の係数を別途指定してください