リビングアーキテクチャドキュメンテーションはフォーマットではなく、働き方です。モデルはコードから導出され、更新は変更と同じプルリクエストに同乗し、それがうまくいったかを何かがチェックします。それを成立させる5つのプラクティス、それぞれのコスト、そしてそれぞれが破綻する場所を解説します。

リビングアーキテクチャドキュメンテーション：ドキュメントを常に最新に保つ

先週の火曜日、誰かがサービスを1つ追加するプルリクエストをマージしました。そして、他には何も起きませんでした。図は1つも変わらず、ADRも書かれず、レビュー自体は入念でした。誰もアーキテクチャに言及しなかったのは、レビューの対象がアーキテクチャではなかったからです。

本記事のテーマはそこにあります。ドキュメンテーションが古くなること自体ではありません。それはアーキテクチャドリフトのガイドが検出方法とあわせて扱っています。テーマは、最新に保てたはずの唯一の瞬間が、正常でよく回っているワークフローの内側で通り過ぎてしまったことです。リビングドキュメンテーションとは、その瞬間を取りこぼさないようにする仕掛けの総体です。これは問題の実践側の半分です。5つの戦略、それぞれのコスト、そしてそれぞれが破綻する場所を扱います。

ドキュメンテーションを「リビング」にするもの

リビングドキュメンテーションには、従来の静的ドキュメンテーションと区別する3つの定義的な特性があります。

自動的に更新される

リビングドキュメンテーションは、人間が更新を思い出すことだけに頼りません。ドキュメンテーションの少なくとも一部の側面はシステム自体（コード、デプロイメント、インフラ、API定義）から導出されます。システムが変わると、手動介入なしにドキュメンテーションがその変更を反映します。

すべてが自動化されるわけではありません。アーキテクチャの意図、設計の根拠、戦略的な意思決定は依然として人間の著作を必要とします。しかし、事実的で構造的な側面（どのサービスが存在するか、どの技術を使用しているか、どう接続されているか）は自動化できるし、すべきです。

継続的に検証される

リビングドキュメンテーションには、現実と乖離した時に検出するメカニズムが含まれています。誰かが読んで間違いに気づいた時に古いドキュメンテーションを発見するのではなく、検証がドリフトを事前に検出します。

実際には、これは2つの異なるチェックです。後述の戦略3ではそれをきちんと分けています。1つは適合性ルールで、あなたが定めた基準にモデルが従っているかを検証します。もう1つはドリフト検出で、コードベースに対してモデルを検証します。どちらもCIで実行できます。どちらも、悪い方向に動いた時にはアラートを出す価値があります。

開発ワークフローの一部

リビングドキュメンテーションは別のプロセスでメンテナンスされません。開発ワークフロー（コードが書かれ、レビューされ、デプロイされるのと同じワークフロー）に統合されています。アーキテクチャの変更はプルリクエストを通じて行われます。ドキュメンテーションの更新はコード変更と一緒に行われます。ドキュメンテーションは開発者が既に作業している場所に存在します。

静的ドキュメンテーションの問題

働き方を変えるべき理由は、その代替手段には決まった形があり、2度見れば早い段階で見分けられるようになるからです。

作成-劣化サイクル

善意によって維持されるドキュメンテーションは、予測可能なサイクルをたどります。

作成: やる気のあるチームメンバー（またはアーキテクト、コンサルタント）がドキュメンテーションを書きます。正確で、詳細で、よく整理されています。
有用性: 数週間から数ヶ月、ドキュメンテーションは価値があります。チームメンバーが参照します。新入社員がそこから学びます。
最初のドリフト: 変更が発生します。新しいサービス、名前変更されたコンポーネント、変更された依存関係。変更を行った開発者がそれを思い出さなかった、ドキュメンテーションがどこにあるか知らなかった、または時間がなかったため、ドキュメンテーションは更新されません。
加速する劣化: 最初の不正確さが現れると、劣化の速度が加速します。以降の各変更がドキュメンテーションに反映される確率は低くなります。信頼は比例して低下します。
放棄: 最終的に、ドキュメンテーションは非常に古くなり、誰も信頼しなくなります。「システムが実際にどのように見えるか」ではなく「システムがかつてどのように見えたか」の参考資料になります。
再作成: 誰かが問題を認識し、ゼロからドキュメンテーションを作り直します。サイクルが再び始まります。

コストが高いのはステップ6です。各作成フェーズには実際の労力がかかりますが、その大半は前回の作成がすでに知っていたことを再び導き出すために費やされます。試行と試行のあいだで、仕組みが何も変わっていないからです。チームが同じアーキテクチャドキュメンテーションの2回目、3回目の書き直しに取りかかっているなら、問題は最初から「書くこと」ではありませんでした。

人間のボトルネック

静的ドキュメンテーションは、人間が何か余分なことをすることに完全に依存しています。機能を完成させた後、開発者はアーキテクチャ図を更新することを思い出す必要があります。設計セッションの後、誰かがホワイトボードの議論を構造化されたドキュメンテーションに変換する必要があります。リファクタリングの後、誰かが影響を受けるすべての図がまだ正確であることを確認する必要があります。

これらのそれぞれは他の優先事項と競合する手動ステップです。そしてほとんどの組織では、ドキュメンテーションの更新はコードの記述、バグの修正、締め切りの遵守よりも低い優先度です。結果は予測可能です。ドキュメンテーションが遅れます。

発見の問題

ドキュメンテーションが正確であっても、しばしば見つけにくいものです。アーキテクチャ図はConfluenceにあります。API仕様は別のツールにあります。ADRはGitリポジトリにあります。技術の選択はWikiに文書化されています。完全な画像を提供する単一の場所がなく、開発者はツール間を検索して時間を浪費します -- もし検索するとすればですが。

リビングアーキテクチャドキュメンテーションの戦略

ドキュメンテーションを真にリビングにするには、複数の戦略を組み合わせる必要があります。単一のアプローチだけでは十分ではありませんが、組み合わせることで最小限の手動労力でドキュメンテーションが最新に保たれるシステムが作られます。

戦略1：コード駆動ドキュメンテーション

ドキュメンテーションを最新に保つ最も効果的な方法は、コードから導出することです。ドキュメンテーションがシステムのソースコード、設定、またはインフラ定義から生成される場合、ドリフトすることはできません。なぜなら常に現在の状態から再構築されるからです。

Architecture as Codeはこの戦略の最も直接的な実装です。ビジュアルツールで図を描いて誰かが更新することを期待する代わりに、Gitリポジトリに存在するYAMLファイルでアーキテクチャを定義します。ファイルが唯一の真実の源であり、ビジュアルな図はそこから生成されます。

開発者が新しいサービスを追加する際、同じプルリクエストでアーキテクチャファイルに数行を追加します。変更は実装と一緒にコードレビューを通過します。CI/CDパイプラインが更新されたファイルをドキュメンテーションプラットフォームに同期します。図はコードから常に再生成されるため、常に最新です。

APIコントラクト生成もコード駆動ドキュメンテーションの一形態です。OpenAPIジェネレーターのようなツールは、注釈付きコードからAPI仕様を生成できます。APIドキュメントを別途メンテナンスする代わりに、実装からドキュメントが抽出されます。コードが変わると、ドキュメントも変わります。

Archylでは、archyl.yaml ファイルがコード駆動の唯一の真実の源として機能します。REST APIまたはMCPサーバーを使用して、ビルドパイプラインからプログラマティックにアーキテクチャ要素を更新することもでき、自動化されたプロセスがドキュメンテーションの同期を保つことを確実にします。

戦略2：AI搭載の発見

コード駆動ドキュメンテーションでも、コードで明示的でないアーキテクチャの側面があります。サービスが環境変数で設定されたデータベースを使用しているかもしれません。2つのサービスがインフラコードで定義された共有Kafkaトピックを通じて通信しているかもしれません。新しいサービスがデプロイメントパイプラインには存在するがアーキテクチャファイルにはまだないかもしれません。

AI搭載の発見はコードベース、インフラ、デプロイメントアーティファクトを分析してアーキテクチャドキュメンテーションへの更新を提案することで、これらのギャップを埋めます。

ArchylのAI Discovery機能はリポジトリをスキャンし、以下を特定します。

まだ文書化されていない新しいサービス
コードに存在するがアーキテクチャモデルに反映されていない依存関係
前回のドキュメンテーション更新以降に変更された技術スタック
文書化されたものと異なる通信パターン

AIはドキュメンテーションを自動的に変更しません。人間がレビューして承認する変更を提案します。モデルが何を語るかの判断は、依然としてすべてあなたが下します。やめられるのは、何が変わったのかを探し回る作業のほうです。

戦略3：適合性ルールとドリフト検出

リビングドキュメンテーションには2つのガードレールが必要です。そして両方とも数値を出し、両方とも派手に失敗するため、日常的に混同されます。この2つは違うものを測っています。

適合性ルールは、あなたのモデルがあなたの定めた基準に従っているかを問います。すべてのコンテナが技術を明記している、すべての外部システムに説明がある、孤立要素がない。ルールエンジンがそれらを評価し、違反を報告します。

ドリフト検出は、あなたのモデルがまだコードベースと一致しているかを問います。文書化されたアーキテクチャをリポジトリと比較し、0から100までのスコアを返します。あなたのルールについては何も知りません。

モデルは、あなたが書いたすべてのルールを満たしながら、前四半期のリファクタリングで消滅したシステムを記述していることがあります。その逆も起こります。正確なモデルが、あなたの基準の半分を破っているという場合です。両方のチェックが必要であり、片方の数字をもう片方であるかのように読んではいけません。ドリフトスコアの計算方法が後者を詳しく扱っており、それが見られないものについても説明しています。

適合性ルールの例：

すべてのコンテナに少なくとも1つの技術が文書化されている
すべての外部システムに説明がある
データベース依存関係を持つすべてのサービスにデータオーナーシップの説明が文書化されている
孤立したコンテナがない（すべてのコンテナが少なくとも1つのリレーションシップに参加している）
すべてのADRが少なくとも1つのアーキテクチャ要素を参照している
すべてのAPI型コンテナにリンクされたAPIコントラクトがある

Archylはこの種のルールを169個のカタログとして提供しており、23の名前付き技術と言語非依存のセットをカバーしています。そのためほとんどのチームは、自分でルールを書くのではなく、当てはまるものを有効にするところから始めます。違反は要素ごとに報告されます。これが重要です。「7つのコンテナに文書化された技術がない」はタスクですが、「あなたのドキュメンテーションは不完全だ」はただの気分です。

ドリフトスコアは別途、オンデマンドまたはCIジョブから計算され、10ポイント以上下落するとwebhookが発火します。この2つが揃うことで、プルリクエストが開いたまま残したループが閉じます。ルールは最後まで仕上げられなかったドキュメンテーションを捕まえ、スコアは真実であることをやめたドキュメンテーションを捕まえます。

戦略4：完了の定義の一部としてのドキュメンテーション

リビングドキュメンテーションのための最も効果的な組織戦略は、アーキテクチャに影響するあらゆる作業の完了の定義にドキュメンテーション更新を含めることです。

これは以下を意味します。

プルリクエストが新しいサービスを追加する場合、同じPRでアーキテクチャファイルを更新する
設計セッションで意思決定がなされた場合、その決定が実装される前にADRを作成する
APIコントラクトが変更される場合、文書化されたコントラクトを更新する
サービスが廃止される場合、アーキテクチャモデルから削除する

これは官僚主義ではありません。「変更が発生する時」と「ドキュメンテーションが更新される時」のギャップをゼロに縮めることです。ドキュメンテーションがコード変更と同じワークフローの一部であれば、別の作業は必要ありません。

Archylはarchitecture-as-code統合を通じてこれをサポートします。アーキテクチャファイルがコードと同じリポジトリに存在する場合、同じプルリクエストで両方を更新するのは自然なことです。コードレビュアーはアーキテクチャの変更が実装と一緒に文書化されているか確認できます。

戦略5：継続的な可視化

リビングドキュメンテーションはアクセスしやすくビジュアルに情報を伝えるものでなければなりません。開発者がアーキテクチャを理解するためにYAMLファイルをパースする必要がある場合、採用は進みません。コードベースの定義は常に最新で、常にアクセス可能で、常に有用なビジュアル出力を生成すべきです。

これは以下を意味します。

唯一の真実の源から自動的に再生成されるアーキテクチャ図
System Contextからコンテナ、コンポーネントへとズームできるインタラクティブなナビゲーション
特定の側面（オーナーシップ、技術スタック、通信パターン）を強調するオーバーレイ
すべてのアーキテクチャ要素、リレーションシップ、ドキュメンテーションにわたる検索

Archylのビジュアルレイヤーはモデルから読み取ります。そのため、そのモデルがどう更新されたか（YAMLファイル、MCPサーバー、REST API、ビジュアルエディタ）にかかわらず、誰も描き直すことなく図が現在の状態を示します。これが何をもたらすのかを正確に押さえてください。図は常にモデルと一致します。モデルがコードと一致しているかどうかは、ドリフトスコアの問いであって、レンダラーの問いではありません。

ドキュメンテーションの鮮度の測定

リビングドキュメンテーションは測定可能であるべきです。重要なメトリクスは以下の通りです。

ドリフトスコア

この実践が機能しているかを教えてくれる唯一の数値です。文書化されたアーキテクチャのうちどれだけがまだコードベースに存在するかを測定し、本記事の仕掛けが効いていれば、下落が止まります。main へのプッシュごとにCIから起動すれば、そのトレンドラインはあなたの意図についてではなく、あなたのワークフローについての正直な報告になります。

仕組みの全体、計算式、そしてそれが見られない4つのものについては、専用の記事で扱っています。

ドキュメント化までの時間

アーキテクチャの変更がドキュメンテーションに反映されるまでの時間を測定します。うまく機能しているリビングドキュメンテーションシステムでは、これはほぼゼロに近いはずです。なぜなら、ドキュメンテーションの更新はコード変更と同じプルリクエストで行われるからです。一貫した遅延がある場合、ワークフロー統合の改善が必要です。

カバレッジ

アーキテクチャのどの程度が文書化されているかを追跡します。サービスのうち何パーセントに説明があるか？リレーションシップのうち何パーセントにラベルがあるか？コンテナのうち何パーセントに技術スタックが文書化されているか？カバレッジメトリクスはギャップがどこにあるかを教えてくれます。

信頼度調査

定期的に開発者に聞きます。「アーキテクチャドキュメンテーションを信頼していますか？」答えがノーなら、定量的メトリクスが何を示していようと、リビングドキュメンテーションの実践を改善する必要があります。開発者の信頼がドキュメンテーション品質の究極の指標です。

よくある落とし穴

すべてを自動化する

すべてを自動化できるわけではないし、すべきでもありません。アーキテクチャの意図、設計の根拠、トレードオフの分析、戦略的な方向性には人間の著作が必要です。リビングドキュメンテーションは事実的で構造的な側面を自動化しながら、人間の洞察のためのスペースを保持します。

適合性をコンプライアンスとして扱う

適合性ルールは有用であるべきで、懲罰的であるべきではありません。意図しないドリフトをキャッチするために存在し、官僚的なオーバーヘッドを作るためではありません。チームが有用な作業をするよりも適合性ルールを満たすことに多くの時間を費やしている場合、ルールが厳しすぎます。

オンボーディングのユースケースを無視する

リビングドキュメンテーションは、システムを一度も見たことがない人にもアクセスしやすくあるべきです。ドキュメンテーションを理解するのに深いコンテキストが必要な場合、最も重要な目的の一つを果たしていません。新人の視点から定期的にドキュメンテーションを確認してテストしてください。

完璧を善の敵にする

有用なリビングドキュメンテーションのために、完全なカバレッジと完璧なドリフトスコアは必要ありません。サービスの大半をカバーし毎週更新されるContainer図は、6ヶ月前に正確だった完全なドキュメンテーションセットよりも価値があります。CIのしきい値は今日の自分たちより低いところに設定し、チームの準備が整ったら引き上げてください。誰も到達したことのない数値でゲートをかけるよりも、そのほうが機能します。

Archylがリビングアーキテクチャドキュメンテーションを実現する方法

Archylはリビングドキュメンテーションの実践をサポートするためにゼロから構築されています。各機能がどう貢献するかを示します。

Architecture as Codeはドキュメンテーションをコード駆動にします。archyl.yaml ファイルはGitに存在し、コードレビューを通過し、CI/CDを通じて自動的に同期されます。アーキテクチャファイルの変更はビジュアルな図に即座に反映されます。

AI Discoveryはコードベースを分析して更新を提案することでドキュメンテーションのギャップを特定します。新しいサービス、変更された依存関係、更新された技術スタックをキャッチし、そうでなければ文書化されないままになる可能性のあるものです。

適合性ルールは正しいドキュメンテーションがどのようなものかを定義し、違反を要素ごとに報告します。ドリフト検出は別のチェックです。モデルをリポジトリと比較し、その差をスコア化します。ルールは最後まで仕上げられなかったドキュメンテーションを捕まえ、スコアは真実であることをやめたドキュメンテーションを捕まえます。

MCPサーバーはアーキテクチャドキュメンテーションをAI支援開発ワークフローに統合します。開発者は別のツールにコンテキストスイッチすることなくIDEからドキュメンテーションをクエリして更新できます。

オーナーシップマップはすべてのアーキテクチャ要素を責任あるチームにマッピングすることで説明責任を作ります。ドキュメンテーションがドリフトすると、所有チームが特定され、アクションを取ることができます。

コラボレーション機能 -- コメント、変更リクエスト、リアルタイム共同編集 -- はドキュメンテーションを個人の負担ではなくチーム活動にします。

リリース追跡とDORAメトリクスはアーキテクチャドキュメンテーションをデリバリーパフォーマンスに接続し、アーキテクチャの意思決定がチームのソフトウェアリリース能力を改善しているか妨げているかについての継続的なシグナルを提供します。

始め方

アーキテクチャドキュメンテーションが現在静的な場合、リビングにするための実践的なパスは以下の通りです。続ける理由が得られる順番で並べています。

すでにあるものを測定する。 チームの働き方を変える前に、既存のモデルに対してドリフトスコアを計算します。リポジトリを1つ接続するだけで済み、以降のすべてのステップを判断する基準値が手に入ります。
Container図から始める。 サービス、その技術、主要なリレーションシップ。それを正式なリファレンスにし、次点のものは削除してください。真実の源が2つあるということは、ゼロだということです。
アーキテクチャをコードに移す。 モデルを archyl.yaml としてエクスポートし、リポジトリにコミットし、CI/CD同期を設定します。
適合性ルールを追加する。 明らかなもの（すべてのコンテナが技術を明記する、すべてのコンテナが少なくとも1つのリレーションシップに含まれる）から始め、チームがそれにつまずかなくなったら拡張します。
ドキュメンテーションをPRワークフローの一部にする。 チェックリスト項目でも機能します。CIでのドリフトのしきい値ならもっとよく機能します。尋ねるのではなく、失敗するからです。
MCPサーバーを設定する。 コーディングエージェントにモデルを渡し、アーキテクチャの読み取りと更新が作業の後ではなく、作業の流れの中で行われるようにします。
数値ではなくトレンドを見る。 月次で十分です。問うべきは、ステップ3から6が踏みとどまれているかどうかであり、それに答えられるのはトレンドだけです。

リビングアーキテクチャドキュメンテーションは目的地ではなく、実践です。目標は完璧なドキュメンテーションではなく、信頼されるのに十分な精度があり、そのように維持するために一貫してメンテナンスされるドキュメンテーションです。そのどちらを手にしているかを知る方法が、スコアです。

このクラスターの残り：問題そのものと検出方法についてはアーキテクチャドリフトの検出、仕組みについてはドリフトスコアの計算方法。用語の定義：リビングドキュメンテーション、アーキテクチャドリフト。製品ページ：ドリフト検出。ステップ1はDeveloperプランで無料、カード不要です：archyl.com。

リビングアーキテクチャドキュメンテーション：ドキュメントを常に最新に保つ - Archyl Blog