dead-code-sweep

デッドコードの一掃

コードベース内のデッドコード、重複した実装、孤立した成果物を体系的に特定して削除します。特に、コンテキストウィンドウが限られたコーディングエージェントによって保守されているコードベースを対象とします。

エージェントが保守するコードベースで不要なコードが蓄積する理由

コーディングエージェントが一度に扱えるコンテキストウィンドウは限られています。リファクタリングの際、次のようなことがよく起こります。

• 元の実装を見つけて削除せずに、機能を再実装する
• すでに存在しないインターフェースの互換性シムを残す
• ロジックをインライン化した後に、ヘルパー関数を放置する
• 置き換えたファイルを削除せずに、新しいファイルを作成する
• モジュール間で型定義を重複させる
• リファクタリングの途中で使わなくなったシンボルのインポートを残す

こうした不要なコードは蓄積していきます。孤立した成果物は、その後のエージェント（または人間）を惑わせ、何もしていないコードを読むためにコンテキストの予算を浪費させます。

ワークフロー

フェーズ 1：範囲の決定と棚卸し

分析範囲を決定します。

ユーザーが範囲を指定している場合（ディレクトリ、ファイルパターン、モジュール）は、すべての分析をその範囲に限定します。

範囲が指定されていない場合は、コードベース全体を分析します。まず、プロジェクト構成を確認します。

1. 主な言語とフレームワークを特定する
2. エントリーポイント（メインファイル、ルート定義、エクスポートされたモジュール、テストランナー）を把握する
3. ビルドシステムと依存関係の設定を確認する
4. モノレポ構成かどうかを確認し、各パッケージを個別に分析する

簡潔な棚卸しを作成します。

Language(s): TypeScript, Python
Entry points: src/index.ts, src/cli.ts
Build: esbuild via package.json scripts
Packages: 1 (single package)
Estimated LOC: ~4,200

フェーズ 2：検出

サブエージェントを並行して起動し、デッドコードの種類ごとにスキャンします。検出パターンの全一覧については、references/cruft-patterns.md を読んでください。

検出は、次のトラックに分けて行います。

トラック	検出対象
孤立したファイル	他のファイルからインポート、読み込み、参照されていないファイル
未使用のエクスポート	他の場所から一度もインポートされていない、エクスポート済みのシンボル（関数、クラス、型、定数）
重複した実装	異なる名前で同じ処理を行う複数の関数やクラス
古い互換性コード	違いがなくなったインターフェースをつなぐシム、アダプター、ラッパー、再エクスポート
デッドブランチ	実行できない条件分岐（常に真／偽となるガード、到達不能な return 文）
孤立したテスト	すでに存在しない関数やモジュールをテストするテストファイル
孤立した依存関係	ソースコード内で一度もインポートされていない依存関係マニフェスト内のパッケージ

各トラックで、サブエージェントは次の作業を行います。

1. そのトラックに固有の検出方法を確認するため、references/cruft-patterns.md を読む
2. Grep と Glob を使用してコードベースを検索する
3. 参照をたどって候補を検証する。シンボルがデッドと見なせるのは、有効なコードパスから到達するものがゼロの場合に限られる
4. ファイルパス、行範囲、根拠を添えて検出結果を記録する

検証は非常に重要です。 次のような一般的な誤検出に注意してください。

• 動的ディスパッチ、リフレクション、または文字列による検索で使われるシンボル
• フレームワークの規約によるエクスポート（例：Next.js のページコンポーネント、pytest のフィクスチャ、Rails の規約）
• 外部の利用者向けに意図された公開 API
• 機能フラグや環境チェックで条件付きにインポートされるもの
• デコレーターやプラグインによって登録されたハンドラー
• package.json の bin フィールドから参照される CLI エントリーポイント
• テンプレートや JSX で動的な文字列として参照される CSS クラス名

判断に迷う場合は、「確認済みのデッド」ではなく「要確認」と記録してください。

フェーズ 3：レポート

すべての検出結果を .claude/dead-code-report.md の構造化されたレポートにまとめます。

検出結果は、確信度の高い順に分類し、その後カテゴリごとに整理します。

# Dead Code Sweep Report

**Scope:** [full codebase | specific path]
**Date:** [date]
**Estimated removable lines:** [count]

## Confirmed Dead (high confidence)

### Orphaned Files
- `src/utils/old-parser.ts` — Not imported anywhere. Superseded by `src/parser/index.ts`.
- ...

### Unused Exports
- `formatDate()` in `src/helpers.ts:42-58` — Exported but zero imports across codebase.
- ...

[...other categories...]

## Needs Review (uncertain)

### Possibly Dynamic
- `handleLegacyEvent()` in `src/events.ts:91` — No static imports, but may be registered dynamically.
- ...

検出結果ごとに、次の情報を記載します。

• ファイルパスと行範囲
• 対象（関数、クラス、ファイル、型、定数、依存関係）
• デッドと思われる理由（インポートがない、参照がない、X に置き換えられたなど）
• 確信度（確認済み／要確認）

フェーズ 4：承認を得てクリーンアップ

レポートの概要をユーザーに提示し、削除する前に承認を求めます。

AskUserQuestion を使って、カテゴリ別に調査結果を提示します。

Found 12 confirmed dead items and 3 needing review.

Confirmed dead by category:
- 3 orphaned files (~280 lines)
- 5 unused exports (~120 lines)
- 2 redundant implementations (~90 lines)
- 2 orphaned dependencies

Which categories should I clean up?

選択肢：確認済みの項目をすべて削除／カテゴリを選択／各項目を確認／クリーンアップをスキップ

承認された各カテゴリについて、次の手順を実行します。

1. デッドコードを削除します
2. 削除したコードを参照していたインポートを整理します
3. クリーンアップ後に残った空のファイルを削除します
4. マニフェストから孤立した依存関係を削除します
5. プロジェクトの lint／型チェック／ビルドコマンドを実行し、問題がないことを確認します

削除によってビルドエラーまたは型エラーが発生した場合は、その削除を直ちに元に戻し、該当項目を「要確認」に移します。

クリーンアップ後、削除した項目と残した項目をレポートに反映します。

検出の原則

疑わしい箇所ではなく、エントリーポイントからたどる

疑わしいシンボルから始めて使用されていることを証明しようとするのではなく、既知のエントリーポイントから始め、到達可能な範囲をたどります。到達可能性に基づく方法では、見落としが少なくなります。

モジュールの境界を尊重する

パッケージの公開 API からエクスポートされたシンボルは、このリポジトリからは見えない外部コードで使われている可能性があります。外部の利用者がいるライブラリやパッケージを分析する場合、「確認済み」として指摘するのは内部の（公開 API ではない）デッドコードに限ります。公開 API のデッドコードは「要確認」として指摘します。

個々の箇所だけでなく、まとまりにも注目する

エージェントが生成した不要コードは、まとまって存在する傾向があります。デッド関数が見つかったら、その周辺も調べます。エージェントはリファクタリング中にセクション全体を放棄した可能性があります。デッドファイルの隣に、同じコミットで作成されたデッドファイルがあることもよくあります。

シグナルとして Git の履歴を活用する

可能な場合は、疑わしいコードが最後に実質的な変更を受けた時期を確認します。複数のリファクタリングコミットを経ても変更されていないコードは、デッドコードである可能性が高くなります。git log --follow を使って名前の変更をたどり、置き換えられたファイルを検出します。