fable-plan

Fable Plan

根拠に基づいた証拠を、依存関係、リスク境界、受け入れの証明、統合の責任者が明確な、実行可能な変更戦略に変換します。

ミッション

計画とは、編集するファイルの一覧ではありません。安全に実行できるほど実装を単純にする、一連の判断です。

プランナーは、アーキテクチャ上の不確実性を取り除き、順序の制約を明らかにし、「完了」の定義を定め、各要素を本当に独立して推論・検証できる場合に限って作業を分割します。

以下の場合に有効化

• タスクが複数のファイル／コンポーネントにまたがる、または新しい契約を導入する場合。
• 移行、スキーマ変更、パブリック API の変更、またはパッケージ横断のリファクタリングが必要な場合。
• 実装に順序付けやロールバックの検討が必要な場合。
• 並列作業者が役立つ可能性があるものの、担当範囲や統合方法を設計する必要がある場合。
• 要件は理解できているものの、まだ検証可能な作業に分解されていない場合。

以下の場合は有効化しない

• 重要な事実がまだ不明な場合（fable-discover／fable-research）。
• 変更が明確な受け入れ条件を持つ、明らかに限定された単一の編集である場合（fable-execute）。
• 直近の作業がテストで動作を再現することである場合（fable-tdd）。

変更の分類

分解する前に分類します。

変更の種類	主な計画上の懸念
限定された動作	受け入れ条件と回帰の範囲
モジュール横断の機能	契約と統合ポイント
リファクタリング	不変条件の維持と段階的な互換性
データ／スキーマの移行	前方／後方互換性とロールバック
パブリック API／CLI	互換性、バージョン管理、ドキュメント／テスト
依存関係のアップグレード	動作の差分と推移的なリスク
セキュリティ上重要な変更	信頼境界とフェイルクローズ動作
リリース／配布	成果物の境界と外部検証

計画プロトコル

ステージ 1 — 契約を言い直す

以下を記録します。

• 求められている結果。
• 対象外の事項。
• すでに確立された証拠。
• 回帰させてはならない、外部から確認可能な動作。
• 未解決事項と、それらがブロッカーではない理由。

ブロッカーとなる不明点が残っている場合は中止し、ディスカバリー／リサーチに戻ります。

ステージ 2 — 変更グラフをマッピングする

以下を特定します。

• 影響を受けるコンポーネント。
• コンポーネント間の契約。
• データ／状態の遷移。
• 移行または互換性に関する接点。
• 統合に関わる共通の要所。
• 生成された成果物とその生成元。
• 検証対象の範囲。

順序は単なる番号付きタスクではなく、依存関係として表現します。

ステージ 3 — 分解の境界を選ぶ

各カードには、一貫した変更理由と明確な受け入れ方法が必要です。

普遍的なルールとして、ファイルが重複しないことを要求してはいけません。 担当範囲と順序が明確であれば、2 枚のカードが同じ統合ファイルを順番に変更してもかまいません。逆に、異なるファイルを変更する 2 枚のカードでも、同じ共有不変条件や契約を変更する場合は、安全に並列化できないことがあります。

ステージ 4 — リスクを優先して計画する

可能であれば、不確実性が高い判断や取り消せない判断を先に進めます。

• 広範なデータ書き換えの前に、移行の形を検証する。
• レガシーパスを削除する前に、互換性アダプターを検証する。
• すべての呼び出し箇所に組み込む前に、サードパーティ API の契約を検証する。
• リスクの高いランタイム変更の前に、可観測性を導入する。

ステージ 5 — 各カードを定義する

各カードでは、以下を明記する必要があります。

• 目的とユーザーから見える効果。
• 担当する範囲と対象外の範囲。
• 依存関係／前提条件。
• 正しさを左右する場合に限った実装上の注意点。
• 受け入れの証拠／コマンド。
• 失敗時にコストが大きい場合のロールバックまたは復旧に関する注意事項。
• 引き継ぎ／統合に関する期待事項。

ステージ 6 — 統合の責任者を定義する

統合後の結果を誰が／何が証明するのかを明記します。カード単位で個別にテストが成功しても、カードをまたぐ動作については十分ではありません。

ステージ 7 — 失敗を想定して計画を確認する

以下を確認します。

• カード 1 の適用後にカード 2 が失敗した場合、どうなりますか。
• 移行中に旧形式と新形式を共存させられますか。
• 取り消せないステップはありますか。
• ロールバックによってデータ／契約は維持されますか。
• テストは主な回帰を検出できますか。
• 並列実行によってマージの競合や意味上の衝突が生じませんか。

判断ルール

• アーキテクチャが不明な場合は fable-discover を、外部コントラクトが不明な場合は fable-research を使用します。
• テスト可能なコントラクトを伴う動作変更では、最初の実装カードを fable-tdd 経由で進めます。
• 依存関係、担当範囲、共有される不変条件、統合ポイントを踏まえて並行作業が安全な場合に限り、並行化します。
• 古い呼び出し元と新しい呼び出し元、または永続化されたデータが共存する可能性がある場合は、一斉置き換えより段階的な互換性確保を優先します。
• 反証可能な受け入れ証拠を明示できないカードは、着手可能な状態ではありません。
• 計画の結果、相互依存が強いカードが概ね5件を超える場合は、機械的にさらに分割するのではなく、マイルストーンの境界や別のアーキテクチャを検討します。
• 生成ファイルは、そのソースまたはジェネレーターを変更するカードに含めます。独立した手動編集として扱いません。

不変条件

• すべてのカードは、要件または必要な前提条件にたどれる必要があります。
• 実行カードの中に、作業を妨げるアーキテクチャ上の不明点を隠してはいけません。
• 受け入れチェックでは、ファイルの存在だけでなく動作を証明します。
• 統合検証の担当者を明確にします。
• 破壊的または不可逆な手順には、明示的な保護策またはロールバックの検討を含めます。
• 並行化は、ファイル数だけでなく依存関係の分析に基づいて判断します。

失敗の分類

隠れた依存関係

カードで別のコンポーネントが予期せず必要になった場合です。依存関係グラフを更新し、実行中に作業範囲を暗黙に広げないでください。

誤った独立性

カードが別々のファイルを扱っていても、1つの不変条件またはコントラクトを共有している場合です。順番に実行するか、互換性の境界を定義してください。

受け入れ条件の弱さ

提案されたチェックが、動作が壊れたままでも通ってしまう場合です。実行前に受け入れ条件を強化してください。

移行上の危険

本番環境で新旧の状態が共存し得るのに、計画が一斉切り替えを前提としている場合です。互換性の確保、バックフィル、または段階的なロールアウトを追加してください。

スコープの肥大化

カードでアーキテクチャに関わる作業が次々に見つかる場合です。作業を中断し、ディスカバリーまたは計画に戻って境界を引き直してください。

アンチパターン

• ファイルごとにカードを1件作成する。
• 順次統合のほうが安全な場合でも、別々のファイルを必須にする。
• 「別々のファイル」という理由だけで並行化する。
• 対象の動作を明示せず、「テストが通る」とだけ受け入れ条件にする。
• 移行やロールバックを実装の説明文に隠す。
• ドキュメントや生成された出力が1つの動作変更の一部であるにもかかわらず、別カードとして扱う。
• 依存関係モデルのない長大なタスクリストを作成する。
• 実行時の証拠がないうちに、コードを1行ずつ過度に詳細化する。

作業カードのテンプレート

Card: <outcome>
Why: <requirement/risk>
Depends on:
Owns:
Must not change:
Behavior/invariant:
Implementation constraints:
Acceptance evidence:
Rollback/recovery:
Integration handoff:
Parallel-safe with:

完了条件

次の条件を満たしたとき、計画は完了です。

• 作業を妨げる不明点が解消されている。
• 依存関係と実行順の制約が明確になっている。
• カードが、任意のファイル分割ではなく動作に基づいて、一貫性があり範囲の明確なものになっている。
• 各カードに反証可能な受け入れ証拠がある。
• 該当する場合、移行、互換性、ロールバックに関する懸念に対処している。
• 並行作業を提案する場合、意味上の担当範囲と統合の証明が明確になっている。

段階的なリソース

• 詳細な分解ガイド：references/risk-and-dependency-decomposition.md
• 既存の分解ルール：references/decomposition-rules.md
• テンプレート：templates/work-card.template.md
• 例：examples/multi-file-migration-plan.md