| 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: 手動レビュー
各自動検出結果について:
- 実際の負債であることを確認（意図的な設計ではない）
- 実世界での影響を評価
- 修正工数を見積もる
- 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. ストラングラーフィグパターン
大規模なレガシーシステムの場合:
- 旧と並行して新を構築
- 段階的にトラフィックをルーティング
- 新が実証されたら旧を削除
レポートテンプレート
ステークホルダー向け
## 技術的負債レポート - [日付]
### ヘルススコア: [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: 健全性メトリクスのための負債トレンドの経時追跡を検討
