refactor

リファクタリング — 1 つの構造的な実験

リファクタリングでは、観察可能な動作を保ちながら構造を変更します。呼び出し元が選択した変換を 1 つ実行し、その結果を報告します。「動作を保持している」ことは、断言するのではなく、変更前後のチェックで証明する必要があります。

動作に含まれるもの

呼び出し元が明示的に対象から除外していない限り、以下すべてを維持する必要があります。

• メッセージと終了コード。 エラーや出力のテキストはバイト単位で一致する必要があります。終了コード、エラーの型、どの入力がどのエラーを発生させるかも変えてはいけません。スクリプトや呼び出し元がこれらを解析します。一貫性のないメッセージもそのまま維持して報告してください。正規化すると動作の変更になります。
• よく似た重複コードの違い。 重複した分岐を統合するときは、差異（定数、比較、メッセージ、追加手順）をすべてパラメーターまたは分岐として引き継いでください。呼び出し元が誤りだと明示していない差異を統一してはいけません。
• インターフェース。 公開シグネチャ、デフォルト値、戻り値の型、永続化されるフィールド名、プロトコル値、CLI フラグ。受け入れられた範囲に含まれていない限り、名前を変えることは互換性の変更です。
• 順序と網羅性。 分岐の優先順位、デフォルトの処理、評価回数、副作用の順序、実行されるテストの集合。既存の失敗が消えることや、テストが実行されなくなることも動作の変更です。
• 保護のためのチェック。 信頼境界の検証、データ損失防止策、セキュリティ制御、アクセシビリティ上の配慮は維持してください。別のレイヤーで重複している場合や、上流・下流に同じチェックがある場合、あるいはどのテストでも実行されない場合も同様です。中立性のゲートではその削除を検知できないため、冗長に見えることは削除の理由になりません。

手順

1. 呼び出し元のドメイン用語を使って、維持する動作、対象を絞った受け入れ範囲、呼び出し元にとっての具体的な構造上の問題を明示します。
2. 対象を絞ったチェックと、変更範囲に応じて必要となる最小限の回帰チェックを実行し、再現可能な環境由来の失敗も含めて、ありのままのベースラインを記録します。実行可能な動作を比較する評価では、開始時のソースを固定し、編集前にベースラインをビルドして、そのバイナリと比較用入力を保持します。
3. 範囲を限定した変換を 1 つ適用します。抽出、名前変更、インライン化、簡素化、カプセル化、移動、既存コードへの置換、またはデッドコードの削除が該当します。リファクタリングカタログには、パターンごとの安全性チェックがあります。ファイルサイズではなく、呼び出し元が理解する必要のあることと、ドメインルールの変更が必要な場所に基づいて評価します。
4. 作業中に見つけたバグや疑わしい不整合は、別途（場所と、誤りに見える理由を）報告し、修正せずに残します。リファクタリングの中で修正すると、呼び出し元が許可していない動作の変更が隠れてしまいます。
5. 同じ入力（エラーパスを含む）に対して、同じ対象を絞ったチェックと、必要最小限の回帰チェックを再実行します。
6. 報告して終了します。失敗は呼び出し元への証拠です。このスキルでは、その後の作業の取り消し、範囲縮小、再試行、コミット、検証、または振り分けは行いません。

実行できるものがない場合（ランタイムやテストがない場合、コードがメッセージ内に提示された場合）、中立性は証明されていません。エラーパスも含めて、呼び出し元が実行すべき変更前後のコマンドと入力を正確に提示し、動作を確認できていないすべての範囲を列挙します。

transformation: <the one change>
preserved:      <behavior and surfaces from step 1>
checks:         <command>: before -> <result>; after -> <result>   (or "not run")
outputs:        <before/after hashes when the surface produces output>
diff:           <files touched>; only those the transformation names
suspected bugs: <file:line, why>; reported, not fixed
not checked:    <surfaces no check covered>; present even when empty

責務とインターフェースのコスト

インターフェースを追加したり、モジュールを分割したりする前に、代表的な呼び出し元を調べます。 呼び出し元が調整しなければならない概念を数えます。必須のセットアップ、実行順序、状態、エラー処理、繰り返されるドメインルールなどです。有用な境界とは、一貫性のあるルールを一つの担当箇所にまとめ、呼び出し元がそのルールを再現せずに結果を要求できるようにするものです。名前を一つ増やすだけのラッパーや、同じ調整を呼び出し元に押し付けるものは避けます。具体的な呼び出し元の問題が境界の変更を正当化しないなら、既存の境界で十分です。

対象を選ぶときは、呼び出し元が指定した領域の摩擦を優先します。同じルールの繰り返しの変更、呼び出し元によるセットアップの繰り返し、または連携するファイル全体に広がる不具合などです。呼び出し元が問題を特定していない場合、最近の履歴から摩擦の箇所を探せますが、変更頻度だけではリファクタリングを正当化できません。呼び出し元の移行コストや回帰コストと照らし合わせ、たとえば一つのルールを一箇所で変更できるなど、具体的な作業削減を明示します。安定していてコストの低い境界はそのままにします。

提案した抽出を検証するには、それを取り除いた場合を想像します。呼び出し元が一貫性のあるルールを再構築する必要があるでしょうか。それとも、転送の手順が一つなくなるだけでしょうか。呼び出し元が差し替えを必要としないなら、内部のテスト用接点は非公開のままにします。呼び出し元に公開される境界を通じて、維持される振る舞いをテストします。異なるケースを同等に網羅できることが示されるまでは、既存のテストを残します。テストを移動しても、それが保護していた振る舞いを削除してよいことにはなりません。

抽出した操作や型には、呼び出し元の語彙を使います。振る舞いを変える命名の曖昧さは、既存のドメイン定義とともに扱います。その区別の検討が必要な場合に限り、Domainを参照します。

変換に接点（抽出境界、インターフェース、モジュール分割）が必要で、候補となる接点が複数ある場合は、分割する前に試します。呼び出し元のポリシーで許可された使い捨ての隔離環境（スクラッチブランチ、ワークツリー、コピーしたツリー）で試行します。接点を仮に作り、何が必要になるか（シグネチャの変更、インポート循環、テストの書き換えなど）を確認してから、試行を破棄し、得られた知見だけを残します。停止条件は、試行は最大二回です。二つ目の候補となる接点も扱いにくい場合は、三つ目を試すのではなく、両方の結果を呼び出し元に報告します。最初に思いついた接点をそのまま作業ツリーに切り込むことは、時期尚早な接点の設定という失敗パターンです。元に戻すコストが、誤った境界を使い続けるコストを上回り、誤った境界が固定化されるためです。

中立性ゲート

振る舞いが同一であることの証明を、変換のゲートとします。

• 対象を絞ったチェックとパッケージレベルの回帰チェックが、変更の前後で、同じ既存の失敗を含めて合格する必要があります。新たな失敗も、既存の失敗の消失もあってはなりません。
• 出力を生成する領域（ジェネレーター、シリアライザー、フォーマッター、レポート）では、変更前に同一入力で出力ハッシュを取得し、変更後にバイト単位で比較します。不一致は報告して説明すべき振る舞いの差分であり、問題ないものとして見過ごしてはなりません。維持するか、範囲を絞るか、元に戻すかは呼び出し元が判断します。

中立性ゲートを実施しなかったり、事後に範囲を狭めたりすることは、事後的な中立性という失敗パターンです。差分によってテスト対象が決まってしまうためです。ゲートで確認されていない領域は、「振る舞いを未確認」として明示します。

参考資料

• 振る舞いを維持した簡素化 — リファクタリングのカタログとパターンごとの安全性チェック
• 振る舞いのシナリオ
• 上流の機能リファレンス — Matt Pocock。AgentOps によるオリジナルの適応版。