実装戦略選択フレームワーク（メタ認知的アプローチ）

メタ認知的戦略選択プロセス

Phase 1: 判断に十分な現状分析

中心となる問い: 「既存の実装はどうなっているのか？」

分析フレームワーク

アーキテクチャ分析: 責務分離、データフロー、依存関係、技術的負債
実装品質評価: コード品質、テストカバレッジ、パフォーマンス、セキュリティ
歴史的文脈理解: 現在の形の理由、過去判断の妥当性、制約の変化、要求の進化

メタ認知質問リスト

• この実装の真の責務は何か？
• どの部分がビジネス本質で、どの部分が技術的制約由来か？
• コードから明確でない依存関係や暗黙の前提条件は何か？
• 現在の設計がもたらしている利点と制約は？

現状に関する事実をこれ以上集めても、責務、再利用、選択肢の成立性、総合的な複雑性、契約、検証のいずれも変わらない時点で調査を止める。

完了条件: 確認したパス、観測したアーキテクチャ・データフローの事実、既知の制約、推測と明記した歴史的背景、不明点のうち戦略選択を変え得るもの。

移行条件: 戦略に関係するすべての主張が、観測済み、根拠付きの推測、または不明として明記されている場合に次へ進む。

Phase 2: Design Convergence

中心となる問い: 「現行の必要な成果を届ける最小の設計は何か。そこから先の追加は、どの根拠が要求しているのか？」

実装戦略の探索に入る前に、以下を順に完了させる：

1. 既存の責務を使う基準案: 既存の責務を通して現在の成果を届ける、最も単純なエンドツーエンドの経路を組み立てる。明示された要件と承認済みの判断は拘束力を持ち、提案された技術手段は候補に留める。
2. エビデンスチェック: その経路を、現行要件、検証済みの制約、スコープ内で観測された問題、根拠のある重大リスクに照らして検証する。選択する設計を変えうる未充足条件だけを残す。要件が品質水準を定めていない場合（性能、鮮度、整合性、可用性、必要な信頼境界を超える保護など）は、成果を届けられる最も低い水準で検証し、それを選択した水準として記録する。
3. 的を絞った比較: 未充足条件ごとに、設計要素を追加する前に、再利用、既存データからの導出、オンデマンド計算、現在の呼び出し側または境界での責務保持を検討する。成立する案について、ユーザーの判断・設定・モード・概念・出力、永続状態、実装経路、およびUX・実行時・実装・テスト・文書・保守のコストのうち、実際に異なる観点だけを比較する。その条件を満たす案のうち、総合的な複雑性が最も低いものを選ぶ。
4. 除去チェック: 提案した追加を1つずつ取り除き、その根拠となる条件を再検証する。成果、必要な境界、または必要な証明が、その出所（要件、承認済みの判断、リポジトリの規則や契約）で満たせなくなる場合に限って追加を残す。ワークフローの成果物がその出所から導いた基準、不変条件、制約は、出所が求める範囲まで絞る。

候補となる経路と不採用の追加は設計時に比較し、長期的に残す出力には Selected Design だけを記載する。選択した経路全体に加えて、追加した設計要素ごとの根拠と、それを取り除くと満たせなくなる条件を記録する。選択肢を判断の履歴として残せるのは、承認済みADRが扱う場合だけである。実装時は別の成果物を作らず、同じ収束チェックを適用する。

完了条件: 完全なSelected Designが1つあること。追加した各設計要素に、現在の根拠、設計範囲をこれ以上小さくできない理由、除去チェックの結果が示されていること。

移行条件: 裏付けとなるすべての主張が、観測済み、根拠付きの推測、または不明として明記されている場合に次へ進む。不明点が次のステップを妨げる場合は、必要なエビデンスを具体的に示す。ユーザーに確認するのは、不明点によって成果・将来状態の要件・対象外のいずれかを変える必要がある場合、または不可逆な操作の承認が必要な場合だけである。

Phase 3: 戦略探索と創造

中心となる問い: 「before → after を判断する時に、参考にすべき実装パターンや戦略は何なのか？」

戦略発見プロセス

直接戦略: Selected Designを必須制約の範囲で届ける、リポジトリが裏付ける最小の戦略
調査の順序: リポジトリ内のパターンを最初に確認し、次に特定した依存バージョンの公式ドキュメント、保守されているOSS実装の順に調査する。文献・ブログは補足にのみ使用し、非公式な情報源と明記する

参考戦略パターン

パターンは、その名前が示す移行や依存の問題がリポジトリに実在する場合に限って使う。

レガシー対応戦略:

• ストラングラーパターン: 段階的置換による漸進的移行
• ファサードパターン: 統一インターフェースによる複雑性の隠蔽
• アダプターパターン: 既存システムとの橋渡し

新規開発戦略:

• 機能駆動開発: ユーザー価値重視の縦断実装
• 基盤駆動開発: 安定性重視の基盤優先構築
• リスク駆動開発: 最大リスク要素から優先的に対処

統合・移行戦略:

• プロキシパターン: 透過的な機能拡張
• デコレーターパターン: 既存機能の段階的強化
• ブリッジパターン: 抽象化による柔軟性確保

完了条件: 直接戦略を、それが満たす観測済みの制約と未解決の制約に対応付ける。代替案は、リスク、互換性、ロールアウト、早期検証点を実質的に変える場合に限って加える。

移行条件: 直接戦略と残した代替案を、同じ制約集合に対して比較できる場合に次へ進む。

Phase 4: リスク評価とコントロール

中心となる問い: 「既存の実装に適用するとどのようなリスクが発生し、検証可能性と切り戻し可能性を保ちながら、その発生確率または影響を計測可能な形で下げられる制御は何か？」

現在のエビデンスが戦略、公開契約、ロールアウト、切り戻し、検証境界を変えうるリスク区分だけを評価する。

リスク分析マトリクス

技術的リスク: 既存システム影響、データ整合性、パフォーマンス劣化、統合複雑性
運用リスク: サービス可用性、デプロイダウンタイム、運用プロセス変更、切り戻し手順

完了条件: 根拠のある重要なリスクごとに、発生確率・影響の根拠と、予防または封じ込めの制御を1つずつ示す。

移行条件: 影響が大きいすべてのリスクに制御または作業を止めるエスカレーションが設定されている場合に次へ進む。

Phase 5: 制約適合性検証

中心となる問い: 「このプロジェクトの制約は何か？」

正典となる要件、リポジトリ、外部契約、現在の環境が根拠を示し、選択する戦略または検証境界を変えうる制約だけを確認する。

制約チェックリスト

技術的制約: ライブラリ互換性、リソース容量、義務要件、数値目標
時間的制約: 期限・優先度、依存関係、マイルストーン、学習期間

完了条件: 各制約を観測済み、推測、不明のいずれかに分類する。候補を無効にし得る不明点ごとに、必要なエビデンスを具体的に示す。

移行条件: 残る不明点によって有効な候補集合が変わらない場合、またはユーザーが解決した場合に次へ進む。

Phase 6: 実装アプローチ決定

すべての必須制約と現行要件を満たし、移行リスクが最も低く、検証までの遅延が最も小さいアプローチを選択する。要件の充足、互換性、リスク制御が同等の場合にのみ、ライフサイクルコストと実装工数を同点時の判断基準にする。

垂直スライス（機能駆動）

特徴: 機能単位で全層を縦断実装 適用条件: 機能間の依存が少ない、ユーザーが利用可能な形で出力、アーキテクチャ全層への変更が必要 確認方法: 各機能完成時のエンドユーザー価値提供

水平スライス（基盤駆動）

特徴: アーキテクチャ層別の段階的構築 適用条件: 基盤システムの安定性が重要、複数機能が共通基盤に依存、層別の段階的確認が有効 確認方法: 全基盤層完成時の統合動作確認

ハイブリッド（創造的組み合わせ）

特徴: プロジェクト特性に応じた柔軟な組み合わせ 適用条件: 要件が明確でない、フェーズごとにアプローチ変更が必要、プロトタイピングから本格実装への移行 確認方法: エンドユーザーが操作可能な振る舞いを生むPhaseにはL1、テスト可能な内部の振る舞いまたは契約を生むPhaseにはL2、実行可能な振る舞いをまだ持たないビルド時の構造だけを生むPhaseにはL3を割り当てる

ハイブリッドでは、すべてのPhaseにL1/L2/L3のいずれか1つと、観測可能な完了結果を明示する。

完了条件: 選択したアプローチ1つ、そのPhase境界、統合点、各Phaseの検証結果。

移行条件: 選択したアプローチがすべての必須制約を満たし、リスクに制御が設定されている場合は文書化へ進む。それ以外は候補探索（Phase 3）へ戻る。Phase 4〜5の結果がSelected Designまたはその根拠を変える場合は Design Convergence（Phase 2）へ戻る。

Phase 7: 判断根拠の文書化

Design Docまたは計画のハンドオフに、以下の構造で記載する：

implementationApproachDecision:
  observedConstraints: [<制約 + 根拠>]
  inferredConstraints: [<制約 + 根拠と推測>]
  unknowns: [<不明点 + 必要な根拠または判断>]
  selectedApproach: <vertical | horizontal | hybridの説明>
  selectionRationale: <必須制約の充足、互換性、リスク制御、総合的な複雑性の根拠>
  addedDesignSurface: [<追加 + 現在の根拠 + 設計範囲をこれ以上小さくできない理由 + 除去チェックの結果>]
  phaseVerification: [<Phase + L1/L2/L3 + 観測可能な完了条件>]

長期的に残す成果物には、選択したアプローチだけを記録する。承認済みADRが判断の履歴として扱う場合は、比較した選択肢も残せる。

完了条件: 選択したアプローチと追加した各設計要素が、観測済みの制約、受け入れた推測、または成果・将来状態の要件・対象外に関する解決済みの判断まで追跡できること。

検証レベル定義

各タスクの完了確認における優先順位：

• L1: 機能動作確認 - エンドユーザー機能として動作（例：ユーザーが検索を実行して結果を受け取れる）
• L2: テスト動作確認 - 変更した振る舞いを証明するテストがパス（例：型定義テスト）
• L3: ビルド成功確認 - コンパイルエラーなし（例：インターフェース定義）

優先順位: L1 > L2 > L3 の順で確認可能性を重視

統合ポイントの定義

選択した戦略に応じて統合ポイントを定義：

• ストラングラー系: 各機能の新旧システム切り替え時
• 機能駆動: ユーザーが実際に機能を利用可能になった時
• 基盤駆動: 全アーキテクチャ層が揃いE2Eテストが通った時
• ハイブリッド: 各フェーズで定義した個別目標達成時

判断ゲートのチェックリスト

• 戦略選択前にPhase 1の完了条件を満たしている
• Phase 2で完全なSelected Designが1つ作られ、追加した各設計要素が現在の根拠、設計範囲をこれ以上小さくできない理由、取り除くとその出所が満たせなくなるという除去チェックの結果に対応している
• 一覧の戦略だけでは必須制約を満たせない場合、候補生成で組み合わせを検討している
• 根拠のある重要なリスクごとに制御がある
• すべての必須制約が選択したアプローチに対応付けられている
• Phase 7の出力に選択した方針、総合的な複雑性の根拠、追加した設計要素が記録され、選択肢は承認済みADRにだけ残っている

チェック項目に必要な根拠が不明な場合は、そのPhaseで止まり、必要なリポジトリのエビデンスを具体的に報告する。ユーザーに確認するのは、不明点によって成果・将来状態の要件・対象外のいずれかを変える必要がある場合、または不可逆な操作の承認が必要な場合だけである。

メタ認知的実行のための指針

1. 既知パターンの活用: パターンの問題とトレードオフが、観測したリポジトリの状態に一致する場合に使う
2. 根拠の優先順に従う調査: リポジトリ内の根拠、対象バージョンに一致する公式ドキュメント、保守されているOSS実装、補足的な二次情報の順に使用
3. 5 Whys適用: 根本理由を追求し本質を把握
4. 複数観点評価: Phase 1〜5の完了条件と移行条件を満たす
5. 戦略の組み合わせ: 1つの戦略ではすべての必須制約を満たせない場合に組み合わせる
6. 判断のトレーサビリティ: すべての選択理由をPhase 7の出力にある根拠へ対応付ける