dead-code-detector

デッドコード検出ツール

Python、TypeScript、Rust のコードベース全体で未使用のコードを見つけて削除します。

自己進化型スキル：このスキルは使用を通じて改善されます。指示に誤りがある場合、パラメーターがずれている場合、または回避策が必要になった場合は、先延ばしにせず、このファイルをすぐに修正してください。実際に再現可能な問題がある場合のみ更新してください。

言語別ツール

言語	ツール	検出対象
Python	vulture v2.14+	未使用のインポート、関数、クラス、変数
TypeScript	knip v5.0+	未使用のエクスポート、依存関係、ファイル
Rust	cargo clippy + rustc の lint	未使用の関数、インポート、dead_code 警告

これらのツールを使う理由

• vulture：AST ベースで、信頼度スコア（60～100%）とホワイトリストに対応
• knip：ts-prune の後継（メンテナンスモード）、モノレポを認識、自動修正に対応
• cargo clippy：Rust ツールチェーンに組み込み済みで、追加の依存関係は不要

---

このスキルを使うタイミング

次のような場合にこのスキルを使います。

• リリース前にコードベースを整理する
• メンテナンスの負担を減らすためにリファクタリングする
• バンドルサイズやコンパイル時間の問題を調査する
• 実際に使われているコードを把握するためにプロジェクトに参加する

対象外：コードの重複（quality-tools:code-clone-assistant を使ってください）

---

クイックスタートのワークフロー

Python（vulture）

# Step 1: Install
uv pip install vulture

# Step 2: Scan with 80% confidence threshold
vulture src/ --min-confidence 80

# Step 3: Generate whitelist for false positives
vulture src/ --make-whitelist > vulture_whitelist.py

# Step 4: Re-scan with whitelist
vulture src/ vulture_whitelist.py --min-confidence 80

TypeScript（knip）

# Step 1: Install (project-local recommended)
bun add -d knip

# Step 2: Initialize config
bunx knip --init

# Step 3: Scan for dead code
bunx knip

# Step 4: Auto-fix (removes unused exports)
bunx knip --fix

Rust（cargo clippy）

# Step 1: Scan for dead code warnings
cargo clippy -- -W dead_code -W unused_imports -W unused_variables

# Step 2: For stricter enforcement
cargo clippy -- -D dead_code  # Deny (error) instead of warn

# Step 3: Auto-fix what's possible
cargo clippy --fix --allow-dirty

---

信頼度と誤検出

Python（vulture）

信頼度	意味	対応
100%	解析対象ファイル内で未使用であることが確実	安全に削除できます
80-99%	未使用である可能性が非常に高い	削除前に確認してください
60-79%	未使用の可能性あり（動的呼び出し、フレームワーク）	意図的な場合はホワイトリストに追加してください

よくある誤検出（フレームワークから呼び出されるコード）：

• ルートハンドラー／コントローラーメソッド（Web フレームワークから呼び出される）
• テストフィクスチャとセットアップ用ユーティリティ（テストランナーから呼び出される）
• パブリック API のエクスポート（利用側向けに再エクスポートされる）
• バックグラウンドジョブのハンドラー（タスクキュー／スケジューラーから呼び出される）
• イベントリスナー／フック（イベントシステムから呼び出される）
• シリアライズのコールバック（エンコード／デコード時に呼び出される）

TypeScript（knip）

Knip は、精度を高めるために TypeScript の型システムを使用します。knip.json で設定します。

{
  "entry": ["src/index.ts"],
  "project": ["src/**/*.ts"],
  "ignore": ["**/*.test.ts"],
  "ignoreDependencies": ["@types/*"]
}

Rust

属性を使って誤検出を抑制します。

#[allow(dead_code)]  // Single item
fn intentionally_unused() {}

// Or module-wide
#![allow(dead_code)]

---

CI との統合

Python（pyproject.toml）

[tool.vulture]
min_confidence = 80
paths = ["src"]
exclude = ["*_test.py", "conftest.py"]

TypeScript（package.json）

{
  "scripts": {
    "dead-code": "knip",
    "dead-code:fix": "knip --fix"
  }
}

Rust（Cargo.toml）

[lints.rust]
dead_code = "warn"
unused_imports = "warn"

---

リファレンスドキュメント

詳しい情報については、次を参照してください。

• Python のワークフロー - vulture の高度な使い方
• TypeScript のワークフロー - knip の設定
• Rust のワークフロー - clippy の lint カテゴリー

---

トラブルシューティング

問題	原因	解決策
フレームワークから呼び出されたコードが報告される	フレームワークのマジック／コールバック	ホワイトリストまたは除外設定に追加
動的に読み込まれるコードが検出されない	静的なエントリーポイントに含まれていない	プラグイン／拡張機能のディレクトリを含めるよう、エントリーポイントを設定する
テスト専用のヘルパーに警告が出る	テストコードが別途コンパイルされる	条件付きコンパイルまたはテスト専用の除外を使用する
誤検知が多すぎる	しきい値が低すぎる	信頼度のしきい値を上げるか、無視パターンを設定する
型のみの参照が見つからない	コンパイル時にのみ使用される	最新のツールの多くは対応しています。ツールのバージョンを確認してください

---

複数の視点による検証（重要）

重要：検出された「デッドコード」を削除する前に、複数の視点から調査結果を検証するため、並行してサブエージェントを起動してください。デッドコードは、実際には未実装の機能や不完全な統合である可能性があります。

分類マトリックス

検出タイプ	本当のデッドコード	未実装の機能	不完全な統合
未使用の呼び出し可能要素	呼び出し元、テスト、ドキュメントがない	TODO／FIXMEがある、仕様書で参照されている	呼び出しチェーンが一部存在する
未使用のエクスポート／公開要素	どこからもインポートされていない	公開APIに含まれ、ドキュメント化されている	同階層のモジュールで使用されている
未使用のインポート／インクルード	タイポ、リファクタリングで不要になった	副作用のために必要	型のみ、またはコンパイル時のみ
未使用のバインディング	代入されているが、一度も読み取られない	将来のためのプレースホルダー	デバッグ／計測機能が削除された

検証ワークフロー

検出ツールの実行後、次の並行サブエージェントを起動してください：

┌─────────────────────────────────────────────────────────────────┐
│                    Dead Code Findings                           │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Intent Agent    │ │ Integration     │ │ History Agent   │
│                 │ │ Agent           │ │                 │
│ - Check TODOs   │ │ - Trace call    │ │ - Git blame     │
│ - Search specs  │ │   chains        │ │ - Commit msgs   │
│ - Find issues   │ │ - Check exports │ │ - PR context    │
│ - Read ADRs     │ │ - Test coverage │ │ - Author intent │
└─────────────────┘ └─────────────────┘ └─────────────────┘
          │                   │                   │
          └───────────────────┼───────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              AskUserQuestion: Confirm Classification            │
│  [ ] True dead code - safe to remove                            │
│  [ ] Unimplemented - create GitHub Issue to track               │
│  [ ] Incomplete - investigate integration gaps                  │
│  [ ] False positive - add to whitelist                          │
└─────────────────────────────────────────────────────────────────┘

エージェントへのプロンプト

意図エージェント（予定されている使用箇所を検索）：

Search for references to [IDENTIFIER] in:
1. TODO/FIXME/HACK comments in codebase
2. Issue tracker (open and closed issues)
3. Design documents and architecture decision records
4. README and project documentation files
Report: Was this code planned but not yet integrated?

統合エージェント（実行パスをたどる）：

For [IDENTIFIER], analyze:
1. All module import/include/use statements
2. Runtime module loading mechanisms (lazy loading, plugins)
3. Framework-invoked patterns (metadata attributes, config bindings, annotations)
4. Test files that may exercise this code path
Report: Is there a partial or indirect call chain?

履歴エージェント（由来を調査）：

For [IDENTIFIER], check:
1. VCS blame/annotate - who wrote it and when
2. Commit message - what was the stated intent
3. Code review / merge request context - was it part of larger feature
4. Recent commits - was calling code removed or refactored
Report: Was this intentionally orphaned or accidentally broken?

例：検出結果の検証

# Step 1: Run detection tool for your language
<tool> <source-path> --confidence-threshold 80 > findings.txt

# Step 2: For each high-confidence finding, spawn validation
# (Claude Code will use Task tool with Explore agents)

検出結果の例：unused function 'calculate_metrics' (src/analytics.py:45)

複数エージェントによる調査結果：

• 意図エージェント：src/dashboard.py:12に「ここでcalculate_metricsを統合する」というTODOを発見
• 統合エージェント：関数はtests/test_analytics.pyでインポートされていますが、テストはskip／pendingとしてマークされています
• 履歴エージェント：MR #234「分析機能の基盤を追加」で追加され、ダッシュボードとの統合は保留されています

結論：デッドコードではありません。未実装の機能です。追跡用のIssueを作成してください。

ユーザー確認フロー

エージェントによる分析後、multiSelect: trueを指定してAskUserQuestionを使用します：

AskUserQuestion({
  questions: [
    {
      question: "How should we handle these findings?",
      header: "Action",
      multiSelect: true,
      options: [
        {
          label: "Remove confirmed dead code",
          description: "Delete items verified as truly unused",
        },
        {
          label: "Create issues for unimplemented",
          description: "Track planned features in GitHub Issues",
        },
        {
          label: "Investigate incomplete integrations",
          description: "Spawn deeper analysis for partial implementations",
        },
        {
          label: "Update whitelist",
          description: "Add false positives to tool whitelist",
        },
      ],
    },
  ],
});

リスク分類

リスクレベル	基準	対応
低	信頼度100％、どこにも参照がなく、6か月以上前のコード	VCSコミットとともに自動削除
中	信頼度80～99％、間接参照が一部ある	まずエージェントで検証する
高	信頼度80％未満、最近のコード、テストカバレッジがある	手動レビューが必要
重大	公開APIの表面、ドキュメント化されている、外部の依存先がある	自動削除は絶対に行わない

参考資料

• vulture GitHub
• knip のドキュメント
• Effective TypeScript：knip を使う
• Rust の dead_code lint
• DCE-LLM の研究論文（新たに登場した LLM ベースのアプローチ）

実行後の振り返り

このスキルの実行後、終了する前に以下を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、原因となった指示またはエラーテーブルを修正してください。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを合わせて更新してください。
3. 回避策が必要でしたか？ — 異なるフラグや追加手順などの工夫が必要だった場合は、次回同じ回避策が不要になるよう、この SKILL.md を更新してください。

問題が実際に発生し、再現可能な場合に限り更新してください。推測に基づいて更新しないでください。