ソフトウェアアーキテクチャドキュメントのテンプレート（無料）

アーキテクチャドキュメントはたいていこうして書かれます。新しいエンジニアが入ってきて、システムの全体像を尋ね、誰かが「ちゃんと書いておくよ」と約束する。その人はソフトウェアアーキテクチャドキュメントのテンプレートを検索し、2012年の40ページあるWordファイルか大学のPDFを見つけ、半分だけ埋めて、二度と開かない。1年後、次に入ってきた人がそれを見つけ、信じて、間違った理解をしてしまいます。

問題がテンプレートの不足であることはまれです。問題は、すべてを求めるテンプレートのせいで何も完成しないこと、そしてオーナーのいないドキュメントのせいで何も更新されないことです。以下のテンプレートは意図的に無駄を削っています。Markdownファイル1つ、9つのセクション。どのセクションも、読む人が必要とするからこそ存在しています。リポジトリにコピーしてください。登録もダウンロードも不要です。そのうえで、各部分に何を書くか、そして古くならないようにするにはどうするかについてのセクション別の解説を読んでください。

アーキテクチャドキュメントは何のためにあるのか（そして誰が読むのか）

アーキテクチャドキュメントは、コードではすぐに答えられない質問に答えます。システムは何のためにあるのか、何と通信しているのか、どう分割されているのか、なぜそう分割されているのか、そして何が脆いとわかっているのか。1つの機能のための設計仕様書ではありませんし、APIリファレンスでもありません。

読み手は5種類います。それぞれを名指しして書くと役に立ちます。

ドキュメントの中に、どの読み手の役にも立たないセクションがあるなら削除しましょう。このルールは、どんなテンプレートよりもドキュメントの品質を高めます。

名前について補足します。「アーキテクチャドキュメント」「システム設計書」（SDD）「ソフトウェアアーキテクチャドキュメント」（SAD）は、ほぼ同じものを指して使われます。SDDのテンプレートはプロジェクトごと、機能ごとに書かれ、詳細設計を含む傾向があります。アーキテクチャドキュメントはシステムをありのままに記述し、システムとともに変わります。ここで紹介するテンプレートは後者です。

テンプレート（Markdownブロック1つ）

これをdocs/architecture.md（またはルートのARCHITECTURE.md）にコピーして埋めてください。山括弧で囲まれたものはすべてプレースホルダーです。当てはまらないセクションは、空のまま残すのではなく削除しましょう。

# <システム名>：アーキテクチャ

| | |
|---|---|
| オーナー | <このドキュメントを正しく保つ責任を負うチームまたは人> |
| 最終レビュー日 | <YYYY-MM-DD> |
| 次回レビュー | <YYYY-MM-DD、または「セクション3〜5を変更するたび」> |
| ステータス | <下書き / 最新 / Xに置き換え中> |

## 1. コンテキストとスコープ

<2〜3文で：システムが何をするのか、誰のためか、なぜ存在するのか。>

**ユーザー**
- <役割>：<そのユーザーがシステムで何をするか>

**外部システム**
- <システム>：<何を送受信するか、プロトコル>

**スコープ外**
- <このシステムがやっていると思われがちだが、実際にはやっていないこと>

**システムコンテキスト図（C4レベル1）**
<リンクまたは埋め込み。システムを1つのボックスとして、あらゆる種類のユーザーとすべての外部システムを描く。>

## 2. 品質目標

互いに衝突したときに優先される3〜5つの品質特性を、優先順位順に。

| 優先度 | 品質特性 | 具体的なシナリオ |
|---|---|---|
| 1 | <例：可用性> | <例：レコメンドサービスが落ちていてもチェックアウトは動き続ける> |
| 2 | <例：レイテンシ> | <例：毎分500件の注文時に、チェックアウトのp95が2秒未満> |
| 3 | <例：変更容易性> | <例：注文サービスに触れずに新しい決済手段をリリースできる> |

## 3. 制約

自分たちで選んだわけではないが、受け入れるしかないもの。
- <例：社内のKubernetesプラットフォームで動かす>
- <例：顧客データはEU内にとどめる>
- <例：バックエンドサービスはGoまたはJavaのみ>

## 4. アーキテクチャ

**コンテナ図（C4レベル2）**
<リンクまたは埋め込み。すべてのデプロイ単位とデータストアを、テクノロジーとプロトコル付きで。>

| コンテナ | テクノロジー | 責務 | オーナー |
|---|---|---|---|
| <Webアプリ> | <React SPA> | <何をするか> | <チーム> |
| <API> | <Go> | <何をするか> | <チーム> |
| <データベース> | <PostgreSQL> | <何を保存するか> | <チーム> |

**コンポーネント図（C4レベル3）**
<新しく来た人が苦労しそうな1〜2個のコンテナについてだけ。リンクまたは埋め込み。>

**主要なフロー**
<最も重要な2〜3のシナリオを、番号付きのステップまたはC4ダイナミック図で。>

1. <アクター> -> <コンテナ>：<何が起きるか>
2. <コンテナ> -> <コンテナ>：<何が起きるか、プロトコル、同期か非同期か>

## 5. 主要な決定

完全な記録は<docs/adr/>にあります。ここはその索引です。

| ADR | 決定 | ステータス | 日付 |
|---|---|---|---|
| [ADR-001](adr/001-<slug>.md) | <例：サービスごとに1つのデータベース> | 承認済み | <YYYY-MM-DD> |
| [ADR-002](adr/002-<slug>.md) | <例：注文イベントにKafkaを使う> | 承認済み | <YYYY-MM-DD> |

## 6. 横断的な関心事

すべてのコンテナが関わる事柄を、システム全体としてどう扱うか。それぞれ1〜2行で、詳細へのリンクを添えて。
- **認証と認可：** <どこで行うか、どのトークンか>
- **オブザーバビリティ：** <ログ、メトリクス、トレース、どこを見ればよいか>
- **エラー処理とリトライ：** <規約、冪等性>
- **データとプライバシー：** <個人情報の所在、保持期間>

## 7. デプロイと運用

- **環境：** <本番、ステージング、……>とその違い
- **実行場所：** <クラウド、リージョン、クラスター>
- **ランブック：** <リンク>
- **ダッシュボードとアラート：** <リンク>

## 8. リスクと技術的負債

| リスクまたは負債 | 顕在化したときの影響 | 対応計画 | オーナー |
|---|---|---|---|
| <例：決済前に在庫を確保しており、補償処理がない> | <決済失敗後に幽霊の在庫確保が残る> | <失敗時の解放処理を追加、第4四半期> | <チーム> |

## 9. 用語集

| 用語 | ここでの意味 |
|---|---|
| <注文> | <ビジネスで使われている意味での定義> |

テンプレートはこれで全部です。10個程度のコンテナを持つシステムで埋めると、たいてい数ページになります。それよりずっと長くなるなら、何かがこのドキュメントではなく、リンク先の別のドキュメントに属している可能性が高いです。

セクションごとの解説

ヘッダー：オーナーとレビュー日

冒頭の4行は、その下のどのセクションよりも重要です。オーナーは、ドキュメントが間違っているときに誰が直すのかを示します。最終レビュー日は、どの程度信頼してよいかを読み手に伝えます。「最終レビューは14か月前」と書いてあるドキュメントは正直です。何も書いていないドキュメントは、実際には最新でないのに最新に見えてしまいます。

1. コンテキストとスコープ

ここから始めましょう。他のすべてのセクションが境界に依存しているからです。あらゆる種類のユーザーとすべての外部システムを挙げます。当たり前だと思っているもの（IDプロバイダー、メールサービス、決済ゲートウェイ）も含めてです。スコープ外のリストは、ドキュメントの中で何よりも多くの会議を減らしてくれます。誰もが扱っていると思い込んでいても、このシステムは返金を扱わない、ということを書き留める場所です。

ダイアグラムはC4のシステムコンテキスト図です。自分のシステムを1つのボックスにし、その周りにユーザーと外部システムを置き、ラベル付きの矢印でつなぎます。何を載せるべきかはSystem Context図ガイドで解説しています。

2. 品質目標

ほとんどのアーキテクチャドキュメントはこのセクションを飛ばしますが、ここが他のすべてを説明するセクションです。「一貫性より可用性」「生の性能より変更容易性」と書いてあれば、コンテナがなぜそういう形をしているのかが読み手に伝わります。目標は3〜5つにとどめ、順位を付け、それぞれにテストできるほど具体的なシナリオを添えましょう。数値、負荷、障害です。

3. 制約

制約とは、誰か別の人が下した決定です。プラットフォームチーム、法務、会社の言語ポリシー。書き留めておけば「なぜXを使わなかったの？」という会話がなくなり、将来の読み手に、どの選択は見直せてどれは見直せないのかを伝えられます。

4. アーキテクチャ：C4ダイアグラム

多くの人が「アーキテクチャ」と聞いて思い浮かべるのがこのセクションです。C4モデルを使いましょう。各ダイアグラムに1つの役割を与えてくれるからです。

• コンテナ図（レベル2）、常に。 すべてのデプロイ単位とデータストアを、それぞれのテクノロジー付きで、各矢印にはプロトコルを付けて描きます。ダイアグラムを1枚しか描かないなら、これを描きましょう。Container図ガイドに実例があります。
• コンポーネント図（レベル3）、選んで。 新しく来た人が苦労しそうなコンテナについてだけ描きます。
• 主要なフロー。 2〜3のシナリオを番号付きのステップで。静的なダイアグラムは2つのコンテナが通信することを示し、フローはそれがどの順番で行われ、ユーザーがどのステップを待つのかを示します。書き方はC4 Dynamic図ガイドで紹介しています。

コンテナの表にオーナーの列があるのは意図的です。誰も所有していないコンテナは、このドキュメントの中でも誰も更新しないコンテナです。

C4が初めてなら、C4モデルとは何かで4つのレベルを説明しています。これらのダイアグラムを実在する大規模システムに適用した例は、C4モデルの実例をご覧ください。

5. 主要な決定（ADR）

決定をインラインで書かないでください。1つひとつをアーキテクチャ決定記録として独立したファイルに残し（コンテキスト、決定、検討した代替案、結果）、ここには索引だけを置きます。ADRは一度書いたら編集せず、新しいADRで置き換えるものなので、ドキュメントは短く保たれ、履歴は損なわれません。フォーマットや、どんな決定がADRに値するかはアーキテクチャ決定記録の完全ガイドで扱っています。

索引の良し悪しを確かめるテストがあります。新しいエンジニアが、セクション4の意外なボックスを指さしたとき、それを説明するADRを見つけられるかどうかです。

6. 横断的な関心事

どのコンテナにも属さないものがあります。認証、ロギング、エラー処理、個人データの所在。それぞれ1〜2行と、詳細へのリンクがあれば十分です。監査人が最も時間を費やすのはこのセクションなので、読みやすくしておきましょう。

7. デプロイと運用

短くして、外部にリンクしましょう。環境とその違い、システムがどこで動いているか、そしてランブックとダッシュボードへのリンク。詳細はインフラのコードとランブックに属するものであり、それらはこのドキュメントよりも頻繁に変わるはずです。

8. リスクと技術的負債

正直さのセクションです。脆いとわかっているものを、オーナーと対応計画を添えて書き留めましょう。計画が「受け入れる、第3四半期に見直す」であっても構いません。書き留められたリスクは、誰かが優先順位を付けられるリスクです。1人のエンジニアの頭の中にしかないリスクは、その人とともに去っていきます。

9. 用語集

どのシステムにも、そこでは特定の意味を持つ言葉があります。「注文」と「カート」、「アカウント」と「テナント」、「フルフィルメント」。それぞれ一度だけ定義しましょう。新しいエンジニアは、思っている以上にこのセクションを読みます。

arc42との関係

このテンプレートに見覚えがあるとしたら、それはPeter HruschkaとGernot Starkeが作った無料のオープンソースのアーキテクチャドキュメントテンプレート、arc42と同じ考え方を簡潔にまとめたものだからです。arc42には12のセクションがあり、arc42自身も「ステークホルダーが必要とするものだけ」をドキュメント化するよう勧めています（arc42 FAQ、B-1）。対応は次のとおりです。

arc42の完全な構成が必要なとき、つまり規制のある環境、複数のアーキテクトがいる大規模システム、すでにarc42を標準にしている組織では、arc42を選びましょう。代わりの選択肢がドキュメントなしだという場合には、このくらいの規模のものを選びましょう。どのC4ダイアグラムをarc42のどのセクションに置くかを含む詳しい比較は、arc42とC4の比較をご覧ください。

古くならないようにする

アーキテクチャドキュメントは、マージされたその日はどれも正確です。半年後も正確かどうかは、いくつかの習慣にかかっています。そのほとんどはダイアグラムに関するものです。現実が最も速く変わるのはセクション4と5だからです。

リポジトリに置く。 コードの隣にdocs/architecture.mdがあれば、サービスを分割するプルリクエストが、同じレビューの中でコンテナの表も更新できます。Wikiのページはコードレビューの一部になれません。

スクリーンショットを貼らず、ダイアグラムにリンクする。 コンテナ図のスクリーンショットは、コンテナが改名された瞬間に古くなります。モデル（Structurizr DSL、YAMLのモデル、あるいはモデルを保持するツール）からレンダリングしたダイアグラムは、モデルが古い分だけしか古くなりません。

レビュー日を活用する。 コンテナが追加・削除されるときに回るチェックリストに、このドキュメントを加えましょう。プルリクエストのテンプレート、アーキテクチャレビュー、四半期の計画など。「次回レビュー：セクション3〜5を変更するたび」は有効な書き方です。

決定は前に向かって書く。 承認済みのADRは決して編集しないでください。置き換えます。そうすればセクション5の索引が履歴を示し、それこそが人々に最も必要な部分です。

構造に関する部分は自動でチェックする。 セクション1と4は、コードに存在するものを記述しています。サービス、データストア、依存関係。これらはリポジトリと照合できます。セクション2、6、8はそうはいかず、定期的に人がレビューする必要があります。前者の方法と、それぞれの方法に何が見えて何が見えないかはアーキテクチャドリフト検出ガイドで扱っています。

これこそ、ドキュメントのダイアグラムの半分についてarchylが解決しようとしている問題です。リポジトリを接続すると、AI発見がC4モデル（システム、コンテナ、コンポーネント、関係）を提案し、あなたは描く代わりにレビューして承認します。ADR、ドキュメント、フローは、それらが説明する要素にリンクされます。その後はドリフトスコアが、文書化された要素がまだコードに存在するかを、決定論的に、途中でAIを介さずにチェックします。古くなったセクション4は、不意打ちではなく数値として現れます。品質目標やリスク一覧はチェックしないので、それらには引き続きレビュー日が必要です。ツールの有無にかかわらずドキュメントを最新に保つプラクティスについては、活きたアーキテクチャドキュメントをご覧ください。

よくある質問

ソフトウェアアーキテクチャドキュメントには何を含めるべきですか？

最低限、システムのコンテキストとスコープ（ユーザーと外部システム）、テクノロジー付きのコンテナレベルのダイアグラム、理由を添えた主要なアーキテクチャ上の決定、既知のリスク、そしてオーナーとレビュー日です。上のテンプレートでは、品質目標、制約、横断的な関心事、デプロイに関するメモ、用語集を、どれも短く加えています。

このテンプレートは本当に無料ですか？

はい。上のMarkdownブロックがそれです。コピーして、自分のシステムに合わせて変更してください。登録も、ダウンロードも、メールアドレスも不要です。

アーキテクチャドキュメントはどこに置くべきですか？

リポジトリの中に、docs/architecture.mdまたはARCHITECTURE.mdとして、docs/adr/のADRの隣に置きましょう。そうすれば、アーキテクチャの変更とドキュメントの変更が同じプルリクエストを通ります。

アーキテクチャドキュメントの長さはどのくらいが適切ですか？

読み手の疑問に答えられる範囲で、できるだけ短く。10個程度のコンテナを持つシステムなら、数ページが普通です。それを大きく超えるようなら、詳細はリンク先のドキュメント（ランブック、ADR、APIリファレンス）に移し、このドキュメントは地図として保ちましょう。

システム設計書とは何が違うのですか？

システム設計書はたいてい、1つのプロジェクトや機能のために、構築前に書かれ、詳細設計を含みます。アーキテクチャドキュメントは、現在のシステム全体をありのままに記述し、システムとともに変わります。チームはシステムごとに1つのアーキテクチャドキュメントを持ち、その寿命のあいだに多くの設計書を書くことがよくあります。設計書に含まれる長く残る決定は、最終的にADRになります。

代わりにarc42を使うべきですか？

arc42の完全な構成が必要な場合や、組織がすでにarc42を使っている場合は、そうすべきです。このテンプレートはarc42のセクションに対応している（上の表を参照）ので、ここから始めて、何も書き直さずに後からarc42へ移行できます。

セクション4のダイアグラムを、記憶ではなくコードから作りたいですか？ Developerプランならarchylを無料で試せます。クレジットカードは不要です。続けて読む：arc42とC4の比較 | Architecture Decision Records：完全ガイド | C4モデルとは？ | 活きたアーキテクチャドキュメント | アーキテクチャドリフト検出