fable-simplify

Fable Simplify

不要な複雑さを減らしながら、外部に関わる動作と契約が変わっていないことを証明します。

ミッション

簡素化は、大規模な書き換えを許可するものではありません。特性評価や不変条件の証拠に裏付けられた、小さくレビューしやすい変換を通じて、コードを理解しやすくすることが目的です。

「よりクリーン」であるかどうかは主観的です。動作の維持、重複・分岐・間接化の削減、責務の明確化は、具体的に示すことができます。

次の場合に有効化

• ロジックの重複によって、差異が生じるリスクがある場合；
• ネストや制御フローの複雑さによって、不変条件が見えにくくなっている場合；
• 未使用であることが証明されたデッドコードや古い間接化がある場合；
• 意図した動作変更を伴わないリファクタリングが明示的に依頼された場合；
• 実装が完了し、レビュー前に範囲を限定した整理が必要な場合。

次の場合は有効化しない

• ユーザーに見える動作／API／スキーマを変更する意図がある場合（fable-tdd／fable-execute）；
• 動作の特性が十分に把握されておらず、維持を保証できない場合；
• アーキテクチャ自体を再設計する場合（fable-plan）；
• 整理の機会が、現在のカードに関係ない場合。

簡素化の分類

課題	安全な最初の手順
動作の重複	同等性を証明し、共通ルールを抽出する
ネストした分岐	判断表／不変条件を特定し、段階的に平坦化する
デッドコード	実行時／登録／リフレクションによる到達可能性がないことを証明する
ラッパー／間接化	呼び出し元／セマンティクスを確認してから統合する
データ変換の連鎖	代表的な入力と境界値を特性評価する
公開／内部 API の煩雑さ	公開契約を維持し、境界の内側を簡素化する
生成コードのノイズ	出力を手動で変更せず、ジェネレーター／ソースを変更する

プロトコル

ステージ 1 — 維持する契約を定める

変更してはならないものを明示します：

• 公開入力／出力／エラー；
• 副作用／状態遷移；
• 契約で定められている場合のシリアライズ／順序／タイミング；
• パッケージ／API／CLI との互換性；
• 重要な場合のパフォーマンス要件。

ベースラインとなるテスト／フィクスチャ／実行時の証拠を記録します。カバレッジが不十分な場合は、構造を変更する前に特性評価を追加します。

ステージ 2 — 削減する複雑さを特定する

具体的に名前を挙げます。例：重複した条件、不要な分岐、デッドアダプター、繰り返しの解析、分断された責務、古い互換性経路。

「このモジュールを最新化する」のような、範囲が定まらない目標は避けます。

ステージ 3 — 削除前に到達可能性／未使用を証明する

呼び出し元に加え、動的登録／プラグイン／リフレクション／生成コード経由の経路も検索します。動的に読み込まれる可能性があるコードでは、「grep でインポートが見つからなかった」だけでは不十分です。

ステージ 4 — セマンティクスを一段階ずつリファクタリングする

例：

• 共通する純粋なルールを抽出する；
• ネストした分岐を、明示的なガード／判断表に置き換える；
• 契約が同一のラッパーを統合する；
• 到達可能性を証明した後で、デッド分岐を削除する。

重要なステップを行うたびに、対象を絞った維持確認を実行します。

ステージ 5 — 意図しない契約変更に注意する

差分を確認し、以下をチェックします：

• 呼び出し元が依存している例外／エラーの型やメッセージの変更；
• 反復順序／順序の変更；
• 真偽値判定／null のセマンティクス；
• 即時評価と遅延評価；
• 非同期処理の順序；
• トランザクション／クリーンアップの移動；
• 公開エクスポート／シグネチャ／デフォルト値の変更；
• 必要な場合のパフォーマンス／リソース動作。

ステージ 6 — 簡素化を正確に評価する

有用な証拠には、以下が含まれます：

• 重複したルール／分岐の削減；
• 公開範囲の縮小；
• 状態／間接化レイヤーの削減；
• 名前付き不変条件の責務の明確化。

行数だけでは品質を評価できません。

ステージ 7 — 改めて検証し、レビューする

最後のリファクタリング変更の後、影響範囲を対象とした検証を改めて実行し、独立した差分レビューを行います。リファクタリング前に成功したベースラインは、簡素化後のコードには適用できません。

判断ルール

• 振る舞いが豊富なレガシーコードに特性評価や証明がない場合は、リファクタリングの前に追加します。
• デッドコードを削除するには、動的レジストリやプラグインも含め、実行時に到達可能かどうかを確信できる必要があります。
• 単純化によって望ましい振る舞いの変更が明らかになった場合は、別の TDD／実行カードに分けます。
• ゼロから書き直すより、元に戻せる変換を少数行うことを優先します。
• 行数が増えても、実際のドメインや所有権の境界を表す抽象化は統合しません。
• 似たコードブロックでも、将来の不変条件が異なる場合は DRY を避けます。構文が共通していても、概念が共通とは限りません。
• テストが失敗した場合は、リファクタリングで振る舞いが変わったのか、テストが内部実装に結合していたのかを診断します。やみくもに元に戻したり、アサーションを更新したりしないでください。

不変条件

• 外部に対して受け入れられた振る舞いは変更されません。
• パブリックコントラクトが意図せず変わることはありません。
• 各変換はレビュー可能で、根拠に裏付けられています。
• 無関係なクリーンアップは対象範囲に含めません。
• 削除の前に、動的な到達可能性や生成コードによる到達可能性を考慮します。
• 最終変更後に、改めて検証を行います。

失敗の分類

振る舞いの逸脱

リファクタリングによって出力、エラー、状態、順序が変わります。不変条件を復元するか、意図した振る舞いの変更を分離します。

テストの結合

テストがコントラクトではなく内部構造を検証しているため、失敗します。好みではなく、受け入れられた振る舞いに基づいて、テストとコードのどちらを変更すべきか判断します。

デッドコードの誤認

動的な登録、リフレクション、プラグインの経路から、依然としてコードに到達できます。コードを復元し、発見の根拠を強化します。

抽象化の崩壊

削除されたレイヤーが、実際の境界や不変条件を表していました。行数を減らすのではなく、より明確な境界を再導入します。

スコープクリープ

リファクタリングがアーキテクチャや機能の作業にまで広がります。中断し、作業を分割して再計画します。

複雑さの移転

局所的にはコードが短くなっても、複雑さが呼び出し元、設定、汎用抽象化に移っています。影響を受ける判断範囲全体を評価します。

アンチパターン

• 「単純化」のためにモジュールをゼロから書き直す
• 行数を主な成功指標として使う
• 静的な import がないという理由でコードを削除する
• 意味の異なるルールをまたいで DRY 抽出する
• クリーンアップ中に API シグネチャを変更する
• コントラクトを確認せず、リファクタリングに合わせてテストを更新する
• 機能作業の後に無関係なクリーンアップをまとめる
• 明示的なドメインロジックを、巧妙な汎用抽象化に置き換える

単純化パケット

Preservation contract:
Baseline evidence:
Complexity targeted:
Reachability/deadness evidence:
Transformations:
Risky semantic deltas checked:
Fresh verification:
Review result:
Measured simplification:
Deferred behavior changes:

完了条件

単純化は、次の条件を満たしたときに完了します。

• 複雑さの低減が具体的で、対象範囲が限定されています。
• 振る舞いやパブリックコントラクトが特性評価され、維持されています。
• 削除やリファクタリングに関する到達可能性の前提に根拠があります。
• 最終的な証拠が最新です。
• 独立したレビューで、隠れた振る舞いの逸脱が見つかりません。
• クリーンアップに無関係な振る舞いの変更が紛れ込んでいません。

段階的なリソース

• 詳細ガイド：references/behavior-preserving-refactor-strategy.md
• 既存のパターン：references/refactoring-patterns.md
• 例：examples/flatten-nested-logic.md