architecture-exploration

アーキテクチャの検討

システムについて深く考察し、実現性のあるアーキテクチャ案を作成して、移行を始める前にユーザーが最適な方向性を選べるよう支援します。

このスキルは、意図的にコミット前の段階に限定されています。目的は適切なアーキテクチャを選ぶことであり、移行を実行することではありません。方向性が決まったら、作業を audit-and-migrate に引き継ぎます。

このスキルが存在する理由

大規模なエンジニアリングの取り組みは、コードを書くずっと前から失敗することがあります。

1. 早すぎる決定 — 有望なアイデアが、他の選択肢を十分に検討しないまま標準のアーキテクチャになります。
2. 局所的な推論 — エージェントが、システム全体の制約、責任範囲、障害モードを理解せずに、あるサブシステムだけを最適化します。
3. 藁人形の比較 — 望ましい案を弱い代替案と比較し、誤った確信を生み出します。
4. 移行の混入 — 目標アーキテクチャが実際に選ばれる前に、議論がいつの間にか「何を構築すべきか」から「どう実装すべきか」へ移ります。

このスキルは、実装前に規律ある検討を徹底するためにあります。

厳守すべき境界

このスキルでは、以下を行いません。

• 移行のスライスを作成する
• 実行用のラチェット予算を作成する
• リファクタリングを開始する
• 足場となるコードや実装コードを書く
• 比較が完了する前に、最有力案を勝者と見なす

このスキルでは、以下を行います。

• 現行システムを把握する
• 意思決定の枠組みを定める
• 有力な複数の選択肢を作成する
• 同じ制約に照らして比較する
• ストレステストを行う
• 方向性を推奨する
• audit-and-migrate への引き継ぎパッケージを作成する

これらの作業はすべて直接行ってください。検討の枠組み作り、ストレステスト、アーキテクチャの比較を、他のスキルに任せないでください。

ユーザーがすでに方向性を選び、安全に実現したいと考えている場合は、このスキルの使用を中止し、audit-and-migrate を使用してください。

中核となる原則

まず現状を掘り下げ、次に選択肢を比較し、その後で推奨する。

アーキテクチャの好みから始めないでください。実際のシステム、実際の制約、実際の問題から始めてください。

エビデンスに基づく判断

アーキテクチャを推奨する前に、その推奨に足る根拠を得てください。

対象システムについて、以下を積極的に調査してください。

• 現在のコードパス
• 責任範囲の境界
• 状態とデータの流れ
• 外部との契約や統合
• ドキュメントと運用上の接点
• 必要に応じて、明らかな履歴の兆候（最近の変更頻度、既知のインシデント、部分的な過去のリファクタリング）

ローカルのコードベースで答えを確認できる場合、ユーザーの要約だけを根拠に大規模な境界変更を推奨しないでください。

主張に不確実性がある場合は、不確実であることを明示してください。誠実なアーキテクチャの推奨とは、最大限の自信があるように聞こえることではなく、確信の度合いが根拠に見合っていることです。

ワークフロー

フェーズ 1：意思決定の枠組みを定める

選択肢を検討する前に、実際に何を決定するのかを明確にしてください。

以下を整理します。

• 目標 — ユーザーが望む成果
• 問題 — 変更の動機となる課題や障害モード
• 不変条件 — 必ず維持しなければならないこと
• 対象外 — スコープに含めないこと
• 制約 — チーム、ツール、パフォーマンス、コンプライアンス、時間、互換性、運用、組織上の制限
• 外部との接点 — API、環境変数、キュー、ダッシュボード、CLI のエントリポイント、ジョブ、データ契約、Webhook、パートナーとの統合
• 意思決定の時間軸 — 今後 3 か月、1 年、3 年のどの期間を最適化するか

ユーザーがすでに候補となる解決策を考えている場合、それを結論ではなく選択肢 Aとして扱ってください。

フェーズ 2：現在のシステムを把握する

代替案を提案する前に、現在のシステムを理解します。

影響を受けるシステムについて、次の項目をマッピングします。

• 主要なワークフロー
• 現在のモジュール境界
• データフロー
• ロジックと状態の所有者
• 外部依存関係
• 運用上の接点
• 既知の課題
• 問題が集中している箇所 — 壊れやすい領域、変更頻度の高いファイル、不安定なテスト、所有者が不明確な領域、重複したロジック、古くなったドキュメント

現状を簡潔にまとめます。

## Current System
| Area | Current Owner | Inputs | Outputs | Dependencies | Pain |
|------|---------------|--------|---------|--------------|------|
| ...  | ...           | ...    | ...     | ...          | ...  |

ユーザーが「システムについてはすでに知っている」と言っても、この手順を省略してはいけません。選択肢を厳密に比較するには、現状について共通認識を持つ必要があります。

フェーズ 3：選択肢を作成する

2〜4 個の、真剣に検討できるアーキテクチャ上の選択肢を作成します。

見せかけの代替案を作成してはいけません。どの選択肢も、優れたチームが合理的に選びうるものでなければなりません。

可能であれば、次の選択肢を含めます。

• 選択肢 1：進化的な道筋 — 変更による影響を抑えつつ、現在のシステムを改善します
• 選択肢 2：簡素化する道筋 — 概念と間接性を積極的に取り除きます
• 選択肢 3：構造的な道筋 — より強固な境界、または新しいアーキテクチャ構造を導入します
• 選択肢 4：何もしない — 想定より小さな変更で問題を解決できる可能性がある場合に検討します

各選択肢について、次の項目を説明します。

• アーキテクチャの構造
• 境界の変更
• 所有モデル
• データフロー
• 運用モデル
• 維持されるもの
• 変更されるもの
• より簡単になること
• より難しくなること

フェーズ 4：各選択肢を分析する

各選択肢について、同じ分析を行います。

A. 適合性

その選択肢は、次の項目をどの程度満たしますか。

• 目標
• 不変条件
• 制約
• 外部に対する責務

B. 前提条件

必ず成り立っていなければならない前提条件を列挙します。

## Must-Be-True Assumptions
| Assumption | Why It Matters | How to Verify | Fastest Disproof |
|------------|----------------|---------------|------------------|
| ...        | ...            | ...           | ...              |

C. 失敗要因

その選択肢が 1 年後に失敗したと想定し、原因をさかのぼって考えます。

## Pre-Mortem
| Failure Mode | Warning Signal | Prevention |
|--------------|----------------|------------|
| ...          | ...            | ...        |

D. トレードオフ

各選択肢を次の観点から評価します。

• 概念の数 — 習得して使いこなす必要がある新しい考え方はいくつあるか
• 境界の明確さ — 所有関係はより明確になるか、それとも曖昧になるか
• 移行の難易度 — 後から実現するのはどれほど難しいか
• 後片付けの負担 — 使われなくなったコード、ドキュメント、設定、アダプターが残る可能性はどの程度か
• ロールバックの見通し — 元に戻すのはどれほど難しいか
• 運用性 — モニタリング、デバッグ、障害対応、サポートの負担
• テスト容易性 — システムを決定論的に検証できるか
• 拡張性 — どのような将来の変更が容易になるか
• ロックイン — どのような新たな制約が生じるか

根拠を添えて相対的に評価します。見せかけの精密さは避けます。

## Tradeoff Matrix
| Dimension | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| Simplicity | Medium — ... | High — ... | Low — ... |
| Migration Difficulty | ... | ... | ... |
| Cleanup Burden | ... | ... | ... |
| Operability | ... | ... | ... |
| Testability | ... | ... | ... |
| Long-Term Flexibility | ... | ... | ... |

E. 選択肢を不適切にする条件

各選択肢について、どのような条件が当てはまれば不適切な選択となるかを述べます。

例：

• プロジェクトで必要のない互換性が求められる
• チームの対応能力を超えて運用負担が増える
• 移行時に後片付けの負債が過剰に発生する
• チームが管理できない外部契約に依存する
• 十分な見返りなしに概念が増える

F. 不明点

何がまだ不確かですか。次の項目に分けます。

• アーキテクチャ上の不明点 — 境界や所有関係に関する不確実性
• 実行時の不明点 — 負荷、レイテンシ、並行性、障害時の挙動
• 組織上の不明点 — チームの準備状況、外部の利用者、運用上の制約

フェーズ 5：推奨する

選択肢を並べるだけで終わらせてはいけません。推奨案を示します。

推奨案には次の項目を含めます。

• 推奨する選択肢
• それが最善である理由
• 次点が劣る理由
• その他の選択肢を却下した理由
• 推奨が変わりうる条件
• 決定前に検証すべきこと

推奨案を本当に決められない場合は、その旨を述べ、適切な判断を妨げている不確実性を具体的に説明します。

フェーズ 6：検証用のスパイクを定義する

決定を下す前に、不確実性を解消するため、コストが低く価値の高いスパイクを提案します。

有効なスパイクは、次のようなものです。

• 対象が限定されている
• 短時間で実施できる
• 根拠を得られる
• アーキテクチャの判断に関係する

例：

• コンパイル時のモジュール骨格
• 重要なワークフローを 1 つだけ通す最小限の経路
• イベント／キューの境界を検証する実証
• データ契約の形を証明するフェイクアダプター
• ボトルネックの疑いがある箇所を対象とした負荷実験

各スパイクについて、次の項目を示します。

## Validation Spikes
| Spike | Question Answered | Cost | Success Signal | Failure Signal |
|-------|-------------------|------|----------------|----------------|
| ...   | ...               | ...  | ...            | ...            |

フェーズ 7：audit-and-migrate への引き継ぎを準備する

ユーザーが方向性を選んだら、決定内容を整理して引き継ぎます。

引き継ぎのセクションには、次の項目を含めてください。

• 選択したアーキテクチャ
• 決定の根拠
• 不変条件
• 対象外事項
• 重要なワークフロー
• 外部に公開されるインターフェース
• 既知のホットスポット
• 主な移行リスク
• 削除が見込まれる領域 — 廃止される可能性が高いコード、ドキュメント、スクリプト、設定、環境変数、アダプター
• 実施済みの検証スパイク
• 今後、証明が必要なこと

このセクションによって、アーキテクチャの議論を蒸し返すことなく、audit-and-migrate を始められるようにします。

出力要件

重要な探索では、意思決定に十分な成果物を .claude/architecture/ARCHITECTURE_OPTIONS.md またはプロジェクト内の同等のドキュメント配置先に作成してください。

次の構成を使用してください。

# Architecture Exploration: [System Name]

## Goal

## Problem

## Invariants

## Non-Goals

## Constraints

## External Surfaces

## Current System
| Area | Current Owner | Inputs | Outputs | Dependencies | Pain |

## Option 1: [Name]
### Architecture Shape
### Why It Might Work
### Tradeoffs
### Failure Modes
### Disqualifiers
### Cleanup / Migration Implications
### Unknowns

## Option 2: [Name]
...

## Tradeoff Matrix
| Dimension | Option 1 | Option 2 | Option 3 |

## Assumptions
| Assumption | Why It Matters | How to Verify | Fastest Disproof |

## Risk Register
| Risk | Option(s) Affected | Likelihood | Impact | Mitigation |

## Validation Spikes
| Spike | Question Answered | Cost | Success Signal | Failure Signal |

## Recommendation

## Runner-Up

## Why The Other Options Lose

## Decision Needed

## Handoff to audit-and-migrate

小規模な依頼では、同じ構成を会話内に提示します。

推論の基準

根拠のない精密さを避ける

実際には厳密な評価をしていないのに、厳密さを示唆する数値評価を作り出さないでください。根拠のない加重合計より、説明を添えた相対評価が適切です。

好みより証拠を優先する

アーキテクチャに対する好みは証拠ではありません。推奨事項は、次の点を根拠にしてください。

• コードベースの構造
• 確認された制約
• 運用上のインターフェース
• 移行の負担
• クリーンアップの負担
• 障害モード

よりシンプルな選択肢を必ず含める

すべての選択肢で概念的な複雑さが増すなら、よりよい道を見落としている可能性があります。

書き直しを既定の選択肢にしない

全面的な書き直しや大規模な構造のリセットは、採用に値することを示す必要があります。通常、最初に選ぶべき方法ではありません。

トレードオフを公平に比較する

すべての選択肢を同じ基準で精査してください。ユーザーの好みに合う選択肢でも、洗練されているように見えるという理由でストレステストを緩めないでください。

終了のタイミング

次の条件を満たしたら、探索は完了です。

• 代替案を比較できる程度に、現行システムが明確に把握されている
• 真剣に検討する価値のある選択肢が少なくとも 2 つ含まれている
• 各選択肢に、明示的なトレードオフと障害モードがある
• 推奨事項が証拠に基づいている
• 次のステップが明確である。検証スパイクを実施するか、audit-and-migrate を開始する

これらの条件を満たしたら、探索を終了し、決定を推奨してください。

audit-and-migrate との関係

次の質問に答えるには、このスキルを使用します。

• 「どのアーキテクチャを選ぶべきですか？」
• 「どのような選択肢がありますか？」
• 「ここでは、どの設計上のトレードオフが最適ですか？」

答えが次の段階になったら、audit-and-migrate を使用します。

• 「Option B を採用します」
• 「次は移行を計画してください」
• 「次は安全に実装してください」