tech-debt-management

name	tech-debt-management
description	技術的負債の特定、分類、優先順位付けフレームワーク。 体系的な負債解消のための legacy-modernizer エージェントとの統合。 以下の場合に使用: - コードベースの技術的負債の特定 - どの負債を先に対処すべきかの優先順位付け - 負債の経時的な追跡 - リファクタリングスプリントの計画 - ステークホルダーへの負債解消の正当化 Trigger phrases: tech debt, technical debt, code smell, refactor priority, RICE score, debt tracking, legacy code
allowed-tools	Read, Write, Glob, Grep, TodoWrite
model	sonnet
user-invocable	true

技術的負債管理

技術的負債の特定、分類、優先順位付け、追跡のためのフレームワーク。

基本原則

Anthropic の Building Effective Agents より:

"Agents should gain ground truth from the environment at each step."

負債への適用: 仮定ではなく実際のコードパターンから負債を特定する。測定可能な影響に基づいて優先順位を付ける。

負債の分類

技術的負債の種類

種類	説明	検出方法
設計負債	不適切な抽象化、密結合	依存関係分析、code-explorer
コード負債	重複、複雑さ、不適切な命名	リンター警告、複雑度メトリクス
テスト負債	低カバレッジ、フレーキーテスト	カバレッジレポート、テスト履歴
ドキュメント負債	ドキュメントの欠如/陳腐化	/doc-audit の発見
依存関係負債	古いパッケージ、脆弱性	npm audit、security-auditor
インフラ負債	手動プロセス、自動化の欠如	devops-sre 分析

負債の重大度レベル

レベル	影響	例
Critical	開発をブロックまたは障害を引き起こす	循環依存、セキュリティ脆弱性
High	開発を大幅に遅延させる	重要パスのテストなし、重大な重複
Medium	摩擦を生み、バグリスクを増加	不整合なパターン、部分的なカバレッジ
Low	見た目上の問題や軽微な不便	命名の不整合、ドキュメント不足

優先順位付けフレームワーク

RICE スコア

Reach x Impact x Confidence / Effort

要素	スケール	説明
Reach	1-10	影響を受ける開発者/機能の数
Impact	0.25, 0.5, 1, 2, 3	ケースごとの改善度
Confidence	0-100%	見積もりの確信度
Effort	人・週	修正にかかる作業量

例:

負債: 共有バリデーションロジックの抽出
Reach: 8（8 モジュールに影響）
Impact: 2（大幅な改善）
Confidence: 80%
Effort: 1 週

RICE = (8 × 2 × 0.8) / 1 = 12.8

遅延のコスト

時間に敏感な負債の場合:

CoD = (Weekly Impact × Weeks Until Critical) / Effort

以下の場合に使用:

• 公開期限のあるセキュリティ脆弱性
• サポート終了が近い依存関係
• ユーザー成長に影響するパフォーマンスの問題

象限分析

迅速な視覚的優先順位付け:

                高インパクト
                    │
    ┌───────────────┼───────────────┐
    │               │               │
    │  クイックウィン │  大型プロジェクト
    │  （最初にやる）│  （慎重に計画）
    │               │               │
低  ├───────────────┼───────────────┤ 高
工数                │               工数
    │               │               │
    │  すき間作業    │  割に合わない作業
    │  （時間がある  │  （回避または委任）
    │   時にやる）   │               │
    │               │               │
    └───────────────┼───────────────┘
                    │
                低インパクト

負債追跡フォーマット

負債レジストリ（JSON）

{
  "version": "1.0",
  "lastUpdated": "2025-01-20",
  "summary": {
    "total": 15,
    "critical": 2,
    "high": 5,
    "medium": 6,
    "low": 2
  },
  "debts": [
    {
      "id": "TD-001",
      "title": "Extract validation utilities",
      "type": "code",
      "severity": "high",
      "location": "src/services/*.ts",
      "description": 
       
       
         
         
         
         
         
      
       
       
       
        
    
  

ステータス値

ステータス	説明
identified	負債を発見、未優先順位付け
prioritized	RICE スコア付き、バックログに追加
scheduled	スプリント/マイルストーンに割り当て
in_progress	現在対処中
resolved	修正済みかつ検証済み
accepted	意図的に先送り

負債特定ワークフロー

ステップ 1: 自動検出

code-explorer を分析重視で起動:

技術的負債の指標についてコードベースを分析:

1. **複雑性ホットスポット**: 高い循環的複雑度のファイル
2. **重複**: ファイル間で類似するコードブロック
3. **依存関係の問題**: 循環インポート、古いパッケージ
4. **テストギャップ**: テストのない重要パス
5. **コードの悪臭**: 長いメソッド、大きなクラス、深いネスト

ファイル場所と重大度評価付きで発見結果を返す。

ステップ 2: 手動レビュー

各自動検出結果について:

1. 実際の負債であることを確認（意図的な設計ではない）
2. 実世界での影響を評価
3. 修正工数を見積もる
4. RICE スコアを計算

ステップ 3: レジストリの更新

確認された負債項目を追跡ファイルに追加:

• .claude/tech-debt.json（プロジェクトレベル）
• またはイシュートラッカーと統合

エージェントとの統合

legacy-modernizer の使用

特定された負債の対処に:

legacy-modernizer に委任:

この技術的負債に対処:

Debt ID: TD-001
Title: Extract validation utilities
Location: src/services/*.ts
Description: [レジストリより]

アプローチ:
1. 共有バリデーションモジュールを作成
2. 各サービスを段階的に移行
3. 動作変更がないことを検証（特性化テスト）
4. コードベース全体でインポートを更新

制約:
- 既存のテストカバレッジを保持
- 破壊的な API 変更なし
- 各サービスの移行後にコミット

security-auditor の使用

依存関係の負債に:

security-auditor に委任:

セキュリティ負債について依存関係を監査:

フォーカス:
- 既知の脆弱性（npm audit 等）
- サポート終了のパッケージ
- セキュリティアドバイザリのあるパッケージ

重大度とアップグレードパス付きの優先順位付きリストを返す。

返済戦略

1. ボーイスカウトルール

「コードを見つけた時よりも良い状態にして去る。」

• 関連作業中に小さな負債を修正
• 専用の負債スプリントは不要
• 累積的な改善を追跡

2. 専用の負債スプリント

キャパシティの一定割合を割り当てる:

• 20% ルール: 週に 1 日を負債に充てる
• 負債スプリント: 四半期ごとの集中的なクリーンアップ
• マイルストーン負債: メジャーリリース前に解消

3. ストラングラーフィグパターン

大規模なレガシーシステムの場合:

1. 旧と並行して新を構築
2. 段階的にトラフィックをルーティング
3. 新が実証されたら旧を削除

レポートテンプレート

ステークホルダー向け

## 技術的負債レポート - [日付]

### ヘルススコア: [X]/100

### サマリー
- **合計項目**: [N]
- **Critical**: [N]（即時対応が必要）
- **推定合計工数**: [X] 人・週

### RICE スコア上位 5 件

| 順位 | タイトル | タイプ | RICE | 工数 |
|------|---------|-------|------|------|
| 1 | [タイトル] | [タイプ] | [スコア] | [工数] |

### 最近の進捗
- 解決済み: この[期間]で [N] 件
- 新規: [N] 件特定

### 推奨事項
1. [最優先のアクション]
2. [次の優先アクション]

Rules (L1 - Hard)

• ALWAYS: 仮定ではなく実際のコードに対して負債を検証する
• NEVER: 影響評価なしに負債を優先順位付けしない
• ALWAYS: 負債を正式に追跡する（レジストリまたはイシュー）
• NEVER: 重大なセキュリティ負債を緊急性なしに対処しない

Defaults (L2 - Soft)

• 優先順位付けに RICE スコアリングを使用
• 負債レジストリを .claude/tech-debt.json に保存
• 月次で負債ステータスをレビュー
• スプリント計画に負債を含める

Guidelines (L3)

• consider: キャパシティの 20% を負債返済に充てることを検討
• prefer: 変更中のコード付近の負債を優先的に返済することを推奨
• consider: チームのレトロスペクティブでの負債の可視化を検討
• consider: 健全性メトリクスのための負債トレンドの経時追跡を検討