architect-decision

architect-decision — 設計方針とアーキテクチャ上の決定

ドメイン評価基準

検討の軸

実装に着手する前に、根拠に基づく方針を確立します。該当しない軸は理由を添えて N/A とし、重要な軸は選択を確定する前に解決します。

• 問題の境界：求められている仕組みとは切り分けて、運用上の成果と観測可能な成功基準を定めます。
• 厳格な制約：時間、費用、コンプライアンス、データの安全性、プラットフォーム、チームの対応能力など、アプローチの種類を除外する譲れない条件です。
• 変更不可の範囲：変更せずに維持しなければならない契約、永続化データ、API、依存されている動作です。
• 可逆性の分類：一方通行の変更は取り消しを不可能にし、双方向の変更は外部コストなしで元に戻せます。具体的なロールバックのリスクを特定します。

検討の規律

• 問い合わせより先に推論する：ビジネス上の影響を尋ね、証拠から技術的制約を推論し、根拠のある既定案を提示して確認を求めます。

  Bad:  "Expected throughput? What p99 latency budget?"
  Good: "When an order fails, does it lose revenue or delay processing?"
        (Derive the durability requirement and offer it as a default.)
  

• 曖昧さのない迅速な進行：依頼と証拠からすでに確定している軸を固定し、未解決の選択肢についてのみ尋ねます。

• 検討に必要な情報：

  ### Axis<N>: <Framing Axis>
  Bottleneck: <Unresolved tension shaping the design space>
  [A] <Option> — Trade-off: <advantage> vs. <disadvantage>
  [B] <Option> — Trade-off: <advantage> vs. <disadvantage>
  Default: [Option] because <grounded rationale>
  

収束基準

候補を次の5項目すべてに照らして評価します。

• 問題の解決：検討で定めた成果を解決し、下流へ移すだけにしないこと。
• 制約への適合性：ほかの長所にかかわらず、厳格な制約に違反する候補は除外します。
• 先例による裏付け：開示された規模と明示された障害モードに基づき、実際の本番環境での先例を評価します。本番環境での証拠と、サンプルや主張を区別します。
• 可逆性：ロールバックのリスクを定量化し、ほかの基準を満たす場合は双方向の変更を優先します。
• 証拠の強さ：判断を左右する主張を、コードへの参照、検証済みの引用、または測定結果で裏付けます。リポジトリ内で確認できる事実は直接調べ、未解決の点は外部要因の不明点や未測定の実行時リスクに限ります。

収束と証拠の状態

• 裏付けがある場合は方針を1つに絞る：証拠が示す場合は1つのアプローチを選びます。拮抗する場合は、可逆性、変更不可の範囲の狭さ、確立された先例のシンプルさの順で判断します。証拠が不足している場合は、暫定候補または未解決の決定として維持します。
• 反証的なレビュー：根拠に基づく最も強い反論と、結論を変える観測可能な条件を示します。収束基準のいずれかで反論が優勢なら、結論を見直します。
• CONFIRMED：明示された条件のもとで、アーキテクチャ上の選択を裏付ける証拠が十分にあります。この状態は、実装が GREEN であることを宣言するものでも、変更を許可するものでもありません。
• INFERRED：推論に裏付けられた暫定候補ですが、明示された前提または証拠の確認に依存します。
• REJECTED：実現可能な候補が成果または制約を満たさないことを示す証拠に基づき、対象範囲を限定して実装しないと判断した状態です。その条件と根拠を明示します。
• UNRESOLVED：重要な不確実性があり、裏付けのある方針または候補を選べない状態です。

証拠の不足は必要な調査を特定するために使い、単なる不確実性ではなく、裏付けのある失敗を棄却の根拠とします。

調査の予算と委任

• 事前にソース、スキーマ、判断を規定する決定を確認します。対象範囲を絞って直接調査し、判断を左右する主張が裏付けられた時点、または不足点が特定された時点で終了します。
• 集中的な調査能力を超える複数のレイヤーやパッケージを調べる場合に限り、作業を委任します。分割した各範囲に、明確な境界、発見済みの手掛かり、検討の軸、候補、評価基準、サブレポートの契約を提示します。サブレポートには、証拠への参照、評価基準ごとの所見、反証、未解決点を含めます。レポートを固定済みの検討枠組みに照らして調整します。

標準出力の契約

# Architectural Decision: <Problem Slug>

## Decision & Boundaries
- **State**: <CONFIRMED | INFERRED | REJECTED | UNRESOLVED>
- **Conclusion**: <Supported direction, provisional candidate, justified bounded no-build, or what prevents selection>
- **Outcome**: <Operational outcome and observable success criteria>
- **Conditions**: <Evidence and scope under which the conclusion holds>
- **Boundaries**: Hard constraints: <constraints> | Frozen surface: <contracts/paths/APIs> | Reversibility: <class and exposure>

## Solution Mechanics
<Use a minimal comparison, interface boundary, state flow, or diagram when it explains a candidate. For rejection, state the disqualifying constraint or demonstrated failure. Omit if no candidate or rejection mechanism can be supported.>

## Cost & Falsification
- **Accepted Cost**: <Concrete trade-off; omit if no direction or candidate exists>
- **Counter-Case**: <Strongest sourced challenge> — changes conclusion when <observable condition>; omit if no defensible sourced counter-case exists, and record any decision-affecting review limitation under Open Gaps instead of inventing evidence
- **Open Gaps**: <External unknowns or runtime risks and what settles them; omit when none>

状態と、その条件および実質的な結論を分け、固定の振り分けメニューではなく、決定的な判断資料を1つ提示します。

振り分け

• 候補には実現可能性の証拠が必要です。問題、成功基準、候補、方針上の制約を引き継ぎます →（via /spike）。
• 裏付けのある方針が確定し、承認されています。証拠、境界、受け入れ基準を引き継ぎます →（via /changeset）。

実行プロトコル

フェーズ 1：根拠に基づく枠組みの設定とエビデンスの収集

1. アーキテクチャ上の要点を事前に調査し、依頼とソースのエビデンスに照らして枠組みの軸を評価します。
2. 未解決の軸について、根拠に基づくデフォルトを示します。独立した軸はまとめて提示し、ユーザーの応答を待ちます。すでに決着している場合は、簡易な手順を選択します。
3. 回答を取り込み、新たに明らかになった経路を調査します。要件の変更によって影響を受ける軸と主張のみを無効にし、変わらないコンテキストは維持します。
4. 調査予算の範囲内で評価基準に関するエビデンスを収集します。根拠に基づく委任は必要な場合に限って行います。

フェーズ 2：収束と成果の提示

1. 候補を採点し、必須条件と同点時の判断基準を適用したうえで、敵対的レビューを実施します。
2. エビデンスの状態と実質的な結論を選定します。適用条件と不足事項は、状態とは切り離して範囲を定めます。
3. コンテキストに応じた適切な経路で評価資料を提示し、ユーザーの判断を待ちます。このワークフローは読み取り専用とし、コード、実験、ワークスペースの変更は、別途実行するワークフローに委ねます。
   • 制約のあるビルド不要という結論に追加の対応が不要な場合は、引き継ぎを行わずに終了します。