LESSON 30分

ストーリー

佐
佐藤CTO
素晴らしいアーキテクチャも、伝えられなければ意味がない
佐
佐藤CTO
設計書はチームの共通理解を作るためのものだ。読む人の立場に立って、過不足なく情報を伝えよう

アーキテクチャ設計書の目的

目的説明
共通理解チーム全員が同じアーキテクチャ像を共有する
意思決定の記録なぜこの設計にしたかを記録する
オンボーディング新メンバーがシステムを理解する入口
レビュー基盤ステークホルダーが評価・フィードバックする材料

arc42テンプレート

arc42は、実績のあるアーキテクチャドキュメントのテンプレートです。

1. はじめに・目標
   └─ システムの目的、主要なステークホルダー、品質目標

2. 制約条件
   └─ 技術的制約、組織的制約、規約

3. コンテキストと範囲
   └─ システムの外部環境、外部インターフェース

4. ソリューション戦略
   └─ アーキテクチャの基本方針と技術選定

5. ビルディングブロック
   └─ システムの静的構造（モジュール分解）

6. ランタイムビュー
   └─ 主要なシナリオの動的振る舞い

7. デプロイメントビュー
   └─ インフラとデプロイ構成

8. 横断的関心事
   └─ セキュリティ、ログ、エラー処理等

9. アーキテクチャ決定
   └─ 主要なADR

10. 品質要件
    └─ 品質シナリオ、品質ツリー

11. リスクと技術的負債
    └─ 既知のリスクと対策

12. 用語集
    └─ ドメイン用語の定義

ステークホルダー別の視点

異なるステークホルダーは異なる情報を求めます。

ステークホルダー関心事重要なセクション
経営層コスト、リスク、スケジュール1, 4, 11
開発者技術詳細、コード構造5, 6, 8
インフラチームデプロイ、運用7, 8
セキュリティチームセキュリティ対策8, 10
新メンバー全体像、用語1, 3, 12

コンテキスト図

システムの境界と外部との関係を示す最初の図です。

graph TD
    User["ユーザー"] -->|"HTTPS"| EC["EC Platform"]
    EC -->|"API"| Pay["決済GW"]
    EC -->|"API"| Ship["配送パートナー"]
    EC -->|"API"| Mail["メールサービス"]
    EC -->|"API"| Inv["在庫管理システム"]

    classDef userStyle fill:#67b7dc,stroke:#3a8ab5,color:#fff
    classDef systemStyle fill:#4a90d9,stroke:#2c5f8a,color:#fff
    classDef extStyle fill:#e8a838,stroke:#b07c1e,color:#fff

    class User userStyle
    class EC systemStyle
    class Pay,Ship,Mail,Inv extStyle

良い設計書の特徴

特徴悪い例良い例
具体性「高可用性を実現する」「マルチAZ構成で99.95%の可用性を実現する」
図表活用文章のみの長い説明C4図 + 補足説明
更新性100ページのWord文書Markdown + Git管理
対象者明確全員に同じ文書ステークホルダー別の要約

まとめ

ポイント内容
テンプレートarc42のような実績あるテンプレートを活用する
読者意識ステークホルダーごとに関心事が異なる
図表活用テキストより図の方が伝わる
生きた文書Git管理で継続的に更新する

チェックリスト

  • arc42テンプレートの構成を理解した
  • ステークホルダー別の関心事を把握した
  • コンテキスト図の書き方を理解した

次のステップへ

次はC4モデルを使ったアーキテクチャ図の作成方法を学びます。

推定読了時間: 30分