software-architecture-design

ソフトウェアアーキテクチャ設計

ビジネスワークフロー、システムランドスケープ、目標状態、または段階的なシステム横断移行から質問が始まる場合は、まず ../software-solution-architecture/SKILL.md を参照し、実行時の詳細、分解、運用性についてはこのドキュメントを参照してください。

エステートのモダナイゼーション、プラットフォームエンジニアリング、AI ネイティブな相互運用性は、任意の詳細トピックとして扱います。ユーザーが明示的にこれらのテーマについて尋ねている場合を除き、読み込まないでください。

クイックリファレンス

タスク	パターン／ツール	主なリソース	使用するタイミング
アーキテクチャスタイルを選択する	モジュラーモノリス（デフォルト。以下の判断要因を参照）。独立したデプロイや所有権のニーズが明確になったら、レイヤード、マイクロサービス、イベント駆動型、またはサーバーレスを選択	modern-patterns.md	グリーンフィールドプロジェクト、大規模なリファクタリング
API 境界の方針を決定する（アーキテクチャレベル）	エンドポイント設計ではなく、コントラクトの方針とバージョニング戦略	api-gateway-service-mesh.md	サービス間コントラクトの決定がアーキテクチャ上の課題である場合
スケーラビリティを考慮して設計する	負荷分散、キャッシュ、シャーディング、読み取りレプリカ	scalability-reliability-guide.md	トラフィックの多いシステム、パフォーマンス目標がある場合
レジリエンスを確保する	サーキットブレーカー、リトライ、バルクヘッド、グレースフルデグラデーション	scalability-reliability-guide.md	分散システム、外部依存関係がある場合
意思決定を文書化する	アーキテクチャ決定記録（ADR）	adr-template.md	重要な技術的決定、トレードオフ分析
サービス境界を定義する	ドメイン駆動設計（DDD）、境界づけられたコンテキスト	microservices-template.md	マイクロサービスへの分解
データの一貫性をモデル化する	ACID と BASE、イベントソーシング、CQRS、Saga パターン	data-architecture-patterns.md	複数サービスにまたがるトランザクション
オブザーバビリティを計画する	SLI／SLO／SLA、分散トレーシング、メトリクス、ログ	architecture-blueprint.md	本番環境への準備
モノリスから移行する	ストラングラーフィグ、データベースの分解、シャドートラフィック	migration-modernization-guide.md	レガシーのモダナイゼーション
サービス間通信を設計する	API ゲートウェイ、サービスメッシュ、BFF パターン	api-gateway-service-mesh.md	マイクロサービスのネットワーキング
デリバリープラットフォームを設計する	IDP、ゴールデンパス、フィットネス関数	fitness-functions-governance.md	複数チームのプラットフォーム、ガバナンス
サービスの乱立を整理する	境界づけられたコンテキストを基盤とするプラットフォーム、リポジトリとランタイムのマトリクス、プラットフォームスコアカード	estate-modernization.md	20 以上のリポジトリ、サービスが多すぎる場合、プラットフォーム成熟度にばらつきがある場合
エステートのモダナイゼーションを計画する	プラットフォーム優先の移行ウェーブ、統合、互換性境界	estate-modernization-blueprint.md	複数リポジトリにまたがるエステート、規制対象の移行、レガシーの削減
AI ネイティブシステムを設計する	RAG の境界、ツールゲートウェイ、エージェントの相互運用性、MCP、A2A	architecture-trends.md	アーキテクチャが主な論点であり、実装ではない LLM 搭載製品

このスキルを使用しない場合

次の場合は、代わりに別のスキルを使用してください。

• システム横断のソリューション設計（業務フロー、目標状態、統合環境、システム間の段階的な移行） → software-solution-architecture
• 単一サービスの実装（ルート、コントローラー、ビジネスロジック） → software-backend
• API エンドポイントの設計（REST の規約、GraphQL スキーマ） → dev-api-design
• セキュリティの実装（認証、暗号化、OWASP） → software-security-appsec
• フロントエンドのコンポーネントアーキテクチャ → software-frontend
• データベースクエリの最適化 → data-sql-optimization
• エージェントのワークフロー実装／MCP サーバーの実装 → ai-agents、agents-mcp

境界に関するルール

• このスキルが対象とするのは、ランタイム境界、デプロイ可能な単位の判断、データ整合性に関するトレードオフ、レジリエンスの内部設計、プラットフォームのデフォルト設定です。
• 制約を満たす最もシンプルなアーキテクチャから始めてください。明確な根拠なしに、マイクロサービス、イベントソーシング、サービスメッシュ、マルチエージェントへの分割をデフォルトにしないでください。
• 未解決の疑問が「どのシステムが関与するのか、どこがシステム・オブ・レコードなのか、目標状態のシステム環境はどのようなものか」である場合は、software-solution-architectureに戻してください。
• 未解決の疑問がエージェントプロトコル、ツールサーバー、ランタイム固有の統合の実装に関するものである場合は、ai-agentsまたはagents-mcpに案内してください。
• 移行の境界：このスキルが対象とするのは、単一システム内での抽出や分解の手順です。これにはストラングラーフィグの手順、データベースの分解、シャドートラフィック（migration-modernization-guide.md、estate-modernization.md）が含まれます。対象外なのはシステム横断の段階的な移行計画（どのシステムがどの順序で共存し、どのようなロールバック／廃止の基準を適用するか）です。これは../software-solution-architecture/SKILL.mdのtransition-architecture.mdが対象とします。

意思決定ツリー：アーキテクチャパターンの選択

Primary question: [What kind of architecture problem is this?]
    ├─ Large estate with many repos/services and rising cognitive load?
    │   ├─ Runtime count is the main problem → Bounded-context platforms + selective consolidation
    │   ├─ Delivery inconsistency is the main problem → IDP + golden paths + scorecards
    │   └─ Both are true → Platform-first modernization, then consolidate low-value runtime units
    │
    ├─ Deterministic workflow, known steps?
    │   ├─ Single deployable acceptable → Modular Monolith
    │   ├─ Independent teams/capabilities required → Sequential or event-driven services
    │   └─ Burst-driven or edge-triggered workload → Serverless / event-driven
    │
    ├─ Adaptive workflow with tool use and reasoning?
    │   ├─ One agent can own the task → Single-agent system
    │   ├─ Specialized roles truly needed → Multi-agent with explicit stop conditions
    │   └─ High stakes / regulated workflow → Human-in-the-loop + audit trail
    │
    ├─ Strong consistency inside one domain boundary?
    │   ├─ Keep data and writes together → Monolith or Modular Monolith
    │   └─ Split only at stable bounded contexts → Microservices with owned data
    │
    └─ Need platform-level consistency across many teams?
        ├─ Repeated service creation / compliance needs → IDP + golden paths
        └─ Cross-agent or cross-vendor interoperability → MCP for tools/context, A2A for agent-to-agent

意思決定の要素：

• デフォルトの方針：独立したデプロイ、オーナーシップ、運用性のメリットが明確でない限り、マイクロサービスよりモジュラーモノリスを優先します。チーム規模、リリース頻度、運用成熟度に関する明確な条件については、modern-patterns.md § モジュラーモノリスとマイクロサービスを参照してください。
• システム全体の方針：リポジトリ数を減らすことよりも、実行単位を減らすことを優先します。リポジトリはコラボレーションの単位であり、実行環境は運用コストの発生源です。
• エージェントの方針：マルチエージェントの連携を導入する前に、決定的なワークフローまたは単一エージェントを優先します。
• 接続性の方針：mTLS、トラフィックポリシー、共有テレメトリの必要性からメッシュの複雑さが正当化されるまでは、ゲートウェイとアプリケーションライブラリのパターンを優先します。
• チーム構造（コンウェイの法則）：アーキテクチャは組織構造を反映します
• デプロイの独立性に関する要件
• 一貫性と障害ドメインの境界
• 運用成熟度（監視、オーケストレーション）
• 相互運用性の要件（プロトコル、コントラクト、外部システム）

分割する場所：フラクチャープレーン（Skelton と Pais 著、『Team Topologies』第2版、2025年）。フラクチャープレーンとは、「ソフトウェアシステムを2つ以上の部分に簡単に分割できる、システム内の自然な継ぎ目」です。これは石工の作業になぞらえたものです。候補となるプレーンは、ビジネスドメインの境界づけられたコンテキスト（デフォルトであり、ほとんどの分割で対応させるべきもの）、規制遵守、変更頻度、チームの所在地、リスク、パフォーマンスの分離、テクノロジー、ユーザーペルソナです。

• リトマス試験（引用）：「できあがるアーキテクチャは、認知負荷（多岐にわたる責任）を軽減しながら、より自律的なチーム（依存関係の少ないチーム）を支援しますか？」具体的には、分割後に各チームが別のチームと調整せずに、自分たちの担当部分を構築、テスト、デプロイできるでしょうか？
• 複合ルール：実際の境界は通常、複数のプレーンを組み合わせます。「異なる種類のフラクチャープレーンを組み合わせてモノリスを分解することは、可能であり、そうすべきです」。また、「多くの場合、複数のフラクチャープレーンの組み合わせが必要です」。
• 分散モノリスへの警告：チームとそのリリース経路に境界を合わせずにソフトウェアを分割すると、自律性が得られないまま分散のコストだけが発生します。本書では、Amy Phillips の言葉を引用しています。「マイクロサービスを使っているのに、リリース前にそれらを組み合わせたエンドツーエンドテストが終わるのを待つなら、それは分散モノリスです」。結合はサービス境界の内側にも忍び込みます。共有データベース、結合されたビルドやリリースがその例です。
• セグメントをチームの規模に合わせます：「チームが持続可能な形でソフトウェアを効果的に所有し、進化させられるように、ソフトウェアセグメントをチームの規模に合わせることが不可欠です」。

パターンの詳細についてはreferences/modern-patterns.mdを、提案する継ぎ目をまたいで強い結合が残らないか確認するにはreferences/modern-patterns.md § コンネサンスを参照してください。

出力ガイドライン

このスキルの参考資料は、背景知識として活用してください。パターンを理解し、自分自身の専門知識として提示してください。ユーザー向けの出力で、内部の参考ファイル名（例：「data-architecture-patterns.mdから」）を引用しないでください。ユーザーはこれらのファイルの存在を知りません。

アーキテクチャに関するすべての推奨事項で、次の項目を扱ってください。明示的な理由がある場合に限り、項目を省略できます。

• 要件を満たす最もシンプルなトポロジー — 要件を満たす最も複雑さの低いアーキテクチャを明示する
• 具体的な技術の選定 — 具体的な技術を挙げる（例：「オーケストレーター」だけでなく、「ワークフローオーケストレーションにTemporal.io」）
• 推奨案と却下した代替案 — 検討した選択肢と、代替案を採用しなかった理由
• 構築しないもの — 時期尚早なスコープを明示的に先送りまたは除外する
• チームとプロセスの連携 — CODEOWNERS、デプロイのオーナーシップ、オンコールの境界
• リポジトリとランタイムのモデル — 複数リポジトリの環境では、リポジトリ数とデプロイ可能な単位の数を区別する
• 運用性のモデル — デプロイのトポロジー、障害ドメイン、ロールバックポイント、SLOのオーナーシップ、インシデントの境界
• 移行パス — 手順、切り替え戦略、可逆性（リファクタリングや新しいサブシステムの場合）
• 主なリスクと障害モード — 破綻点を明示し、早期検知の方法を示す
• 成功指標 — サービスSLOと、該当するDORAのデリバリーメトリクス5項目（デプロイ頻度、変更のリードタイム、デプロイ失敗からの復旧時間、変更失敗率、デプロイの手戻り率）。各指標をそれぞれのベースラインと比較する

ワークフロー（システムレベル）

ユーザーがアーキテクチャの推奨、分解、またはプラットフォームに関する重要な意思決定を求めている場合は、このワークフローを使用してください。

1. 明確化する：問題の説明、非目標、制約、成功指標
2. 品質特性を把握する：可用性、レイテンシ、スループット、耐久性、一貫性、セキュリティ、コンプライアンス、コスト
3. ワークロードの形態を決める：決定論的ワークフロー、単一エージェント、マルチエージェント。同期か非同期か
4. アーキテクチャの候補を2～3案提示し、トレードオフを比較する
5. 分散パターンを正当化する前に、実現可能な選択肢の中で最も複雑さの低いトポロジーを基本とする
6. 20以上のリポジトリを持つ環境では、各リポジトリをランタイム、アダプター、ライブラリ、チャネル、プラットフォーム、ツール、または統合候補に分類する
7. 境界を定義する：境界づけられたコンテキスト、オーナーシップ、API／イベント、プロトコル契約、相互運用性の要件
8. データ戦略を決める：ストレージ、一貫性モデル、スキーマの進化、移行
9. 運用を設計する：SLO、障害モード、可観測性、デプロイ、DR、インシデント対応手順
10. ガバナンスと安全性を設計する：ポリシーの適用、監査可能性、評価ゲート、ロールバック制御
11. スコープの制限を明示する：まだ構築しないもの、先送りするもの、購入するものと構築するもの
12. 意思決定を文書化する：デプロイ可能な境界、一貫性または障害のモデル、プラットフォーム契約、あるいは元に戻すコストの高い制約に影響する選択では、ADRを作成する。ADRテンプレートに、背景、選択肢、結果、オーナー、置き換え先へのリンクを記録してください。MADRは簡潔な形式の選択肢です。ローカルな実装上の選択には、より簡易なメモを使用してください。

推奨する成果物（依頼内容に合うものを選んでください）：

• アーキテクチャ設計書：assets/planning/architecture-blueprint.md
• システム群のモダナイゼーション設計書：assets/planning/estate-modernization-blueprint.md
• 意思決定記録：assets/planning/adr-template.md
• パターンの詳細解説：references/modern-patterns.md、references/scalability-reliability-guide.md

意思決定の根拠ゲート

提案する境界や新たなデプロイ対象ごとに、それが必要となる観測済みの圧力を明記してください。具体的には、独立したリリース頻度、拡張方法の不整合、障害の分離、データ主権、または所有権の違いです。ベースラインと、その選択を誤りだと示す実験を記録してください。圧力が仮説にすぎない場合や、既存のランタイム内で対処できる場合は、境界を論理的なものにとどめ、運用上の分割は先送りしてください。

既知の落とし穴

• ランタイムの乱立と所有権の弱さが本当の問題であるにもかかわらず、すでにリポジトリが多数あるという理由でマイクロサービスを選ぶこと。
• 移行手順、ロールバックの境界、旧経路と新経路の間の互換性計画を示さずに、目標状態の図を描くこと。
• 追加される運用負担を支える体制が整う前に、ドメインを分割すること。具体的には、所有権、オンコール体制、デプロイ権限が整っていない状態での分割です。
• 実際に疎結合が必要な経路を判断する前に、すべての境界に非同期ワークフローやイベント駆動型ワークフローを導入すること。
• ゴールデンパスが任意のまま、一貫性がないまま、または所有者が不明確なまま、プラットフォームエンジニアリングと呼ぶこと。

よくあるアンチパターン

• 境界づけられたコンテキスト、チームの所有権、運用コストではなく、デプロイ可能なサービスをデフォルトの分解単位として使うこと。
• 同等の規模、ツール、プラットフォーム要員を持たないチームに、ハイパースケーラーやベンダーのリファレンスアーキテクチャをそのまま適用すること。
• 現在のスループット、障害、コンプライアンス、変更管理の制約ではなく、将来起こるかもしれない最大限の状況に合わせて設計すること。
• 明らかな調整やガバナンスのコストがあるにもかかわらず、「多少は価値がある」という理由で、すべてのリポジトリとランタイムを残すこと。
• 「モダン」と「より分散化されている」、「AIネイティブ」と「デフォルトでマルチエージェント」を同一視すること。

ナビゲーション

主なリファレンス

質問ごとに読むリファレンスは最大2～3件にしてください。具体的な質問に最も関連するものを選び、すべてに目を通す必要はありません。

リファレンス	内容	読むタイミング
modern-patterns.md	判断ツリーを含むアーキテクチャパターン。モジュラーモノリスとマイクロサービスの選択基準、セルベースアーキテクチャなど	パターンを選択または比較するとき
scalability-reliability-guide.md	CAP 定理、DB のスケーリング、キャッシュ、サーキットブレーカー、SRE	スケーリングや信頼性に関する質問
data-architecture-patterns.md	CQRS の各種パターン、イベントソーシング、データメッシュ、サーガ、一貫性	サービス間のデータフロー
migration-modernization-guide.md	ストラングラーフィグパターン、DB の分解、フィーチャーフラグ、リスク評価	モノリスのリファクタリング
api-gateway-service-mesh.md	ゲートウェイパターン、サービスメッシュ、mTLS、可観測性	サービス間通信
fitness-functions-governance.md	フィットネス関数の分類（6つの軸）、アーキテクチャとドメイン、監視とアラームを見分ける判断基準、ArchUnit／NetArchTest／リンターのルール、モジュラーモノリスの境界の強制、群集化のしきい値、結合度と複雑性の指標、コーディングエージェントが変更したコードベース	アーキテクチャガバナンスの自動化、原則の強制可能化、エージェントが作成した差分を安全に適用できるコードベースの構築
architecture-trends.md	プラットフォームエンジニアリング、アンビエントメッシュ、AIネイティブシステム、MCP/A2A	最新動向のみ
estate-modernization.md	ランタイムとリポジトリの整理、境界づけられたコンテキスト向けプラットフォーム、統合の判断基準	マルチリポジトリ環境やサービスの乱立
operational-playbook.md	アーキテクチャに関する質問のフレームワーク、分解の判断基準	設計の議論を組み立てるとき

テンプレート

計画とドキュメント（assets/planning/）：

• architecture-blueprint.md — サービスのブループリント（依存関係、SLA、データフロー、レジリエンス、セキュリティ、可観測性）
• estate-modernization-blueprint.md — システム群のブループリント（リポジトリ／ランタイムの分類、ターゲットプラットフォームのマップ、移行の段階、スコアカード）
• adr-template.md — トレードオフ分析のためのアーキテクチャ決定記録

アーキテクチャパターン（assets/patterns/）：

• microservices-template.md — マイクロサービス設計（API コントラクト、レジリエンス、デプロイ、テスト）
• event-driven-template.md — イベント駆動型アーキテクチャ（イベントスキーマ、Saga パターン、イベントソーシング）

運用（assets/operations/）：

• scalability-checklist.md — スケーラビリティのチェックリスト（DB のスケーリング、キャッシュ、負荷テスト、自動スケーリング、DR）

検証

• evals/evals.json — このスキルの動作を確認する、トリガー、非トリガー、境界付近のチェック

適用レシピのツールキット

• references/decision-theory-applied.md — アーキテクチャに適用する意思決定理論のレシピ：EU と感度分析を含む ADR、不可逆な選択に対するリアルオプション、スパイクに対する VoI。
• references/queueing-theory-applied.md — アーキテクチャに適用する待ち行列理論のレシピ：サービスのサイジング、バックプレッシャーのトポロジー、テールレイテンシの予算。
• references/theory-of-constraints-applied.md — アーキテクチャに適用するTOCのレシピ：システム全体のボトルネック調査、リファクタリングのスコープ、安定性と速度に関する ADR。
• references/distributed-systems-applied.md — アーキテクチャに適用する分散システムの基本要素：CAPを考慮したサービス境界、コンセンサスアルゴリズムの選定、APIの境界における冪等性、リーダー選出されたジョブ向けのフェンシング付きリース、クォーラムのサイジング、一貫性とレイテンシに関する ADR テンプレート。
• references/reliability-theory-applied.md — ソフトウェアアーキテクチャ設計に適用する信頼性の基本要素（MTBF／MTTR、可用性、FMEA、エラーバジェット）。

関連スキル

• software-solution-architecture — エンドツーエンドのソリューション設計、システム全体像、目標状態および移行アーキテクチャ
• software-backend — バックエンドエンジニアリング、API 実装、データレイヤー
• software-frontend — フロントエンドアーキテクチャ、マイクロフロントエンド、状態管理
• dev-api-design — REST、GraphQL、gRPC の設計パターン
• ops-devops-platform — CI/CD、デプロイ戦略、IaC
• qa-observability — 監視、トレーシング、アラート、SLO
• software-security-appsec — 脅威モデリング、認証、安全な設計
• data-sql-optimization — 既存のスキーマに対するクエリの調整と最適化
• software-database-design — スキーマ設計、マイグレーション、データモデリング
• docs-codebase — アーキテクチャドキュメント、docs-as-code の構成
• docs-diagram-design — 図を作成する価値があるか、また何を示す必要があるか
• C4 のコンテキスト図／コンテナ図、arc42 のドキュメント構成、またはコードとしての図を扱う場合は、docs-diagram-design で最小限かつ有用なビューを選び、docs-codebase でその管理責任と更新手順を維持してください。
• ai-agents — エージェントシステム設計、オーケストレーション、評価
• agents-mcp — MCP サーバー／クライアントのパターンと統合

鮮度確認プロトコル

質問がバージョンに左右される場合（現在のトレンド、「X は今も推奨されていますか？」、ベンダーの制限、マネージドサービスの機能、AI ネイティブな相互運用性）は、回答する前に data/sources.json にある一次情報源を確認してください。リアルタイムのアクセスがない場合は、長期的に有効なパターンを回答し、変わる可能性のある前提を明示してください。該当条件、確認手順、情報源のカテゴリについては、references/operational-playbook.md#freshness-protocol を参照してください。トレンドの詳細な解説については、architecture-trends.md、estate-modernization.md を参照してください。

学びのループ

過去の決定や落とし穴が関連する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または利用可能な代替ファイルとしてのみ、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、記憶に残す価値のあるパターン、防止すべき誤り、または意外だった分野の知識に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付付きの箇条書きを 1 つ learnings.md に追記してください。SKILL.md 自体は変更しないでください。