refactor-clean

Refactor Clean

保守的なクリーンアップのループを使用します。実行時や外部の利用側に隠れた依存がある可能性を否定できないコードは、削除せずに残すことを優先してください。

ワークフロー

1. ベースラインを確立します。
2. 言語に適したツールでデッドコードを検出します。
3. 検出結果を SAFE、CAUTION、DANGER に分類します。
4. SAFE の項目を一度に1つ削除します。
5. 削除のたびに検証を再実行します。
6. CAUTION の項目は、手を加える前に調査します。
7. ユーザーが詳細な調査を明示的に希望しない限り、DANGER の項目は対象外にします。
8. デッドコードのクリーンアップが安定してから、明らかな重複を統合します。

ベースラインを確立する

• まず意味のある最小限のベースラインを実行し、その後、リポジトリで必要なより広範なプロジェクトチェックを実行します。
• クリーンアップを始める前に、テストスイートがすでに失敗しているかどうかを記録します。
• 事前から存在していた問題が新たに見つかっても、クリーンアップが原因だと判断しないでください。
• 対象領域のベースラインが失敗している場合は、コードを削除する前に作業を中断し、ユーザーに伝えてください。

デッドコードを検出する

エコシステムに適したツールを選びます。可能な限り、プロジェクトのパッケージマネージャーや既存のスクリプトを優先してください。

ツール	検出するもの	コマンド
knip	未使用のエクスポート、ファイル、依存関係	npx knip
depcheck	未使用の npm 依存関係	npx depcheck
ts-prune	未使用の TypeScript エクスポート	npx ts-prune
vulture	未使用の Python コード	vulture src/
deadcode	未使用の Go コード	deadcode ./...
cargo-udeps	未使用の Rust 依存関係	cargo +nightly udeps

専用ツールが利用できない場合は、対象を絞って検索します。

• エクスポートされたシンボルとファイルを探します。
• インポート、require、動的インポート、ルート参照、設定参照、文字列による検索を調べます。
• 「明らかな参照がゼロ」であることは手がかりであり、証拠ではないと考えてください。

検出結果を分類する

編集する前に、すべての検出結果を安全性の段階に分類します。

段階	典型的な例	デフォルトの対応
SAFE	未使用の内部ユーティリティ、プライベートヘルパー、未使用のテスト／ヘルパー、呼び出し元のないラッパー関数	検証しながら削除
CAUTION	コンポーネント、フック、API ルート、ミドルウェア、サーバーアクション、ジョブ、CLI コマンド	まず実行時の使用状況と間接的な使用状況を調査
DANGER	設定ファイル、エントリーポイント、エクスポートされた型、スキーマファイル、生成コードとの境界、公開 API	ユーザーが詳細な作業を依頼しない限り対象外

以下のいずれかに該当する場合は、よりリスクの高い段階に分類してください。

• 動的なインポートパス
• リフレクションまたはレジストリによる検索
• 文字列によるルーティングまたはコマンドのディスパッチ
• フレームワークによる自動検出
• パッケージの公開エクスポート
• 外部の利用側またはリポジトリをまたぐ使用

安全な削除ループ

SAFE の項目ごとに、次の手順を実行します。

1. ベースラインの検証を実行します。
2. 外科的な編集で、項目を正確に1つだけ削除します。
3. 関連するテストをすぐに再実行します。
4. テストが失敗した場合は削除を元に戻し、その項目を対象外にします。
5. テストが成功した場合は、次の項目に進みます。

削除はアトミックに行います。無関係な複数の削除を1回の検証サイクルにまとめないでください。

元に戻す必要がある場合：

• テスト対象の項目だけを復元します。
• 無関係なユーザーの変更に影響しない、非破壊的な復元方法を優先します。
• 失敗を要約に記録し、次に進みます。

注意が必要な項目への対応

CAUTION の項目を削除する前に、次の点を明示的に確認します。

• import() または require() の使用
• 設定、ルート、レジストリ、機能フラグ、テスト内の文字列参照
• パッケージまたはアプリのエントリーポイントからの再エクスポート
• モジュールが公開済みまたは共有されている場合の外部利用者
• ファイル名や配置場所に基づいてファイルを自動読み込みするフレームワークの規約

間接的な使用がないことを確認し、検証にも成功した場合に限り、CAUTION の項目を削除してください。

重複の統合

不要コードの削除後に検証がすべて成功したら、リスクの低い統合を検討します。

• 同じ動作をする、ほぼ重複した関数
• 冗長な型定義
• ポリシーや使いやすさを向上させない、処理をそのまま通すだけのラッパー
• 見つけやすさや互換性の向上につながらない再エクスポート

このフェーズは不要コードの削除とは分けてください。統合によって動作が変わる場合は、クリーンアップとして扱わず、そのことを明示してください。

報告

最後に、次の項目を含む短いクリーンアップ報告をまとめてください。

• 削除した関数、ファイル、依存関係
• スキップした項目とその理由
• 削除した行数の概算
• 実行した検証コマンド
• 最終的な成功／失敗の状態

必要に応じて、次の形式を使用してください。

Dead Code Cleanup
----------------------------
Deleted:   12 unused functions
           3 unused files
           5 unused dependencies
Skipped:   2 items (verification failed)
Saved:     ~450 lines removed
----------------------------
All tests passing

ルール

• ベースラインの検証を実行する前に、コードを削除しないでください。
• 一度に削除する項目は1つにしてください。
• 判断に確信が持てない項目は、推測せずスキップしてください。
• 削除の手順に大規模なリファクタリングを混在させないでください。
• 削除に失敗した箇所を復元する際は、無関係なユーザーの変更を保持してください。
• CAUTION または DANGER の項目が残っている場合は、残存するリスクを明確にしてください。