どのエンジニアリング組織にも必ず一枚あります。何年も前の数週間だけ正しかった、Wiki 上のアーキテクチャ図です。新しく入ったメンバーはそれを読み込み、その後で同僚から「箱の半分は名前が変わっているし、真ん中のキューは去年の春に置き換えた」と教わります。アーキテクチャドキュメントのベストプラクティスの多くは「何を描くか」に焦点を当てています。この記事では、もっと難しい部分を扱います。最初のドラフトの後も図を正しく保つこと、そして図を使い捨ての成果物ではなく「生きたドキュメント」として扱うワークフローです。

アーキテクチャドキュメントが古くなる理由

図が古くなるのは、人が怠けているからではありません。図を取り巻くプロセスが、古くなることを当たり前にしているからです。

使い捨ての成果物になっている。 図は設計レビュー、移行プロジェクトのキックオフ、監査のために描かれます。その会議が終われば、誰もそれを再び開く理由がありません。
スクリーンショットがあちこちに貼られる。 元のファイルは誰かのノート PC にあり、PNG が Wiki、オンボーディング資料、3 つのスライド、README に貼られます。コピーは 5 つになり、どれも編集できません。
オーナーがいない。 「プラットフォームチーム」はオーナーではありません。具体的な担当者がいなければ、誰もが「誰かが更新するだろう」と考えます。
更新のきっかけがない。 コードの変更はプルリクエスト、レビュー、CI を通ります。図が変わるのは誰かが思い出したときだけで、それがシステムが変わった瞬間であることはまれです。
情報を詰め込みすぎている。 すべての Pod、すべてのキュー、すべての IAM ロール、すべてのユーザージャーニーを載せた図は、完成した日に古くなります。どこかで何かが変われば、それだけで図が間違いになるからです。

これらはどれも、まずツールの問題ではありません。より良い描画ツールを使っても、オーナー不在は解決しません。ただし、ツールは正しいワークフローを安くも高くもします。

生きた図のためのアーキテクチャドキュメントのベストプラクティス

私たちが推奨するワークフローを紹介します。あえて主張をはっきりさせています。

1. 図ごとに唯一の情報源を持つ

それぞれの図は、編集可能な場所にちょうど一つだけ存在します。それ以外はすべて、その場所を指すリンクか埋め込みです。どこかに貼るために PNG をエクスポートしようとしているなら、リンクで足りないか考えてください。たいていは足ります。

2. コピーせずリンクする

Wiki、ドキュメントサイト、README は、図の画像を載せるのではなく、生きた図を参照するべきです。ライブで埋め込まれた図は元が変われば変わりますが、貼り付けたスクリーンショットは次の変更以降ずっと間違ったままです。監査担当者向けの PDF など、静的な画像がどうしても必要な場合は、日付付きのエクスポートとして扱い、日常的に参照されるドキュメントには置かないようにします。

3. オーナーを決める

すべての図にオーナーを置きます。個人、または窓口となる担当者が決まっているチームです。オーナーがすべての変更を描くわけではありませんが、図が間違っていることに気づき、質問を受けるのはオーナーです。オーナー名は図そのものと、図のインデックスの両方に書きます。

4. 既存のイベントに更新トリガーを結びつける

記憶に頼らないでください。すでに発生しているイベントに図の更新を結びつけます。

プルリクエスト。 PR テンプレートに「アーキテクチャへの影響」のチェックボックスを追加します。
ADR。 承認されたアーキテクチャ決定記録（ADR）は、変更対象の図にリンクし、承認の一部として図を更新します。
インシデントのポストモーテム。 図が間違っていた、あるいは依存関係が欠けていたことがインシデントで判明したら、その修正をアクションアイテムにします。
四半期レビュー。 オーナーが図ごとに数分かけて現実と一致しているか確認し、「最終レビュー日」を更新します。

PR テンプレートの例です。

## Architecture impact
- [ ] This change does not affect any architecture diagram
- [ ] I updated the affected diagram(s) and linked them below
- [ ] This needs an ADR (link):

5. 適切な詳細レベルを選ぶ

巨大な一枚絵ではなく、レベルに分けます。C4 model は共通の語彙を提供してくれます。System Context ビュー（人とシステム）、Container ビュー（アプリケーションとデータストア）、そして一つの container の内部を示す Component ビューです。上位レベルはめったに変わらず、正確に保つコストも低めです。下位レベルは頻繁に変わるので、必要とされる部分だけを描き、それより下はコードを情報源にします。

役に立つ目安があります。スプリントのたびに変わる図は、おそらく一段深く描きすぎています。

6. 日付とバージョンを見えるようにする

すべての図の隅に、オーナーと「最終レビュー日」を入れます。読む人はひと目で信頼度を判断できます。先月レビューされた図と 2 年前にレビューされた図では、信頼してよい度合いが違います。日付がないと、どの図も同じくらい正式に見えてしまい、古い日付を示すよりも悪い結果になります。

7. 図のインデックスを持つ

重要な図をすべて一つのページにまとめます。

図	レベル	オーナー	最終レビュー	関連 ADR
Payments: context	C4 context	Payments リード	2026-09-14	ADR-012
Payments: containers	C4 container	Payments チーム	2026-09-14	ADR-019

インデックスがあれば抜け漏れ（オーナー不在、古い日付）が見えるようになり、四半期レビューの出発点にもなります。

8. 図と ADR を組み合わせる

図はアーキテクチャが 何であるか を示します。なぜそうなっているかは示せません。そのギャップを埋めるのがアーキテクチャ決定記録です。Michael Nygard のオリジナルの ADR フォーマットは、実際に書いてもらえるほど短く、タイトル、ステータス、コンテキスト、決定、結果で構成されます。図から ADR へ、ADR から図へ、双方向にリンクします。

# ADR-019: Move payment events to a dedicated queue

## Status
Accepted

## Context
Payment events share a queue with notifications.

## Decision
Give payment events their own queue.

## Consequences
One more queue to operate. Diagram "Payments: containers" updated.

半年後に誰かが「なぜこうなっているの？」と聞いても、答えはワンクリック先にあります。

Archboard で生きたドキュメントのワークフローを回す

Archboard はクラウドでホストされるアーキテクチャワークスペースで、上記のワークフローの大部分は既存の機能に対応しています。何をカバーしていて、どこに独自のプロセスが必要かをまとめます。

唯一の情報源。 各図はワークスペース内の一つのドキュメントで、自動保存とリビジョンスナップショットがあります。Free は直近 5 件のリビジョンを保持し、Pro は 1 年分のリビジョン履歴を保持します。Enterprise には上限がありません。
コピーせずリンクする。 すべてのプランに公開共有リンクがあります（Free ではブランド表示付き）。Pro と Enterprise では iframe で図をドキュメントサイトに埋め込めるので、古くなっていくスクリーンショットではなく現在のバージョンが表示されます。
リポジトリでの履歴管理。 図を構造化 JSON としてエクスポートし、コードや ADR の隣にコミットします。アプリ内のリビジョンに加えて、Git の履歴と図の変更に対するレビューの手順が得られます。エクスポートは手動なので、PR の習慣に組み込んでください。
キャンバス上のメモ。 Markdown ノードはキャンバス上に置けるので、オーナー、最終レビュー日、ADR へのリンク、短い凡例を別ドキュメントではなく図の中に置けます。
適切な詳細レベル。 C4 Model パックには Person、Software System、Container、Component、Database のノードと boundary があります。ノードはポートを持つファーストクラスのノードで、ポート同士をつないで接続します。context ビューと container ビューは別々の図にしておきましょう。

一つのシステムでの具体的なセットアップ例です。

「Payments: Context」と「Payments: Containers」の 2 つの図を作成します。
左上にオーナー、最終レビュー日、関連 ADR へのリンクを書いた Markdown ノードを追加します。
Pro では、サービスのドキュメントページに container ビューを埋め込みます。Free では共有リンクを使います。
PR でアーキテクチャが変わるときは、図を更新し（または、その PR で作業しているコーディングエージェントに Archboard の MCP サーバー経由で更新を任せ）、JSON をエクスポートして、同じ PR で docs/architecture/ にコミットします。
両方の図をインデックスページに追加します。

機能の全体像は製品概要、C4 固有の設定は C4 のユースケース、各プランの内容は料金をご覧ください。Free では、それぞれ 15 ダイアグラムノードと 150 件のメモ・テキスト・ステッカー・マインドマップのトピックを置ける 3 つのダイアグラムを使って、1 つのシステムのコンテキストビューを試せます。プラットフォーム全体をドキュメント化するときは、Pro で図とノードが無制限になります。