gjalla-cleanup-audit

クリーンアップ監査

保守コストを発生させているコードや、新しく参加したエージェントや人間を混乱させているコードを見つけます。多くの場合、使われていない、重複している、または過度に複雑になっていることが原因です。

削除する前に、不要であることを証明してください。 grep ではすべての参照を検出できるわけではありません。十分な確信を持って検証せずにコードを削除すると、本番環境でインシデントが発生します。

プロセス

フェーズ 1：状況を把握する

調査範囲を定めます。リポジトリ内で完結するのが理想ですが、影響を評価する際はリポジトリ間の相互運用性も考慮してください。gjalla が役立つ場合があります。 最近の変更を簡単に確認し、重点的に調べる箇所の目星をつけます。ただし、どの領域も調査対象から除外しないでください。 gjalla でアーキテクチャ、ルール、学び、システムの進化を確認します。

フェーズ 2：調査する

不要なコード、重複したロジック（または非常によく似ているものの差異が生じているロジック）、過度な設計、意図されたアーキテクチャパターンに従わずスパゲッティコードの原因となっているコード、無秩序に追加されたコードなどを見つけます。

フェーズ 3：検証する

候補ごとに、grep では見つからない可能性のある参照方法も含め、調査範囲全体にわたって参照を列挙します。たとえば、すべての呼び出し元を把握できないため、パブリック API エンドポイントには特に注意してください。

フェーズ 4：分類する

ティア	説明	対応
ティア 1	不要であることが証明済み：すべての参照を調べた結果、参照がゼロで、動的な参照も外部からの参照もない	関連するテストとともに削除する
ティア 2	コード上では不要だが、データ（孤立した行や列）が残る	コードは今すぐ削除し、データについては別途、慎重に判断する
ティア 3	所有者が明確な重複	1 つの実装に統合し、最もよくテストされているものを残す
ティア 4	疑わしいが証明されていない、または調査範囲の外部から参照可能	報告するが、削除しない。何が確認できれば判断がつくかを明記する
古くなった記述	事実と異なる内容を主張しているコメント、ドキュメント、仕様	すぐに修正する。監査で最も低コストかつ価値の高い対応

フェーズ 5：段階的に削除する

途中で何も壊れないよう、依存関係の末端から順に進めます。まずテスト、次に呼び出し元、続いて実装、最後にデータファイルまたはモジュールを削除します。各段階の間に、関連するテストスイートを実行します。各段階は個別に元に戻せるようにし、削除作業とリファクタリングを混在させないでください。

出力

1. ティア 1 の削除：ファイルパス、行数、それぞれが不要であることを証明する参照の列挙。
2. ティア 3 の統合：存在する重複、それぞれのコピーのうち残すもの、動作を保証するテスト。
3. ティア 4 の未証明項目：疑わしい点と、判断を確定するために必要な証拠。
4. 修正した古い記述：何が記述されていたか、実際にはどうなのか。
5. 影響：何がシンプルになるか、どのようなリスクを受け入れたか、意図的に何を残したか。

原則

• 確信ではなく証拠。 「呼び出し元を見つけられなかった」と「呼び出し元が存在しない」は異なる主張です。どちらを確認したのか報告してください。
• 削除は最善のリファクタリングです。 存在しないコードにバグはなく、テストも必要なく、誰かを混乱させることもありません。
• コードの監査でデータを削除しないでください。 行は、それを書き込んだコードよりも長く残り、後から編集されている可能性もあります。書き込み処理を削除するのはコード上の判断ですが、その処理が書き込んだものを削除するのはプロダクト上の判断であり、人間が行うべきです。
• 誤解を招くものを最初に直す。 古いコメントや完了していない作業を完了済みとする仕様は、不要なコードよりも早く誤った判断を招きます。
• 1 つの変更につき懸念事項は 1 つ。 「ついでに改善」も行うクリーンアップはレビューが難しく、きれいに元に戻すこともできません。