リビングアーキテクチャドキュメンテーション：ドキュメントを常に最新に保つ
すべてのエンジニアリングチームが経験したことがあるでしょう。新しいプロジェクトに参加し、アーキテクチャドキュメンテーションを見つけて読み始めます。System Context図には3つの外部統合が表示されていますが、コードベースは7つと通信しています。Container図には6ヶ月前に廃止された「Legacy Auth Service」がリストされています。PostgreSQLの使用に関するADRは、概念実証の後に中止されたCockroachDBへの移行を参照しています。
ドキュメンテーションが間違っているのは、誰かが不注意だったからではありません。ドキュメンテーションの劣化がデフォルトの状態だからです。システムは継続的に進化します。新しいサービスが追加され、古いものが削除され、通信パターンが変わり、技術スタックが更新されます。ドキュメンテーションが同じペースで進化しない限り、遅れます。そして遅れ始めると、信頼が崩れます。開発者はそれを参照しなくなります。新しいチームメンバーはそれを無視することを学びます。ドキュメンテーションはアーキテクチャのフィクションになります。
リビングアーキテクチャドキュメンテーションがその解決策です。これは特定のツールやフォーマットではなく、ドキュメンテーションを記述するシステムと同期させ続ける実践と原則のセットです。このガイドでは、リビングドキュメンテーションが実際に何を意味するか、それを機能させる戦略、そしてArchylがそれぞれをどう実現するかを解説します。
ドキュメンテーションを「リビング」にするもの
リビングドキュメンテーションには、従来の静的ドキュメンテーションと区別する3つの定義的な特性があります。
自動的に更新される
リビングドキュメンテーションは、人間が更新を思い出すことだけに頼りません。ドキュメンテーションの少なくとも一部の側面はシステム自体（コード、デプロイメント、インフラ、API定義）から導出されます。システムが変わると、手動介入なしにドキュメンテーションがその変更を反映します。
すべてが自動化されるわけではありません。アーキテクチャの意図、設計の根拠、戦略的な意思決定は依然として人間の著作を必要とします。しかし、事実的で構造的な側面（どのサービスが存在するか、どの技術を使用しているか、どう接続されているか）は自動化できるし、すべきです。
継続的に検証される
リビングドキュメンテーションには、現実と乖離した時に検出するメカニズムが含まれています。誰かが読んで間違いに気づいた時に古いドキュメンテーションを発見するのではなく、検証がドリフトを事前に検出します。
これは、文書化されたアーキテクチャを実際のインフラと比較する適合性チェックの実行を意味するかもしれません。アーキテクチャ定義をコードベースに対して検証するCI/CDパイプラインかもしれません。ドリフトスコアを表示し、精度がしきい値を下回った時にアラートを出すダッシュボードかもしれません。
開発ワークフローの一部
リビングドキュメンテーションは別のプロセスでメンテナンスされません。開発ワークフロー（コードが書かれ、レビューされ、デプロイされるのと同じワークフロー）に統合されています。アーキテクチャの変更はプルリクエストを通じて行われます。ドキュメンテーションの更新はコード変更と一緒に行われます。ドキュメンテーションは開発者が既に作業している場所に存在します。
静的ドキュメンテーションの問題
リビングドキュメンテーションが重要な理由を理解するために、従来のドキュメンテーションがどのように失敗するかを考えてみましょう。
作成-劣化サイクル
従来のドキュメンテーションは予測可能なサイクルに従います。
- 作成: やる気のあるチームメンバー（またはアーキテクト、コンサルタント）が包括的なドキュメンテーションを作成。正確で、詳細で、よく整理されています。
- 有用性: 数週間から数ヶ月、ドキュメンテーションは価値があります。チームメンバーが参照します。新入社員がそこから学びます。
- 最初のドリフト: 変更が発生します。新しいサービス、名前変更されたコンポーネント、変更された依存関係。変更を行った開発者がそれを思い出さなかった、ドキュメンテーションがどこにあるか知らなかった、または時間がなかったため、ドキュメンテーションは更新されません。
- 加速する劣化: 最初の不正確さが現れると、劣化の速度が加速します。以降の各変更がドキュメンテーションに反映される確率は低くなります。信頼は比例して低下します。
- 放棄: 最終的に、ドキュメンテーションは非常に古くなり、誰も信頼しなくなります。「システムが実際にどのように見えるか」ではなく「システムがかつてどのように見えたか」の参考資料になります。
- 再作成: 誰かが問題を認識し、ゼロからドキュメンテーションを作り直します。サイクルが再び始まります。
このサイクルはほとんどの組織で6〜18ヶ月ごとに繰り返されます。各作成フェーズに投資された労力は、ドキュメンテーションが現実との接触に耐えないため、大部分が無駄になります。
人間のボトルネック
静的ドキュメンテーションは、人間が何か余分なことをすることに完全に依存しています。機能を完成させた後、開発者はアーキテクチャ図を更新することを思い出す必要があります。設計セッションの後、誰かがホワイトボードの議論を構造化されたドキュメンテーションに変換する必要があります。リファクタリングの後、誰かが影響を受けるすべての図がまだ正確であることを確認する必要があります。
これらのそれぞれは他の優先事項と競合する手動ステップです。そしてほとんどの組織では、ドキュメンテーションの更新はコードの記述、バグの修正、締め切りの遵守よりも低い優先度です。結果は予測可能です。ドキュメンテーションが遅れます。
発見の問題
ドキュメンテーションが正確であっても、しばしば見つけにくいものです。アーキテクチャ図は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：適合性ルールとドリフト検出
リビングドキュメンテーションには、ドキュメンテーションが現実から乖離した時に検出するガードレールが含まれています。適合性ルールは「正しい」ドキュメンテーションがどのようなものかを定義し、ドリフト検出は現在のドキュメンテーションがそれらのルールからどれだけ逸脱しているかを測定します。
適合性ルールの例：
- すべてのコンテナに少なくとも1つの技術が文書化されている
- すべての外部システムに説明がある
- データベース依存関係を持つすべてのサービスにデータオーナーシップの説明が文書化されている
- 孤立したコンテナがない（すべてのコンテナが少なくとも1つのリレーションシップに参加している）
- すべてのADRが少なくとも1つのアーキテクチャ要素を参照している
- すべてのAPI型コンテナにリンクされたAPIコントラクトがある
これらのルールが違反されると、ドリフトが自動的に表面化されます。チームはドキュメンテーション精度の数値的指標であるドリフトスコアを確認し、注意が必要な領域を正確に特定できます。
Archylの適合性エンジンはこれらのルールを継続的に評価します。ドリフトスコアはプロジェクトダッシュボードに表示され、チームはスコアがしきい値を下回った時のアラートを設定できます。これにより、ドキュメンテーションドリフトが信頼を損なうほど深刻になる前に、早期に検出されるフィードバックループが作成されます。
戦略4：完了の定義の一部としてのドキュメンテーション
リビングドキュメンテーションのための最も効果的な組織戦略は、アーキテクチャに影響するあらゆる作業の完了の定義にドキュメンテーション更新を含めることです。
これは以下を意味します。
- プルリクエストが新しいサービスを追加する場合、同じPRでアーキテクチャファイルを更新する
- 設計セッションで意思決定がなされた場合、その決定が実装される前にADRを作成する
- APIコントラクトが変更される場合、文書化されたコントラクトを更新する
- サービスが廃止される場合、アーキテクチャモデルから削除する
これは官僚主義ではありません。「変更が発生する時」と「ドキュメンテーションが更新される時」のギャップをゼロに縮めることです。ドキュメンテーションがコード変更と同じワークフローの一部であれば、別の作業は必要ありません。
Archylはarchitecture-as-code統合を通じてこれをサポートします。アーキテクチャファイルがコードと同じリポジトリに存在する場合、同じプルリクエストで両方を更新するのは自然なことです。コードレビュアーはアーキテクチャの変更が実装と一緒に文書化されているか確認できます。
戦略5：継続的な可視化
リビングドキュメンテーションはアクセスしやすくビジュアルに情報を伝えるものでなければなりません。開発者がアーキテクチャを理解するためにYAMLファイルをパースする必要がある場合、採用は進みません。コードベースの定義は常に最新で、常にアクセス可能で、常に有用なビジュアル出力を生成すべきです。
これは以下を意味します。
- 唯一の真実の源から自動的に再生成されるアーキテクチャ図
- System Contextからコンテナ、コンポーネントへとズームできるインタラクティブなナビゲーション
- 特定の側面（オーナーシップ、技術スタック、通信パターン）を強調するオーバーレイ
- すべてのアーキテクチャ要素、リレーションシップ、ドキュメンテーションにわたる検索
Archylのビジュアルレイヤーは常に基盤となるモデルと同期しています。そのモデルがYAMLファイル、MCPサーバー、REST API、ビジュアルエディタのいずれを通じて更新されても、図は現在の状態を反映します。これにより、ほとんどの開発者が実際にインタラクトするビジュアルドキュメンテーションが常に正確であることが確保されます。
ドキュメンテーションの鮮度の測定
リビングドキュメンテーションは測定可能であるべきです。重要なメトリクスは以下の通りです。
ドリフトスコア
ドリフトスコアは、ドキュメンテーションが定義されたルールにどれだけ適合しているかを測定します。100のスコアはすべてのルールが満たされていることを意味します。70のスコアはルールの30%が違反していることを意味します。このスコアを時間の経過とともに追跡し、ドキュメンテーションの精度が向上しているか低下しているかを把握します。
Archylは適合性ルールに基づいてドリフトスコアを自動的に計算し、プロジェクトダッシュボードに表示します。
ドキュメント化までの時間
アーキテクチャの変更がドキュメンテーションに反映されるまでの時間を測定します。うまく機能しているリビングドキュメンテーションシステムでは、これはほぼゼロに近いはずです。なぜなら、ドキュメンテーションの更新はコード変更と同じプルリクエストで行われるからです。一貫した遅延がある場合、ワークフロー統合の改善が必要です。
カバレッジ
アーキテクチャのどの程度が文書化されているかを追跡します。サービスのうち何パーセントに説明があるか？リレーションシップのうち何パーセントにラベルがあるか？コンテナのうち何パーセントに技術スタックが文書化されているか？カバレッジメトリクスはギャップがどこにあるかを教えてくれます。
信頼度調査
定期的に開発者に聞きます。「アーキテクチャドキュメンテーションを信頼していますか？」答えがノーなら、定量的メトリクスが何を示していようと、リビングドキュメンテーションの実践を改善する必要があります。開発者の信頼がドキュメンテーション品質の究極の指標です。
よくある落とし穴
すべてを自動化する
すべてを自動化できるわけではないし、すべきでもありません。アーキテクチャの意図、設計の根拠、トレードオフの分析、戦略的な方向性には人間の著作が必要です。リビングドキュメンテーションは事実的で構造的な側面を自動化しながら、人間の洞察のためのスペースを保持します。
適合性をコンプライアンスとして扱う
適合性ルールは有用であるべきで、懲罰的であるべきではありません。意図しないドリフトをキャッチするために存在し、官僚的なオーバーヘッドを作るためではありません。チームが有用な作業をするよりも適合性ルールを満たすことに多くの時間を費やしている場合、ルールが厳しすぎます。
オンボーディングのユースケースを無視する
リビングドキュメンテーションは、システムを一度も見たことがない人にもアクセスしやすくあるべきです。ドキュメンテーションを理解するのに深いコンテキストが必要な場合、最も重要な目的の一つを果たしていません。新人の視点から定期的にドキュメンテーションを確認してテストしてください。
完璧を善の敵にする
有用なリビングドキュメンテーションのために100%のカバレッジと完璧なドリフトスコアは必要ありません。サービスの80%をカバーし毎週更新されるContainer図は、6ヶ月前に正確だった包括的なドキュメンテーションセットよりもはるかに価値があります。
Archylがリビングアーキテクチャドキュメンテーションを実現する方法
Archylはリビングドキュメンテーションの実践をサポートするためにゼロから構築されています。各機能がどう貢献するかを示します。
Architecture as Codeはドキュメンテーションをコード駆動にします。archyl.yaml ファイルはGitに存在し、コードレビューを通過し、CI/CDを通じて自動的に同期されます。アーキテクチャファイルの変更はビジュアルな図に即座に反映されます。
AI Discoveryはコードベースを分析して更新を提案することでドキュメンテーションのギャップを特定します。新しいサービス、変更された依存関係、更新された技術スタックをキャッチし、そうでなければ文書化されないままになる可能性のあるものです。
適合性ルールは正しいドキュメンテーションがどのようなものかを定義し、現在の状態を継続的に検証します。ドリフトスコアはドキュメンテーション精度の単一数値サマリーを提供し、違反は事前に表面化されます。
MCPサーバーはアーキテクチャドキュメンテーションをAI支援開発ワークフローに統合します。開発者は別のツールにコンテキストスイッチすることなくIDEからドキュメンテーションをクエリして更新できます。
オーナーシップマップはすべてのアーキテクチャ要素を責任あるチームにマッピングすることで説明責任を作ります。ドキュメンテーションがドリフトすると、所有チームが特定され、アクションを取ることができます。
コラボレーション機能 -- コメント、変更リクエスト、リアルタイム共同編集 -- はドキュメンテーションを個人の負担ではなくチーム活動にします。
リリース追跡とDORAメトリクスはアーキテクチャドキュメンテーションをデリバリーパフォーマンスに接続し、アーキテクチャの意思決定がチームのソフトウェアリリース能力を改善しているか妨げているかについての継続的なシグナルを提供します。
始め方
アーキテクチャドキュメンテーションが現在静的な場合、リビングにするための実践的なパスは以下の通りです。
Container図から始める。 サービス、その技術、主要なリレーションシップを文書化する。Archylに入れてカノニカルなリファレンスにする。
アーキテクチャをコードに移す。 モデルを
archyl.yamlとしてエクスポートし、リポジトリにコミットし、CI/CD同期を設定する。適合性ルールを追加する。 基本的なルール（すべてのコンテナに技術が必要、すべてのコンテナに少なくとも1つのリレーションシップが必要）から始め、時間とともに拡張する。
ドキュメンテーションをPRワークフローの一部にする。 PRテンプレートにチェックリスト項目を追加する：「必要に応じてアーキテクチャドキュメンテーションを更新」。
MCPサーバーを設定する。 AIアシスタントにアーキテクチャモデルへのアクセスを与え、開発中にドキュメンテーションのクエリと更新が自然に行われるようにする。
ドリフトスコアを月次でレビューする。 トレンドを追跡し、精度が下がった時に調査する。
リビングアーキテクチャドキュメンテーションは目的地ではなく、実践です。目標は完璧なドキュメンテーションではなく、信頼されるのに十分な精度があり、そのように維持するために一貫してメンテナンスされるドキュメンテーションです。
Archylで始めましょう。アーキテクチャドキュメンテーションを常に最新に保ちましょう。