reclaim-code-entropy

コードのエントロピーを抑える

コードのエントロピーを、現在、維持する必要がある根拠のない保守対象として扱います。製品が整合性を保つ必要のある、追加の表現、状態、API、分岐、パッケージ、ポリシー、テストなどが該当します。

基本ルール：スキャナーが候補を提示し、削除を正当化できるのは、利用側、所有者、履歴、検証の証拠がある場合だけです。推測に基づく長いリストより、根拠のある削除を少数行うことを優先します。安全に削除できるものが見つからない場合も、妥当な結果です。

モードを選択する

• 「audit」「find」「review」「report」の場合は、調査のみを行い、優先順位を付けた候補を返します。編集は行いません。
• 「apply」「remove」「clean up」「simplify」「refactor」の場合は、依頼された削除のうち最も安全なものを実施し、検証します。
• 到達可能なユーザー機能、サポート対象の公開 API、永続化形式、互換性経路の削除は、製品上の判断として扱います。ユーザーがすでにその判断を明示している場合を除き、変更前に、ユーザーに見えるトレードオフを示します。

契約を確認する

1. リポジトリの指示と、適用範囲が最も近い同等の資料を読みます。AGENTS.md、CONTRIBUTING、アーキテクチャ文書、ADR/RFC/意思決定メモ、パッケージマニフェスト、テストのガイダンスが該当します。
2. git status を確認し、無関係な作業を保持します。コードを分類する前に、生成物、ベンダーコード、マイグレーション、フィクスチャ、公開パッケージのパスを特定します。
3. エントリーポイント、設定、レジストリ、依存性注入、イベント、キュー、永続化、プロセス／ワーカー、ワイヤープロトコルを通じて、実際のランタイムの流れを追跡します。
4. apply モードでは、リポジトリで実際に使われている範囲の狭い検証コマンドと広い検証コマンドを特定し、可能であれば妥当な範囲で変更前のベースラインを実行します。ベースラインに失敗がある場合、その後のチェックで証明できる範囲は限られます。回帰だと主張せず、その失敗を記録します。

信頼境界での検証、認可、セキュリティ制御、アクセシビリティの基本、データ損失防止、永続データとの互換性、リソースの静止状態を確立するクリーンアップを簡素化によって取り除いてはいけません。

エントロピーを調査する

明らかに未使用のシンボルだけでなく、大規模な本番コードや中核的な領域から調査を始めます。まずリポジトリ標準のツールを使います。rg --files、rg、コンパイラー／リンターの出力、依存関係マニフェスト、git log などが該当します。役立つ場合はインストール済みのデッドコード検出ツールや依存関係ツールを実行しますが、その結果はすべて手がかりとして扱います。

以下の候補クラスを探します。

1. 消費されていない表面：本番コードで利用側がない公開メソッド、エクスポート、イベント、設定キー、フック、パッケージ、レジストリ通知、プロトコルフィールド。
2. 重複して記録される事実：同じ事実を記録し、同期を保つ必要のある2つのイベント、キャッシュ、要約、状態ストア、スナップショット、アダプター。
3. 先回りしすぎた汎用化：設定されない調整項目、固定された機能フラグ、未使用のフォールバック、実装が1つしかないインターフェイス、放棄されたスタブ、所有者のいない拡張ポイント。
4. 余分な経路やレイヤー：1つの動作に対する複数の入口、転送だけを行うラッパー、処理を中継するだけのパッケージ、単一の呼び出し元を分かりにくくするヘルパー。
5. ライフサイクルの重複：ready、stopped、settled、flushed、disposed など、1つの遷移を表す複数のフラグ、センチネル、プロミス、キュー、コントローラー。
6. 配置を誤った防御処理：実際の信頼境界や所有権境界ではなく、同一プロセス内の型付き受け渡しを保護するコピー、フリーズ、バリデーター、ロールバック処理、敵対的オブジェクトのテスト。
7. 独自に実装した基盤機能：標準ライブラリ、ネイティブプラットフォーム、インストール済みの依存関係ですでに対応できるローカルのパーサー、リトライループ、glob 処理、フレーミング、差分計算、データ構造。
8. サポート目的だけの残骸：テストまたはドキュメントだけが利用しているコード、重複した期待出力、古い一覧、ランタイムコストや公開コストを生むデモ／テスト用パッケージ。
9. 追加後に放棄された残骸：実装はなくなったのに、フラグ、スキーマ、ドキュメント、テスト、互換性分岐、意思決定メモには記述が残っているもの。

重複と、必要な独立性を混同しないでください。バックエンド、アダプター、表現、ライフサイクルの仕組みを分けておくことが、意図的に契約を検証したり、異なる所有者を保護したりする場合があります。

候補を証明または却下する

各シンボル、動作、成果物について、次を行います。

1. リポジトリ全体で、そのシンボル、ファイルパス、パッケージ名、設定キー、イベント／ワイヤー文字列、別の呼び出し構文を検索します。
2. 見つかった箇所をすべて分類します。
   • 本番用：ランタイムソース、配布される設定、実際のエントリーポイント、マイグレーション、運用スクリプト。
   • 非本番用：テスト、ドキュメント、コメント、スナップショット、生成された期待出力。
   • 要確認：例、フィクスチャ、プラグイン、リフレクション、レジストリ、遅延インポート、コード生成、外部から利用されるエクスポート。分類する前に調査します。
3. 検索件数だけでなく、呼び出し元と呼び出し先も調査します。動的読み込み、文字列によるディスパッチ、ルート、プラグインマニフェスト、DI コンテナー、シリアライズ、環境変数をキーにした検索、外部パッケージとの契約を確認します。
4. 履歴と意思決定記録を読みます。その表層を生み出した問題は何か、その問題はまだ存在するか、元の根拠を上回る現在の証拠は何かを確認します。
5. 非同期コードまたは状態を持つコードの所有関係を図にします。各状態フラグ、破棄処理、キャンセル経路、準備完了を示す Promise、終端状態を、それぞれ固有の所有者または遷移に対応付けます。
6. 削除によって失われる機能や動作を明記します。答えが「観測可能なものはない」の場合も明記します。
7. 正味の削減量を見積もります。コード、対象コード専用のテスト、ドキュメント、設定、生成物、依存関係、削除される概念から、追加される置き換え用の接続処理やマイグレーションを差し引きます。
8. 単純化が誤っていた場合に失敗する、最小限のチェックを挙げます。

候補を監査出力で記録する場合は、次の簡潔な証拠記録を使用します。

[confidence / risk] candidate
evidence: production consumers; dynamic/public/compatibility checks; owning rationale
cut: exact code, artifacts, dependency, and concept removed
tradeoff: observable capability or behavior lost
verify: smallest decisive check; estimated net reduction

根拠のある削減を実装する

1. 一度に一つの所有境界で作業します。呼び出し元を一つずつ修正するのではなく、エントロピーの共通の発生源を修正します。
2. 古くなった契約を宣言、実装、分岐、削除対象の動作専用のテスト、エクスポート、設定、ドキュメント、例、スナップショット、生成された一覧、依存関係のエントリーまで、一貫して削除します。
3. 残す観測可能な契約のテストは維持します。テストは証拠であり、手を付けてはならない仕様でも、行数を減らすために捨ててよいものでもありません。
4. 重複した状態を、重要な表現に集約します。二つの事実を同期するラッパーに置き換えてはいけません。
5. まず削除を検討し、次に標準ライブラリやネイティブ機能、最後にすでにインストールされている依存関係を検討します。追加する依存関係は、それによって削減される実装と専用テストの負担が、接続処理とサプライチェーンのコストを上回る場合に限ります。
6. 互換性を維持する義務がない場合は、互換性シムを避けます。その義務がある場合は、経路を維持するか、黙って削除するのではなく、明示的なマイグレーションを設計します。
7. レビューしやすく、元に戻せる単位に保ちます。無関係なユーザー変更を破棄してはいけません。

行数が正味で減ることは、削減の証拠であって目標ではありません。安全な単純化のために小さなテストやマイグレーションが増えることもあります。大幅に削除できても、それが誤りである場合はあります。

結果を検証する

実質的な各バッチの後に、次の作業を行います。

1. 削除したシンボル、文字列、パス、古くなったドキュメントがないか、もう一度検索します。
2. まず最も範囲を絞った決定的なテストを実行し、その後、リポジトリで関連する広範な型チェック、リンティング、テスト、ビルド、コード生成、またはスモークテストのゲートを実行します。
3. 候補を生成した静的アナライザーを再実行します。
4. Git が利用可能な場合は git diff --check を実行し、意図せず変更範囲が広がっていないか、差分全体を確認します。
5. 公開、永続化、ワイヤー、ユーザーから見える各境界での動作を比較します。パフォーマンスに関する主張を行う場合に限り、パフォーマンスを測定します。

検証に失敗した場合は、その候補が不可欠だったのか、実装が不完全だったのか、それともベースラインがすでに失敗していたのかを特定します。現在のバッチだけを元に戻すか、検証を修正します。削除を無理に通すために、意味のあるチェックを弱めてはいけません。

結果を報告する

監査では、信頼度、リスク、保守負担の純削減量を基準に、有力な候補を順位付けします。証拠が不足しているものの、追加調査が可能な有望な候補は、実行可能な証拠が不足している場合に限り記載します。

変更を適用した場合は、次の内容を報告します。

• 削除した契約または重複した真実の内容
• 測定可能な範囲での、削除したファイル、行、依存関係、概念
• ユーザーから見える機能や互換性に生じた変更
• 実行した検証の正確な内容と結果
• 意図的に残した有望な候補と、その理由