Imported from Gami19/rd-strands-agents (strands-py/backend/agent/skills/pr/software-architecture/SKILL.md). Install upstream with npx skills add Gami19/rd-strands-agents --skill software-architecture. Copyright stays with the author.

Skill: Software Architecture（ソフトウェアアーキテクチャ設計・評価・意思決定）

すべてはトレードオフである ── 「正解」を探すな、「最も害の少ない選択」を見極めよ

Instructions

ワークフロー内の位置

ビジネス要件 → story-map → [software-architecture] → diagram → review
   distill ↗                       ↓
                              アーキテクチャ設計
                              ・スタイル選定
                              ・特性分析
                              ・ADR 生成
                              ・トレードオフ分析
                              ・リスク評価

入力

出力

Step 1: 要件の把握とコンテキスト分析

対象システムの要件を以下の観点で把握する。

1a. ビジネスコンテキスト

1b. 技術コンテキスト

チェックリスト:

• ビジネス上の主要な課題・ユースケースを明確にした
• 規模（ユーザー数、トランザクション量）の想定を確認した
• チームの規模・スキルセットを把握した
• 技術的制約・コンプライアンス要件を確認した
• 予算・スケジュールの制約を確認した

Step 2: アーキテクチャ特性の抽出と優先順位付け

ビジネス要件からアーキテクチャ特性（-ilities）を抽出する。

2a. ビジネス要件から特性への変換

2b. 暗黙的特性の確認

明示されていなくても必要な特性を洗い出す。以下はほぼ全てのシステムで暗黙的に求められる:

• Availability -- ほぼ全システムで暗黙的に要求される
• Reliability -- ミッションクリティカル度に応じて
• Security -- 最低限の認証・認可は必須

詳細な特性一覧は architecture-characteristics.md を参照。

2c. 特性の優先順位付け

原則: 支える特性の数は「最も少なく」。各特性が複雑性を追加するため、7個以内に絞る。

優先順位付けの手順:

1. 全抽出した特性をリストアップ
2. ビジネスインパクトが最大の上位 3-7 個を選定
3. 重み付けスコアリング（High = 3, Medium = 2, Low = 1）

チェックリスト:

• ビジネス要件を具体的なアーキテクチャ特性に変換した
• 暗黙的な特性（Availability, Security 等）を確認した
• 特性を 7 個以内に絞り込み、優先順位を付けた
• 「最も少ない特性」の原則を遵守した（全てを満たそうとしていない）
• ステークホルダーと特性の優先度を合意した

Step 3: アーキテクチャ量子（Quantum）の決定

3a. Quantum の定義

アーキテクチャ量子 = 独立デプロイ可能で、高い機能的凝集度・高い静的結合度・同期的な動的結合を持つ単位。

3b. Quantum 数の判定

各ドメイン/コンポーネントの必要な特性を比較
  ├─ 全てのコンポーネントが同じ特性セットで十分
  │    → Quantum = 1 → モノリスが候補
  │
  └─ コンポーネントごとに異なる特性が必要
       → Quantum = N → 分散アーキテクチャが候補
       例: 決済 = 高 Security + 高 Availability
           商品カタログ = 高 Scalability + 高 Performance
           → 少なくとも 2 Quantum

3c. モノリス vs 分散の基本判断

重要: 分散アーキテクチャを選択する場合、8つの誤謬（Fallacies of Distributed Computing）を必ず確認すること。

チェックリスト:

• 各コンポーネントに必要な特性セットを列挙した
• Quantum 数を判定した（1 = モノリス候補、N = 分散候補）
• 分散を選択する場合、8つの誤謬のリスクを理解した
• Quantum 判定の根拠を文書化した

Step 4: アーキテクチャスタイルの選定

Quantum 数と抽出した特性に基づき、最適なスタイルを選定する。

4a. モノリス候補（Quantum = 1）

4b. 分散候補（Quantum > 1）

4c. スタイル特性レーティング比較

詳細な特性レーティング（1-5星）は architecture-styles.md を参照。

4d. ハイブリッドアプローチ

実務では純粋な単一スタイルは稀。ハイブリッドの典型例:

• Modular Monolith + Microkernel: ドメインモジュール + プラグイン拡張
• Microservices + Event-Driven: サービス間のイベント通信
• Service-Based + CQRS: サービス内での読み書き分離

チェックリスト:

• Quantum 数に基づく候補スタイルを選定した
• 候補スタイルの特性レーティングと要件を照合した
• 各候補の When to Use / When Not to Use を確認した
• ハイブリッドアプローチの可能性を検討した
• ドメインとアーキテクチャの同型性（isomorphism）を確認した

Step 5: コンポーネント設計

選定したスタイル内でのコンポーネント構成を設計する。

5a. パーティショニング戦略

原則: 現代のアーキテクチャではドメイン分割が推奨。ただし、問題の性質に応じて技術分割が適切な場合もある。

5b. コンポーネント特定の手順

1. ドメインのユースケースから主要コンポーネントを洗い出す
2. ユーザーストーリーを各コンポーネントに割り当てる
3. 各コンポーネントの責務を分析する
4. コンポーネント間の結合度を評価する

5c. 結合度の管理

通信のデフォルト: 同期通信をデフォルトとし、非同期は必要な場合のみ使用する。

チェックリスト:

• パーティショニング戦略（技術 vs ドメイン）を決定した
• 主要コンポーネントとその責務を特定した
• コンポーネント間の結合度を評価し、適切に制御した
• 通信方式（同期/非同期）を決定した

Step 6: トレードオフ分析と ADR 生成

6a. トレードオフ分析

First Law: 「すべてはトレードオフである」 -- 利点のないものは存在しないが、欠点のないものも存在しない。

以下のフレームワークで分析する:

各セルを H (High) / M (Medium) / L (Low) で評価し、ビジネス優先度で重み付けする。

6b. ADR の生成

主要なアーキテクチャ決定に対し、ADR を生成する。テンプレートは adr-template.md を参照。

ADR の 7 セクション構造:

## ADR-NNN: [タイトル]

### Status
[Proposed | Accepted | Superseded by NNN]

### Context
[この決定を迫っている状況・力学の記述]

### Decision
[決定内容を断定的に記述: "We will use..."]

### Consequences
[ポジティブ・ネガティブ両面の影響]

### Compliance
[この決定の遵守をどう確認するか]

### Alternatives
[検討した代替案とその評価]

### Notes
[著者、承認者、日付等のメタデータ]

Second Law: 「Why は How より重要」 -- ADR では なぜ その決定をしたかの記述が最も重要。

6c. 判断の自己承認基準

チェックリスト:

• 主要な決定ポイントを特定した
• 各決定に対しトレードオフ分析を実施した
• ADR を 7 セクション構造で作成した
• 決定を断定的な表現（"We will use..."）で記述した
• 代替案と採用しなかった理由を記録した

Step 7: リスク評価とフィットネス関数

7a. リスクマトリクス

2 次元（影響度 x 発生確率）でリスクを定量化する。

原則: 影響度を先に評価し、確率を後に評価する。確率が不明な場合は高 (3) を仮定する。

7b. リスクストーミング（協調リスク識別）

1. Phase 1: 識別 -- 各参加者が独立にアーキテクチャ図上のリスクを識別
2. Phase 2: コンセンサス -- チームで認識のズレを議論・解消
3. Phase 3: 緩和 -- 高リスク領域に対する緩和策を策定

7c. フィットネス関数の設計

チェックリスト:

• 主要リスクをリスクマトリクスで評価した
• 高リスク（6-9）の領域に緩和策を策定した
• アーキテクチャの重要特性に対するフィットネス関数を設計した
• フィットネス関数の実行タイミング（CI/CD / 負荷テスト / 本番）を決定した
• リスク評価の結果をステークホルダーと共有した

Step 8: 出力とセルフレビュー

アーキテクチャ推奨レポートの構成

## アーキテクチャ推奨レポート

### 1. エグゼクティブサマリー
（推奨スタイルと根拠の要約）

### 2. 要件分析
（ビジネスコンテキスト + 技術コンテキスト）

### 3. アーキテクチャ特性
（抽出した -ilities と優先順位）

### 4. Quantum 分析
（モノリス vs 分散の判断根拠）

### 5. スタイル選定
（候補の比較評価 + 推奨スタイル + トレードオフ）

### 6. コンポーネント設計
（論理コンポーネント図、責務、結合度）

### 7. ADR
（主要な意思決定の記録）

### 8. リスク評価
（リスクマトリクス + 緩和策）

### 9. フィットネス関数
（アーキテクチャ特性の保護メカニズム）

### 10. 次のステップ
（実装計画、追加設計が必要な領域）

Software Architecture Slop 防止チェック（Distributional Convergence 対策）

アーキテクチャ設計は「正解がない判断」の連続であり、LLM は不確実性を回避するために業界で最も一般的な選択肢に収束する。特にマイクロサービスの過剰推奨、Availability/Scalability/Performance の 3 特性への固定、Service-Based や Space-Based 等の中間解の無視が頻発する。

核心原則: 「最良のアーキテクチャ」は存在しない、あるのは「最も害の少ないトレードオフ」だけ — First Law に従い、全ては trade-off であることを前提に設計する。「別のビジネスドメイン・別のチーム規模に同じアーキテクチャを推奨しても違和感がないか？」→ 違和感がないなら Software Architecture Slop である。

最終チェックリスト:

• 8 ステップ（要件 → 特性 → Quantum → スタイル → コンポーネント → ADR → リスク → 出力）を完了した
• 推奨スタイルの選定根拠が明確で、3法則に基づくトレードオフ分析がある
• ADR が 7 セクション構造で作成され、why が記述されている
• リスクマトリクスで高リスク領域が識別され、緩和策がある
• フィットネス関数が設計されている
• 成果物がステークホルダーに説明可能な形式になっている
• Software Architecture Slop チェック（SA-1〜SA-8）に 2 つ以上該当しない
• 出力がドメイン固有の要素を含み、汎用テンプレートに見えない

Examples

Example 1: 新規 Web アプリケーションのアーキテクチャ選定

「ECサイトのバックエンドを新規構築したい。5人チーム、6ヶ月、AWS。
 将来的にはモバイルアプリも追加したい」

→ Step 1 で要件把握（中規模、成長性あり、AWS 制約）
→ Step 2 で特性抽出（Scalability, Maintainability, Deployability を Top 3 に）
→ Step 3 で Quantum 分析（商品/注文/決済で異なる特性 → 2-3 Quantum）
→ Step 4 で Service-Based Architecture を推奨（5人チームに Microservices は過剰）
→ Step 6 で ADR 作成（スタイル選定、通信方式、DB 分割戦略）
→ 成果物: アーキテクチャ推奨レポート + ADR 3本

Example 2: 既存モノリスのマイクロサービス移行可否評価

「既存の Java モノリスが性能限界。マイクロサービスに移行すべきか？」

→ Step 1 で現行アーキテクチャの課題把握
→ Step 2 で求められる特性の変化を分析
→ Step 3 で Quantum 分析（どの部分に異なる特性が必要か）
→ Step 4 で候補比較（Modular Monolith vs Service-Based vs Microservices）
→ Step 6 で移行戦略の ADR（Strangler Fig パターンの適用を推奨）
→ Step 7 でリスク評価（分散トランザクション、データ整合性のリスク）
→ 成果物: 移行可否判定レポート + 段階的移行ロードマップ

Example 3: ECサイトの非同期イベント処理設計

「注文確定後の処理（在庫更新、決済、通知）を高速化したい」

→ Step 2 で特性抽出（Performance, Reliability, Fault Tolerance）
→ Step 4 で Event-Driven Architecture（Mediator トポロジー）を選定
→ Step 5 で OrderPlacement → Inventory / Payment / Notification のイベントフロー設計
→ Step 6 で ADR（同期 vs 非同期、Broker vs Mediator の判断記録）
→ Step 7 でリスク評価（データ損失防止、エラーハンドリング戦略）
→ 成果物: イベントフロー設計 + ADR + エラー処理方針

Example 4: SaaS のマルチテナントアーキテクチャ設計

「B2B SaaS を新規構築。テナント間のデータ隔離が必須」

→ Step 1 でテナント要件（テナント数、データ量、カスタマイズ要件）
→ Step 2 で Security, Configurability, Scalability, Maintainability を抽出
→ Step 3 で Quantum 分析（テナントごとに異なるスケール → 分散）
→ Step 4 で Microservices + Microkernel ハイブリッドを推奨
→ Step 5 でテナント分離戦略（DB per tenant vs schema per tenant vs row-level）
→ Step 6 で ADR（テナント分離方式の決定）
→ 成果物: マルチテナント設計書 + ADR + コンポーネント図

Example 5: IoTプラットフォームのスケーラビリティ設計

「数万台のIoTデバイスからのリアルタイムデータを処理したい」

→ Step 2 で Scalability, Elasticity, Performance, Availability を抽出
→ Step 3 で複数 Quantum（デバイス管理 vs データ処理 vs 分析）
→ Step 4 で Space-Based + Event-Driven ハイブリッドを検討
→ Step 5 でデータフロー設計（Ingestion → Processing → Storage → Analytics）
→ Step 7 でリスク評価（データ衝突、同期問題、処理遅延）
→ 成果物: IoT アーキテクチャ設計書 + データフロー図 + ADR

Example 6: ADR テンプレートの生成

「REST と gRPC のどちらを使うか決めたい。ADR を書いて」

→ Step 6 に直接進む
→ Context: サービス間通信のプロトコル選定
→ トレードオフ分析: REST（互換性、デバッグ容易） vs gRPC（低レイテンシ、型安全）
→ Decision: ビジネスコンテキストに基づく判断を断定的に記述
→ Consequences: 選択の影響（正・負両面）を明記
→ 成果物: ADR 1本（7セクション構造）

Example 7: レガシーシステムのリスク評価

「15年物のシステムのアーキテクチャリスクを評価して」

→ Step 1 で現行アーキテクチャの把握
→ Step 7 でリスクマトリクスを構築
→ リスクストーミング: Availability, Maintainability, Security の観点で評価
→ 高リスク領域の特定と緩和策の策定
→ フィットネス関数の提案（技術的負債の定量化）
→ 成果物: リスク評価レポート + 緩和策ロードマップ + フィットネス関数設計

Troubleshooting

References

アンチパターン検出

このスキルの出力品質を検証するためのチェックリスト。

• アーキテクチャスタイルの選定が特性レーティング（-ilities）の定量比較に基づいているか（「マイクロサービスが良い」等の結論ありきでないか）
• Architecture Quantum の分析でコネクタのタイプ（同期/非同期）が明示されているか
• コンポーネント設計が単一責務原則と結合度メトリクスで検証されているか
• ADR が「最終責任時点」で作成され、Decision セクションに Why が記述されているか
• フィットネス関数が具体的な実装手段（テスト・監視ツール）まで特定されているか
• トレードオフ分析で「万能なスタイルはない」前提の下、少なくとも 3 候補が比較されているか

Related Skills