implementation-approach

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

メタ認知による戦略選択プロセス

フェーズ 1：意思決定に十分な現状分析

中心となる問い：「既存の実装はどのような状態ですか？」

分析フレームワーク

Architecture Analysis: Responsibility separation, data flow, dependencies, technical debt
Implementation Quality Assessment: Code quality, behavior-relevant test evidence, performance, security
Historical Context Understanding: Current form rationale, past decision validity, constraint changes, requirement evolution

メタ認知のための質問一覧

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

現状についての事実を追加しても、責務、再利用、選択肢の妥当性、全体の複雑さ、契約、または検証が変わらなくなった時点で停止します。

フェーズ 2：設計の収束

実装戦略を選択する前に、次の手順を順番に完了してください。

1. 既存の表面を基準にする：既存の責務を通じて現在の成果を実現する、最も単純なエンドツーエンドの経路を構成します。明示的な要件と受け入れ済みの決定は拘束力を持ちます。提案された仕組みは、引き続き候補として扱います。
2. 根拠の確認：その経路を現在の要件、検証済みの制約、対象範囲内で観察された問題、根拠に基づく重大なリスクに照らして確認します。選択する設計を変え得る未達条件のみを残します。
3. 対象を絞った比較：未達条件ごとに、設計の要素を追加する前に、再利用、既存データからの導出、オンデマンド計算、現在の呼び出し元または境界での責務分担を検討します。実現可能な選択肢のうち、実質的に異なる次元、すなわちユーザーの判断、設定、モード、概念、出力、永続状態、実装経路、UX、実行時、実装、テスト、ドキュメント、保守にわたる全体の複雑さを比較します。その条件を満たす選択肢の中から、全体の複雑さが最も低いものを選びます。
4. 削除による確認：提案する追加要素を一つずつ取り除き、それを支える条件を再確認します。確認済みの成果、必須の境界、または必要な証明が満たされなくなる場合にのみ、その追加要素を残します。

裏付けとなる主張を、観察済み、推論済み、または不明に分類します。次の手順を妨げる不明事項は、具体的な根拠の前提条件として提示します。ユーザーとの対話が必要かどうかは、呼び出し元の値の境界と不可逆操作に関するゲートによって決まります。

候補となる経路と却下された追加要素も、分析の対象として維持します。永続的な成果物は選択した設計です。これは、選択した完全な経路と、追加する各設計要素の根拠およびその要素を削除した場合に満たされなくなる条件で構成されます。承認済みの ADR では、意思決定の履歴として代替案を残すことができます。実装者も、別個の成果物を作成せずに同じ収束確認を行います。

フェーズ 3：戦略の検討と策定

中心となる問い：「変更前から変更後を決定する際、どの実装パターンや戦略を参考にすべきですか？」

戦略の発見プロセス

Direct Strategy: Smallest repository-supported change that satisfies the accepted requirements and constraints
Repository Alternatives: Existing patterns that materially differ in migration, dependency order, or verification boundary
External Research: Official/current sources only when repository evidence cannot resolve a time-sensitive capability, compatibility, or dependency decision

参考となる戦略パターン

レガシー対応戦略：

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

新規開発戦略：

• フィーチャー駆動開発：ユーザー価値を優先する垂直方向の実装
• 基盤駆動開発：安定性を優先する基盤優先の構築
• リスク駆動開発：リスクの大きい要素への対処を優先

統合／移行戦略：

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

これらのパターンは、名称が示す移行上または依存関係上の問題が存在する場合にのみ使用してください。まず直接的な戦略を採用します。代替案によってリスク、段階的な展開、互換性、または早期の検証時点が実質的に変わる場合に、その代替案と比較します。選択肢は、こうした実質的な違いのいずれかをもたらすパターンに限定してください。

フェーズ 4：重大なリスクの評価と管理

中核となる問い：「これを既存の実装に適用した場合、どのようなリスクが生じ、それらを管理する最善の方法は何ですか？」

現在のエビデンスによって戦略、公開契約、段階的なリリース、ロールバック、または検証の境界が変わり得るリスクカテゴリのみを評価します。

条件付きリスクカテゴリ

Technical Risks: System impact, data consistency, performance degradation, integration complexity
Operational Risks: Service availability, deployment downtime, process changes, rollback procedures
Project Risks: Schedule delays, learning costs, quality achievement, team coordination

リスク管理戦略

Preventive Measures: Phased migration, parallel operation verification, integration/regression tests, monitoring setup
Incident Response: Rollback procedures, log/metrics preparation, communication system, service continuation procedures

フェーズ 5：意思決定に関わる制約との適合性

中核となる問い：「このプロジェクトにはどのような制約がありますか？」

選択する戦略または検証の境界が変わり得る、適用される要件、リポジトリ、外部契約、または現在の環境によって裏付けられた制約のみを確認します。

条件付き制約カテゴリ

Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets
Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods
Resource Constraints: Team/skills, work hours/systems, budget, external contracts
Business Constraints: Market launch timing, customer impact, regulatory compliance

フェーズ 6：実装アプローチの決定

検証済みの依存関係とデリバリー上の制約に直接適合する実装アプローチを選択します。

垂直スライス（機能主導型）

特性：機能単位で、すべてのレイヤーにわたって垂直に実装します。 適用条件：エンドツーエンドの価値単位を独立して提供・検証できる場合のデフォルトです。データモデルの共有やレイヤーの広がりは判断を補うエビデンスであり、独立した提供可能性の代わりにはなりません。 検証方法：各機能の完了時にエンドユーザーへの価値提供を確認します。

水平スライス（基盤主導型）

特性：アーキテクチャレイヤーごとに段階的に構築します。 適用条件：共通基盤が利用側の作業を妨げている場合、または依存するスライスに進む前に安定性・互換性の検証が必要な場合に使用します。複数の利用側にわたって依存関係の所有者が実質的に共有されている場合は、このアプローチを評価する目安となります。 検証方法：基盤の全レイヤーが完成した時点で、統合動作を検証します。

ハイブリッド

特性：プロジェクトの特性に応じて柔軟に組み合わせます。 適用条件：検証済みの基盤工程が先に必要で、その後の作業を独立して検証できる価値スライスとして進められる場合に使用します。実装アプローチを選択する前に、進行を妨げる要件の曖昧さを解消します。 検証方法：各フェーズの目標に応じた適切な L1／L2／L3 レベルで検証します。

フェーズ 7：意思決定の根拠を文書化

適用される実装または設計の意思決定記録に、次の内容を記録します。

1. 選択した戦略の名称と特性
2. 現在のエビデンス、および設計面での追加要素を正当化する総合的な複雑さの根拠
3. フェーズ 4 で有効となった重大な各リスクへの対策
4. フェーズ 5 で有効となった意思決定に関わる各制約との適合性
5. 検証レベル（L1／L2／L3）と統合ポイントの定義

別の選択肢は、承認済み ADR が意思決定の履歴として記録しない限り、引き続き分析対象とします。

検証レベルの定義

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

• L1：機能動作の検証 - エンドユーザー向けの機能として動作する（例：検索を実行できる）
• L2：テスト動作の検証 - 新しいテストが追加され、成功する
• L3：ビルド成功の検証 - コードがエラーなくビルド・実行される

優先順位：検証の重要度は L1 > L2 > L3 です。

統合ポイントの定義

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

• ストラングラーパターン型：各機能について、旧システムと新システムを切り替えるとき
• 機能主導型：ユーザーが実際に機能を利用できるとき
• 基盤主導型：すべてのアーキテクチャレイヤーが整い、E2E テストが成功したとき
• ハイブリッド：各フェーズに定義された個別の目標を達成したとき

品質チェック

1. Phase 1 で、戦略を選択する前に現在の責務、依存関係の経路、過去からの制約が特定されていることを確認します
2. Phase 2 で、完全な Selected Design が 1 つ作成され、追加された各設計要素が現在の根拠、より小さな設計要素では不十分であること、および要素を取り除いた場合に条件を満たせないことに対応していることを確認します
3. Phase 4 で、根拠のある重大なリスクごとに具体的な対策が記録されていることを確認します。該当しないカテゴリには記入不要です
4. Phase 5 で、戦略の選択または検証を変更し得る、根拠のある制約をすべて確認していることを確認します。該当しないカテゴリには記入不要です
5. Phase 7 で、選択した戦略、その総合的な複雑さの根拠、早期の検証ポイントが記録されていることを確認します。代替案は承認済み ADR にのみ記載します

メタ認知的な実行のガイドライン

1. 既知のパターンを活用する：問題とトレードオフが、確認されたリポジトリの状態に合致する場合は、そのパターンを使用します
2. 条件付きの外部調査：リポジトリを調査しても、時間とともに変化する機能、互換性、依存関係に関する判断が未解決の場合は、公式かつ最新の情報源を使用します
3. 5 Whys を適用する：根本原因を追究し、本質を把握します
4. 複数の観点から評価する：実装方針を選択する前に、現状、収束性、リスク、制約を評価します