software-solution-architecture

ソフトウェアソリューションアーキテクチャ

単一のサービスやデプロイ可能な境界ではなく、ビジネスワークフロー、運用モデル、システムランドスケープ、または移行上の課題から質問が始まる場合に、このスキルを使用します。

このスキルでは、まずソリューションの形を決めます。ビジネスフロー、関与するシステム、移行の形が明確になるまでは、モジュラーモノリスとマイクロサービスの比較、CQRS、サービスメッシュ、MCP/A2Aなどのランタイムパターンをデフォルトで選びません。

ソリューションの形が定まり、次の課題がサービス分解、分散整合性、プラットフォームエンジニアリング、またはランタイムトポロジーである場合は、../software-architecture-design/SKILL.mdを使用してください。

クイックリファレンス

必要なこと	デフォルトの対応	次に読むもの
複数のシステムにまたがるターゲットソリューションを設計する	パターンを選ぶ前に、ビジネスフローをシステム、責務、制約に対応付けます	references/solution-workflow.md
統合スタイルと境界を比較する	判断マトリクスに基づき、API、イベント、バッチ、ファイル、Webhook、BFF、または腐敗防止境界を選びます	references/integration-and-boundary-patterns.md
ケイパビリティ、オーナー、SoRを対応付ける	ビジネスケイパビリティ、担当チーム、境界の種類、信頼できる唯一の情報源に関する判断を記録します	assets/planning/capability-boundary-map.md
段階的な移行を計画する	共存、切り替え、ロールバックのルールを定め、現状、中間、目標の各状態を定義します	references/transition-architecture.md
デリバリーを安全な段階に分ける	移行段階の開始、ロールバック、廃止の基準を記録します	assets/planning/transition-wave-planner.md
最終提案をまとめる	目標状態、選択肢、移行、リスク、引き継ぎ事項を要約します	assets/planning/solution-blueprint.md

このスキルを使用しないケース

• ランタイムや分散システムの詳細設計 → ../software-architecture-design/SKILL.md
• 単一サービスの実装 → ../software-backend/SKILL.md
• APIコントラクトの詳細設計 → ../dev-api-design/SKILL.md
• インフラ／プラットフォーム運用が主な課題 → ../ops-devops-platform/SKILL.md
• セキュリティアーキテクチャが主な課題 → ../software-security-appsec/SKILL.md

境界ルール

• このスキルでは、システムランドスケープ、選択肢の比較、移行の形を扱います。
• このスキルでは、変更しないもの、今変更するもの、意図的に先送りするものを明示します。
• このスキルでは、デプロイ可能な単位の数、内部サービスのトポロジー、または選択したソリューション内部の詳細な整合性メカニズムの決定には踏み込みません。
• 主な課題がランタイム境界、境界づけられたコンテキスト、レジリエンスの内部設計、またはプラットフォームのデフォルト設定になったら、../software-architecture-design/SKILL.mdに引き継ぎます。
• 移行の境界：このスキルでは、どのシステムを、どの順序で、どのロールバック基準と廃止基準で共存させるかという、システム横断の段階的な計画を扱います。一方、単一システム内部の抽出や分解の仕組み（ストラングラーフィグの手順、データベースの分解、シャドートラフィック）は扱いません。ターゲットアーキテクチャと分解の選択肢については、../software-architecture-design/SKILL.mdのmigration-modernization-guide.mdとestate-modernization.mdを参照してください。実行の仕組み（同等性の判定基準、接合点、段階的な展開）については、../qa-refactoring/SKILL.mdのstrangler-fig-migration.mdとcross-language-rewrite.mdを参照してください。

デフォルトのワークフロー

1. ビジネスシナリオ、関係者、成功指標を定義します。
2. 現行システム、所有権の境界、重大な課題を把握します。
3. ビジネスケイパビリティをシステムの所有者および信頼できる情報源となるシステムに対応付けます。
4. コンプライアンス、レイテンシ、データの保管場所、レガシー依存関係、ベンダーの制限、ロールアウトの制限など、厳守すべき制約を明確にします。
5. システムランドスケープレベルで、実現可能なソリューション案を2～3件提案します。
6. 目標状態を選択し、必要に応じて最小限の実行可能な暫定状態を定めます。
7. システムの責任範囲、統合方式、データの移動、信頼境界、検証チェックポイントを定義します。境界方式の選択には、統合の意思決定マトリクスを使用します。
8. ロールバックポイント、共存ルール、廃止基準を含めて、移行ウェーブの順序を決めます。
9. ソフトウェアアーキテクチャ、API、セキュリティ、プラットフォーム運用など、より深い検討は関連スキルに引き継ぎます。

必須の出力形式

すべての推奨事項には、次の項目を含める必要があります。

• 問題の説明とシステムの対象範囲
• 対象に含める境界と、意図的に対象外とする境界の明示
• ケイパビリティ、所有権、信頼できる情報源となるシステムの概要
• 現状と目標状態の概要
• 変更を段階的に進める場合は、暫定状態の概要
• 測定可能なNFRシナリオに照らして評価し、選択肢ごとのコスト（構築、運用、移行、撤退）を示した推奨案と却下した代替案 — references/option-scoring.mdを参照
• 統合とデータフローの構成
• 該当する場合は、ロールバックまたは終了基準を含む移行ウェーブ計画
• 主なリスク、障害モード、検証チェックポイント
• 現時点では決定しない事項
• 関連スキルへの明示的な引き継ぎ
• 選択肢の各判断に対するADR（またはADRとして使用できる概要）：背景、決定、ステータス、結果 — 却下した代替案も後から追跡できるようにし、採用案だけを記録することがないようにします

構築と購入とパートナー連携の比較

シグナル	検討する方向	理由	注意点
ケイパビリティに差別化要素がなく、成熟したベンダーが提供している（例：KYC、決済処理、メール配信）	購入	価値実現までの時間を短縮でき、購入したケイパビリティの運用をベンダーに任せられます	データのエクスポートに関するベンダーロックインや、成長を妨げる料金体系に注意してください。統合とコンプライアンスに関する責任は引き続き自社にあります
ケイパビリティが、ビジネスの競争力を左右する中核的な差別化要素である	構築	中核的な差別化要素を購入すると、競合他社も同じものを購入できてしまいます	実際にはコモディティであるものを構築しようとするサンクコストバイアスに注意してください
ケイパビリティに、独自の社内データやワークフローとの深く継続的な統合が必要である	構築または大幅にカスタマイズ	市販のツールでは、独自性の高い社内プロセスをうまくモデル化できないことがよくあります	「購入」の見積もりが単体では安価に見えるため、統合コストを過小評価しないようにしてください
構築したソリューションを長期的に運用できる社内チームがない	購入またはパートナー連携	所有者のいないカスタムシステムは、サポートされているベンダー製品より早く劣化します	一度限りの予算サイクルを理由に「構築」を選び、運用コストの責任を見落とさないようにしてください
規制または契約上の条件により、特定された監査可能な第三者が必要である	パートナー連携（規制対象ベンダー）	社内で構築しても満たせない義務があります	ベンダーの認証がベンダー自身の境界だけでなく、統合全体を網羅していると思い込まないようにしてください

ベンダーのケイパビリティに関する主張は、組織の実際の制約（データの保管場所、認証モデル、サポートSLA、契約終了時の条件やエクスポート条件）に照らして確認するまでは、未検証として扱ってください。データシートに記載されたケイパビリティが、必ずしもこのランドスケープの所有権やコンプライアンスの境界に適合するとは限りません。

パターン選択を超えたランドスケープの選択肢

• 統合のバックボーン：完全に相互接続されたポイントツーポイントのランドスケープでは、可能なリンクの数が二次的に増えます。実際の統合コストは、必要なリンクと契約によって決まります。iPaaS またはイベントバックボーンを導入すると、統合作業の重複を減らせますが、共有依存関係とガバナンスの責任者が加わります。必要な接続性と、システム横断の変更を誰が所有するかに基づいて選択してください。
• ランドスケープにおけるエージェントと LLM の参加者：どのシステムがエージェントから呼び出し可能なインターフェース（MCP など）を公開するか、またエージェントが開始する書き込みに対する信頼境界をどこに置くかを明記してください。他の書き込み元に適用するのと同じ正式なデータの承認ゲートを通さずに、エージェントが記録システムを変更できるようにしてはいけません。ランタイムレベルのエージェントおよびツールゲートウェイの設計については、../software-architecture-design/SKILL.md を参照してください。

チームトポロジーとコンウェイの法則の確認

コンウェイの法則では、意図的かどうかにかかわらず、システムランドスケープには組織のコミュニケーション構造が反映されると予測されます。目標状態を確定する前に、次の点を確認してください。

• 各記録システムと各統合境界をどのチームが所有するかを明確にしてください。所有チームが明確でない境界には、その場しのぎで文書化されていない結合が蓄積します。
• 提案する目標状態の実現に、まだ存在しないチーム構成（共有プラットフォームチームや新しいドメインチームなど）が必要かどうかを確認してください。必要な場合、移行計画には組織設計の変更を前提ではなく、明示的な依存関係として含める必要があります。
• 変更のたびにチーム間の調整が必要となる、アーキテクチャ上は洗練されていても実現に調整コストがかかる目標状態より、実際に想定されるチームの境界に合致する目標状態を優先してください。調整コストは実コストであり、無視できる誤差ではありません。
• 現在のチーム構成に意図的に逆らう目標状態（望ましいアーキテクチャを実現するための「逆コンウェイ・マヌーバ」）を採用する場合は、その旨を明記し、組織変更の推進責任者を明確にしてください。図の暗黙の副作用にしてはいけません。

検証チェックリスト

正式なデータの承認ゲート。

システム間を移動するすべてのビジネスエンティティについて、正式な所有権と収束ルールを明記してください。ルールには、単一の書き込み元、パーティションが所有する書き込み元、または意図的な複数書き込み元のセマンティクスがあります。許可されるレプリカ、伝播と因果順序のルール、決定論的な競合解決またはマージの動作、障害処理、および照合の責任者を文書化してください。これらのセマンティクスなしに、各システムが同じ事実を独立して変更できる設計は却下してください。移行計画には、一時的なデュアルライトの所有者を含め、その廃止に必要な証拠を定義してください。

ソリューションの推奨を確定する前に、次の項目を確認してください。

• ビジネス上の課題と成功指標を、技術用語を使わずに定義している
• 参加するすべてのシステムについて、明確な所有者と記録システムとしての役割を示している
• 厳しい制約を把握している：コンプライアンス、レイテンシ、データレジデンシー、ベンダーの制限、ロールアウトの制限
• 2～3 個のソリューション案を比較し、代替案を却下する理由を明示している
• 統合スタイルを、API をどこでも使うという既定の選択ではなく、意思決定マトリックスに基づいて選択している
• 変更を段階的に行う場合、中間状態を定義している（現状と目標だけではない）
• 移行ウェーブにロールバック基準、終了条件、廃止計画がある
• まだ決定しないことを明示している
• 関連スキル（アーキテクチャ、API、セキュリティ、プラットフォーム）への引き継ぎ先を明記している
• 各選択肢の決定について、ADR または ADR にまとめられる要約（コンテキスト、決定、ステータス、影響）がある
• ベンダーまたはプラットフォームの購入を検討する機能について、内製・購入・提携の判断理由を示している
• 目標状態を実際のチーム所有権（コンウェイの法則）に照らして確認し、まだ存在しないチームが目標状態の実現に必要な場合は、組織設計上の依存関係を明記している

既知の落とし穴

• 所有権とシステムオブレコードの境界を明確にする前に、ビジネス上の課題からマイクロサービス、イベントバス、プラットフォームの購入へと飛躍する。
• 組織が実際に乗り越えなければならない、移行期間中の共存、契約の重複、ロールバックの制約を無視した、整然とした目標状態を描く。
• 一方が正となる情報源である、レート制限がある、法的な制約がある、あるいは政治的に変更が難しい場合に、連携を対称的なものとして扱う。
• 将来状態の図によって、手作業での回避策、サポート負荷、データ照合の負担といった現在の運用上の課題を覆い隠す。
• あまりに多くのチームやシステムにまたがる、あるいは不可逆なデータ移行が多すぎる移行ウェーブを一つ選ぶ。
• チームの所有権や運用モデルを検証せずに、エンタープライズツールの機能を、確実な導入、ガバナンス、実行環境への適合性と取り違える。
• 明示的にトレードオフを示さず、ビジネスの真の差別化要因となる機能に「購入」を推奨したり、成熟したベンダーがすでに解決しているコモディティ機能に「構築」を推奨したりする。
• 組織に存在しないチーム構成を暗黙に必要とする、洗練された目標状態の図を設計しながら、組織設計への依存関係を明示しない。

マネージド移行サービスやリファクタリングサービスを選択肢に含める前に、提供元のドキュメントで利用可否、リージョンのサポート状況、移行範囲、終了時の動作を確認してください。ストラングラーフィグ、ACL、拡張／縮小といった持続性の高いパターンは、それを実装するために選んだ製品とは分けて記載してください。

よくあるアンチパターン

• 実際には実行環境に関するアーキテクチャの好みを装った、ソリューションの推奨を提示する。
• バッチ、ファイル、イベント、または腐敗防止パターンのほうが状況に適している場合でも、すべての境界をAPIの課題として扱う。
• 信頼境界、データ管理責任、信頼できる唯一の情報源をめぐる競合を、実装の詳細として曖昧に済ませる。
• 開始状態と終了状態だけを記した移行計画を作成し、移行期間中の明示的な制御、終了基準、廃止計画を設けない。
• 全社で一つのプラットフォームへの標準化を強制し、置き換えコストが統一によるビジネス価値を上回る場合を考慮しない。

ナビゲーション

リファレンス

• references/solution-workflow.md — ビジネスフローを起点とするソリューション設計ワークフロー
• references/integration-and-boundary-patterns.md — API、イベント、ファイル、バッチ、Webhook、BFF、ACLの境界に関する判断マトリクス
• references/transition-architecture.md — ウェーブ管理を含む、現状・移行期間・目標状態の計画
• references/option-scoring.md — NFRシナリオ、システム間の可用性／レイテンシ予算、選択肢ごとのコスト骨子、ベンダーのデューデリジェンスと終了計画
• references/cybernetics-vsm-applied.md — ソリューションアーキテクチャとシステムの存続可能性に適用するVSM、アシュビーの法則、フィードバックループ、アルジェドニック・チャネル。

テンプレート

• assets/planning/solution-blueprint.md — 最終推奨案の設計書
• assets/planning/capability-boundary-map.md — ケイパビリティ、所有権、システムオブレコードのワークシート
• assets/planning/transition-wave-planner.md — ロールバック基準と廃止基準を含む移行ウェーブ計画ツール

検証

• evals/evals.json — このスキルの発動、非発動、境界付近の動作チェック

関連スキル

• ../software-architecture-design/SKILL.md
• ../software-backend/SKILL.md
• ../dev-api-design/SKILL.md
• ../software-security-appsec/SKILL.md
• ../ops-devops-platform/SKILL.md

主要なソースは data/sources.jsonにあります。

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または他に利用できるものがない場合に限り、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、覚えておく価値のあるパターン、防止すべきミス、または意外だった分野の事実に気づいた場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付付きの箇条書きを learnings.md に1つ追記してください。SKILL.md 自体は変更しないでください。