techdebt

技術的負債スキャナー

並列サブエージェントを使用して、技術的負債を自動検出します。コンテキストが新鮮なうちに問題を見つけられるよう、セッション終了時に実行する設計です。

クイックスタート

# Session end - scan changes since last commit (default)
/techdebt

# Deep scan - analyze entire codebase
/techdebt --deep

# Specific categories
/techdebt --duplicates    # Only duplication
/techdebt --security      # Only security issues
/techdebt --complexity    # Only complexity hotspots
/techdebt --deadcode      # Only dead code

# Auto-fix mode (interactive)
/techdebt --fix

アーキテクチャ

高速に分析するため、常に並列サブエージェントを使用します。

Main Agent (orchestrator)
    │
    ├─> Subagent 1: Duplication Scanner
    ├─> Subagent 2: Security Scanner
    ├─> Subagent 3: Complexity Scanner
    └─> Subagent 4: Dead Code Scanner

    ↓ All run in parallel (2-15s depending on scope)

Main Agent: Consolidate findings → Rank by severity → Generate report

メリット:

• 🚀 並列実行 — すべてのスキャンを同時に実行します
• 🧹 メインコンテキストをクリーンに維持 — 分析作業による汚染がありません
• 💪 スケーラブル — 大規模なコードベースも効率的に処理します
• 🎯 高速 — 小規模な差分でも並列化の効果が得られます

ワークフロー

ステップ 1：対象範囲を決定する

デフォルト（フラグなし）：

• 前回のコミット以降に変更されたファイルをスキャンします：git diff --name-only HEAD
• セッション終了時に実行する高速ワークフロー（約 2～3 秒）
• 「作業の締めくくり」に最適です

詳細スキャン（--deep フラグ）：

• コードベース全体をスキャンします
• 包括的な分析を行います（中規模プロジェクトで約 10～15 秒）
• リファクタリング時やメジャーリリースの準備時に使用します

特定のカテゴリー（例：--duplicates）：

• 指定されたスキャナーのみを実行します
• 対象を絞った分析に最速の方法です

ステップ 2：並列サブエージェントを起動する

4 つのサブエージェントを同時に起動します（カテゴリーが指定されている場合は、該当するサブエージェントのみ）。

サブエージェント 1：重複スキャナー

• タスク：AST 類似度を使用して、重複したコードブロックを見つけます
• ツール：ast-grep、構造検索、トークン分析
• 出力：類似度スコア付きの重複コードブロック一覧

サブエージェント 2：セキュリティスキャナー

• タスク：セキュリティ上の脆弱性やアンチパターンを検出します
• 確認項目：ハードコードされたシークレット、SQL インジェクション、XSS、安全でない暗号化
• 出力：深刻度と修正方法を含むセキュリティ上の検出事項

サブエージェント 3：複雑度スキャナー

• タスク：複雑すぎる関数やメソッドを特定します
• 指標：循環的複雑度、ネストの深さ、関数の長さ
• 出力：リファクタリングの提案を含む複雑度の高い箇所

サブエージェント 4：デッドコードスキャナー

• タスク：未使用のインポート、変数、到達不能なコードを見つけます
• 確認項目：未使用のインポート、デッドブランチ、参照されていない関数
• 出力：安全な削除手順を含むデッドコード一覧

サブエージェントの指示テンプレート：

Scan {scope} for {category} issues.

## Domain Knowledge
Before scanning, read the relevant skill for deeper patterns:
- Security scanner: Read skills/security-ops/references/owasp-top10-a01-a05.md and owasp-top10-a06-a10.md
- Complexity scanner: Read skills/refactor-ops/SKILL.md

Scope: {file_list or "entire codebase"}
Language: {detected from file extensions}
Focus: {category-specific patterns}

Output format:
- File path + line number
- Issue description
- Severity (P0-P3)
- Suggested fix (if available)

Use appropriate tools:
- Duplication: ast-grep for structural similarity
- Security: pattern matching + known vulnerability patterns
- Complexity: cyclomatic complexity calculation
- Dead Code: static analysis for unused symbols

ステップ 3：検出事項を統合する

メインエージェントはすべてのサブエージェントから結果を収集し、次の処理を行います。

1. 重複を排除する — カテゴリー間で重複する検出事項を取り除きます
2. 深刻度順にランク付けする：
   • P0（重大）： セキュリティ上の脆弱性、作業を妨げる問題
   • P1（高）： 大規模な重複、高い複雑度
   • P2（中）： 軽微な重複、中程度の複雑度
   • P3（低）： デッドコード、スタイル上の問題
3. ファイルごとにグループ化する — 検出事項を影響を受けるファイル別に整理します
4. 負債スコアを算出する — 技術的負債の全体指標を算出します

ステップ 4：レポートを生成する

実行可能なレポートを作成します。

# Tech Debt Report

**Scope:** {X files changed | Entire codebase}
**Scan Time:** {duration}
**Debt Score:** {0-100, lower is better}

## Summary

| Category | Findings | P0 | P1 | P2 | P3 |
|----------|----------|----|----|----|----|
| Duplication | X | - | X | X | - |
| Security | X | X | - | - | - |
| Complexity | X | - | X | X | - |
| Dead Code | X | - | - | X | X |

## Critical Issues (P0)

### {file_path}:{line}
**Category:** {Security}
**Issue:** Hardcoded API key detected
**Impact:** Credential exposure risk
**Fix:** Move to environment variable

## High Priority (P1)

### {file_path}:{line}
**Category:** {Duplication}
**Issue:** 45-line block duplicated across 3 files
**Impact:** Maintenance burden, inconsistency risk
**Fix:** Extract to shared utility function

[... continue for all findings ...]

## Recommendations

1. Address all P0 issues before merge
2. Consider refactoring high-complexity functions
3. Remove dead code to reduce maintenance burden

## Auto-Fix Available

Run `/techdebt --fix` to interactively apply safe automated fixes.

ステップ 5：自動修正モード（任意）

--fix フラグが指定されている場合：

1. 安全な修正を特定する：

   • デッドインポートの削除（安全）
   • 単純な重複コードの抽出（レビューが必要）
   • フォーマットの修正（安全）

2. 対話形式で確認する：

   Fix: Remove unused import 'requests' from utils.py:5
   [Y]es / [N]o / [A]ll / [Q]uit
   

3. 変更を適用する：

   • 確認済みの修正をファイルに適用します
   • 変更の git diff を表示します
   • コミットするか確認します

安全ルール：

• セキュリティ上の問題は自動修正しません（手動レビューが必要です）
• 複雑度は自動修正しません（設計上の判断が必要です）
• ユーザーが明示的に確認した場合のみ自動修正します

検出パターン

重複

AST 類似度検出：

• 構造パターンマッチングに ast-grep を使用します
• 構造上の類似度が 80% を超えるコードブロックを検出します
• 些細な違い（変数名、空白）は無視します

トークンベースの分析：

• トークン列を比較して完全一致する重複を検出します
• 最小しきい値：連続する 6 行
• ファイル間で類似する重複をグループ化します

しきい値：

• P1：3 か所以上で 30 行以上が重複
• P2：2 か所以上で 15 行以上が重複
• P3：2 か所で 6 行以上が重複

セキュリティ

パターン検出：

パターン	重大度	例
ハードコードされたシークレット	P0	API_KEY = "sk-..."
SQL インジェクションのリスク	P0	f"SELECT * FROM users WHERE id={user_id}"
安全でない暗号化	P0	hashlib.md5()、トークンに random.random() を使用
パストラバーサル	P0	検証せずに open(user_input) を使用
XSS の脆弱性	P0	HTML 内のエスケープされていないユーザー入力
Eval/exec の使用	P1	eval(user_input)
脆弱なパスワード	P2	ハードコードされたデフォルトのパスワード

言語固有のチェック：

• Python：pickle の使用、SafeLoader を指定しない yaml.load()
• JavaScript：eval()、ユーザーデータを含む innerHTML
• SQL：クエリでの文字列連結

複雑さ

メトリクス：

メトリクス	P1 のしきい値	P2 のしきい値
循環的複雑度	>15	>10
関数の長さ	>100 行	>50 行
ネストの深さ	>5 レベル	>4 レベル
パラメーター数	>7	>5

リファクタリングの提案：

• 長い関数からメソッドを抽出する
• パラメーターが多い場合はパラメーターオブジェクトを導入する
• ガード節を使って条件分岐を簡潔にする
• 深くネストしたロジックを分割する

デッドコード

検出方法：

• 未使用のインポート（言語固有のリンター）
• 到達不能コード（return/break/continue の後）
• 未使用の変数（書き込まれているが、読み取られていないもの）
• 孤立した関数（コードベース内で一度も呼び出されないもの）

安全に削除するための条件：

• 外部からの参照が見つからない
• 公開 API の一部ではない
• 動的にインポート／呼び出しされない

言語サポート

Tier 1（完全サポート）：

• Python：ast-grep、radon、pylint
• JavaScript/TypeScript：ast-grep、eslint、jscpd
• Go：gocyclo、golangci-lint
• Rust：clippy、cargo-audit

Tier 2（基本サポート）：

• Java、C#、Ruby、PHP：パターンベースの検出のみ

言語の検出：

• ファイル拡張子から自動検出する
• 言語ごとに適切なツールを使用する
• 特定のツールが利用できない場合は、汎用パターンにフォールバックする

統合パターン

セッション終了時の自動化

ワークフローに追加します：

## Session Wrap-Up Checklist

- [ ] Run `/techdebt` to scan changes
- [ ] Address any P0 issues found
- [ ] Create tasks for P1/P2 items
- [ ] Commit clean code

コミット前フック

.claude/hooks/pre-commit.sh を作成します：

#!/bin/bash
# Auto-run tech debt scan before commits

echo "🔍 Scanning for tech debt..."
claude skill techdebt --quiet

if [ $? -eq 1 ]; then
  echo "❌ P0 issues detected. Fix before committing."
  exit 1
fi

echo "✅ No critical issues found"

CI/CD との統合

プルリクエストで詳細スキャンを実行します：

# .github/workflows/techdebt.yml
name: Tech Debt Check
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tech debt scan
        run: claude skill techdebt --deep --ci

高度な使用方法

ベースラインの追跡

負債を経時的に追跡します：

# Initial baseline
/techdebt --deep --save-baseline

# Compare against baseline
/techdebt --compare-baseline
# Output: "Debt increased by 15% since baseline"

ベースラインは .claude/techdebt-baseline.json に保存されます：

{
  "timestamp": "2026-02-03T10:00:00Z",
  "commit": "a28f0fb",
  "score": 42,
  "findings": {
    "duplication": 8,
    "security": 0,
    "complexity": 12,
    "deadcode": 5
  }
}

カスタムパターン

.claude/techdebt-rules.json にプロジェクト固有のパターンを追加します：

{
  "security": [
    {
      "pattern": "TODO.*security",
      "severity": "P0",
      "message": "Security TODO must be resolved"
    }
  ],
  "complexity": {
    "cyclomatic_threshold": 12,
    "function_length_threshold": 80
  }
}

レポート形式

/techdebt --format=json     # JSON output for tooling
/techdebt --format=markdown # Markdown report (default)
/techdebt --format=sarif    # SARIF for IDE integration

トラブルシューティング

問題：スキャンがタイムアウトする

• 解決策：--deep は小規模なモジュールにのみ使用するか、タイムアウトを延長します
• 検討事項：大規模なコードベースを小さなスキャン単位に分割します

問題：誤検出が多すぎる

• 解決策：.claude/techdebt-rules.json のしきい値を調整します
• 検討事項：--ignore-patterns フラグを使ってテストファイルを除外します

問題：依存関係（ast-grep など）が見つからない

• 解決策：npm install -g @ast-grep/cli でツールをインストールするか、該当カテゴリをスキップします
• フォールバック：専用ツールがなくても、パターンベースの検出は機能します

ベストプラクティス

1. 各セッションの終了時に実行する - コンテキストが新鮮なうちに負債を検出します
2. P0 は直ちに対処する - 重大な問題をコミットしないでください
3. P1/P2 のタスクを作成する - 技術的負債をバックログで追跡します
4. 傾向の把握にベースラインを使う - 負債の蓄積を経時的に監視します
5. CI/CD で自動化する - 負債がマージされるのを防ぎます
6. チームに周知する - 検出結果を共有し、リファクタリング戦略について話し合います

参考資料

関連項目：

• Anthropic の Agent Skills - サブエージェントのパターン
• references/patterns.md - 言語固有の負債パターン
• references/severity-guide.md - 検出結果の重大度の評価方法