design-cleanup

設計のクリーンアップ — ツリーから、最初からこの設計だったように読み取れる状態にする

このスキルが必要な理由

作業中に設計上の判断が変わると、たとえば別のアプローチへの変更、概念の改名、仕組みの置き換えなどが起きると、ブランチには放棄した設計の痕跡が残りがちです。不要な分岐、古い経路のためだけのシム、古い概念に基づく名前、変更の経緯を語るコメント、もはや重要でない動作を固定するテストなどです。差分にはその過程が表れていても、最終的なツリーに残してはいけません。このスキルでは、そうした痕跡を探し出し、現在の設計が最初から存在していたかのように結果を書き直します。

ステップ 1 — 判断を明確にする

判断を 1 行で述べます。「設計は X であり、放棄したアプローチは Y です」。ユーザーまたはセッションのコンテキストから判断を得てください。明示されていない場合は、ブランチの差分とコミットメッセージから再構成し、大規模な編集を行う前に 1 行の要約をユーザーに確認してください。誤って解釈した判断に基づくクリーンアップは、正しいコードを壊してしまいます。

ステップ 2 — 対象範囲を決める

• ブランチの差分を計算します。git diff $(git merge-base HEAD origin/main)...HEAD （利用できない場合は、origin/develop、次に develop に切り替えます）。
• クリーンアップの対象は、その判断に関係するコードに限ります。つまり、判断を実装する変更対象ファイルと、改名または削除した概念を参照するファイルです（古い名前を grep して見つけます）。
• それ以外は対象外です。このスキルは、無関係なリファクタリング、フォーマットの一括適用、便乗した改善を許可するものではありません。

ステップ 3 — 残存物を探す

対象範囲のファイルを確認し、各カテゴリに該当するものがないか調べます。

• 不要なコード：放棄した経路でしか使われない分岐、パラメーター、機能フラグ、設定キー、ヘルパー。
• シムと間接化：古い設計から新しい設計への橋渡しだけを目的としていたアダプター、ラッパー、抽象化レイヤー。
• 名前と構造：古い概念に基づく識別子、ファイル、モジュール。newParser、handleV2、legacyFoo、あるいは存在しなくなった概念を中心に構成されたモジュール構成など。
• コメントと docstring：古い設計を説明するものや、変更の経緯を語るもの。「以前は」「〜の代わりに」「今は〜」「X から Y に変更」など。説明には現在の設計だけを記述してください。
• テスト：放棄した動作、移行途中の状態、古い API の形を固定するテスト。現在の設計で意図する動作に合わせて書き直してください。偶然テストが通る状態を保ってはいけません。
• ドキュメント：古い仕組みを説明する README のセクション、ADR、図、例。既存箇所を更新し、「移行に関する注記」を追加してはいけません。
• TODO：古い計画のために残された項目。

ステップ 4 — パッチではなく書き直す

• 現在の概念に合わせて、変更が簡単な箇所だけでなく、すべての箇所で名前を変更します。
• 不要なコードはそのまま削除します。コメントアウトしたり、「念のため」残したりしてはいけません。古いバージョンは Git の履歴に残っています。
• 役割を失った間接化を取り除きます。
• 影響を受けるコメント、docstring、ドキュメントは、現在の状態だけを説明するように書き直します。

ステップ 5 — 検証して報告する

• プロジェクトのビルドとテストを実行します。クリーンアップによって、残す設計の動作が変わってはいけません。
• 履歴を示す語句がないか、結果のブランチ差分を grep で簡易確認します。previously|instead of|no longer|old |new |V2|legacy — 該当箇所は修正候補であり、必ず違反というわけではありません。個別に判断してください。
• ツリー全体を grep して、放棄した名前への参照が残っていないことを確認します。
• 上記のカテゴリごとに、削除、改名、書き直しを行った内容を報告し、判断の対象範囲外であるため変更せずに残した、疑わしい箇所があれば明記してください。