手動のアーキテクチャドキュメンテーションは勝ち目のない戦いです。コードは毎日変わり、図は四半期ごとに更新されます。AIはこの方程式を変えつつあります。コードからアーキテクチャを発見し、ドリフトを自動検出し、AIエージェントにアーキテクチャの認識を与えます。その仕組みと今後の方向性を解説します。

AI搭載アーキテクチャドキュメンテーション：未来はここにある

ソフトウェアアーキテクチャドキュメンテーションの中心には根本的な緊張関係があります。コードは生きています。コミット、リファクタリング、ホットフィックスのたびに変化します。ドキュメンテーションは静的です。誰かが更新を思い出した時にだけ変わります。この2つの間のギャップは静かに広がり、Wikiの図がもはや存在しないシステムを描写するようになります。

これは規律の問題ではありません。最も勤勉なチームでさえ、いずれは遅れをとります。Lattixの調査によると、ほとんどの組織でアーキテクチャドキュメンテーションは作成から数週間で古くなるとされています。正確な図を手動で維持するために必要な労力はシステムの複雑さとともに線形に増加する一方、コード変更の速度は一定か加速します。

AIはこの方程式を変えています。人間のアーキテクチャ判断を置き換えるのではなく、人間が苦手とするドキュメンテーションの部分 -- 発見、同期、ドリフト検出 -- を自動化することによってです。その結果、コードから始まり、自動的に最新の状態を維持し、人間とAIエージェントの両方に対する知識レイヤーとして機能するアーキテクチャドキュメンテーションが実現します。

手動アーキテクチャドキュメンテーションの問題

AIがどのように役立つかを探る前に、何が壊れているかを具体的に見てみましょう。

作成の問題

既存システムのアーキテクチャドキュメンテーションをゼロから作成するのは大変な作業です。コードを読み、依存関係をたどり、チームメンバーにインタビューし、ゆっくりとメンタルモデルを構築してそれを図に変換します。中規模のシステム（20〜30サービス）では数週間かかります。大規模なシステム（100以上のサービス）では数ヶ月かかります。

その間もシステムは変わり続けます。ドキュメンテーションが「完成」する頃には、その一部は既に古くなっています。動く的を文書化しているのです。

メンテナンスの問題

完璧なドキュメンテーションを作成できたとしても、正確さを維持するには継続的な努力が必要です。新しいサービス、名前が変更されたモジュール、廃止されたAPIのすべてをアーキテクチャ図に反映する必要があります。実際には以下を意味します。

開発者がコード変更に合わせて図を更新する必要がある
誰かが図の更新の正確さをレビューする必要がある
古い図を検出して修正する必要がある

ほとんどのチームはプロセスでこれを解決しようとします。「アーキテクチャを変更した時にアーキテクチャ図を更新する」。これは約3ヶ月間はうまくいきますが、締め切りと機能開発のプレッシャーにより、ドキュメンテーションの更新は優先順位の最下位に押しやられます。

発見の問題

新しいエンジニアがチームに加わる際、生産性を発揮する前にアーキテクチャを理解する必要があります。ドキュメンテーションが存在するが古い場合、ドキュメンテーションがないより悪いです。なぜなら、積極的に誤解を招くからです。新しいエンジニアは間違った図に基づいてメンタルモデルを構築し、その前提をデバッグするのに何日も費やすことになります。

ドキュメンテーションがなければ、発見は暗黙知に頼ることになります。最も長く在籍しているエンジニアに質問することです。これはスケールせず、ボトルネックを作り、キーパーソンが退職すると完全に失敗します。

一貫性の問題

複数のチームを持つ組織では、各チームがそれぞれ異なる方法でアーキテクチャを文書化します。チームAはVisioを使用。チームBはMiroを使用。チームCにはASCIIアートのREADMEがある。チームDは全く文書化していない。組織のアーキテクチャの統一ビューがなく、一貫した表記法がなく、チーム横断の依存関係を理解する方法がありません。

AIはどのように方程式を変えるか

AIは上記の各問題に対処します。人間の関与を排除するのではなく、退屈でエラーの起きやすい部分を自動化し、人間の判断を増幅することによってです。

AI搭載アーキテクチャ発見

アーキテクチャドキュメンテーションにおけるAIの最も直接的な応用は自動発見です。手動でコードを読んで図を作成する代わりに、AIシステムにコードベースを指定すると、ドラフトのアーキテクチャモデルが生成されます。

Archylでの実際の動作は以下の通りです。

リポジトリ接続。 Gitリポジトリ（GitHub、GitLab、Bitbucket、またはAzure DevOps）を接続します。
コードスキャン。 システムがコードベースを走査し、ファイル構造、設定ファイル、エントリーポイント、依存関係グラフを特定します。
AI分析。 大規模言語モデルがコードをチャンクごとに分析し、以下を特定します。
- 各モジュールまたはサービスが担当するもの
- 使用されている技術とフレームワーク
- コードが統合する外部システム
- コンポーネント間の通信方法
C4モデル生成。 AIは発見した内容をC4モデル要素（システム、コンテナ、コンポーネント、コード要素、リレーションシップ）にマッピングします。
人間のレビュー。 生成されたモデルをレビューし、正確な要素を承認し、間違いを修正し、AIが推論できなかったコンテキストを追加します。

その結果、数週間ではなく数分で作成されるC4アーキテクチャモデルが得られます。完璧ではありません。AIはビジネスドメインや組織のコンテキストを理解しません。しかし、白紙のキャンバスよりも劇的に優れた出発点です。

AIが正しく認識するもの

AIはアーキテクチャドキュメンテーションの構造的な側面に優れています。

技術の検出。 LLMは数十の言語とエコシステムにわたるフレームワークパターン、ライブラリのイディオム、設定フォーマットを認識します。github.com/gofiber/fiber を含む go.mod ファイルは、Fiberフレームワークを使用するGoサービスを即座に識別します。next を含む package.json はNext.jsアプリケーションを識別します。

サービス境界の検出。 マイクロサービスアーキテクチャでは、AIはディレクトリ構造、Docker設定、デプロイメントマニフェストからサービス境界を確実に特定します。5つのサービスを含む docker-compose.yml は、AIに作業するための明確なトポロジーを提供します。

依存関係のマッピング。 Import文、APIクライアントライブラリ、設定ファイルは、サービス間および外部システムへの依存関係を明らかにします。すべてのSDKインポート、すべてのAPIベースURL、すべての接続文字列が手がかりです。

パターン認識。 AIは何百万ものコードベースで学習されています。MVCの構造、ヘキサゴナルアーキテクチャ、イベント駆動パターン、その他数十のアーキテクチャパターンを認識します。コードが確立された慣例に従っている場合、AIはそれらを迅速に特定します。

AIが間違えるもの

期待値を適切に設定するために、限界について正直であることが重要です。

ビジネスドメイン。 AIは processOrder() が存在することは教えてくれますが、あなたの特定のビジネスコンテキストにおける「注文の処理」が何を意味するかは教えてくれません。ドメイン固有の命名、カスタムワークフロー、ビジネスルールには人間の解釈が必要です。

非標準的なアーキテクチャ。 システムがカスタムプラグインフレームワーク、独自のビルドシステム、珍しいプロジェクト構造を使用している場合、AIは苦労する可能性があります。ReactアプリがReactアプリらしく見え、GoサービスがGoサービスらしく見えることを期待します。

ランタイム依存関係。 静的コード分析では、ランタイムにのみ存在する依存関係を検出できません。サイドカーコンテナ、サービスメッシュの設定、環境固有の統合、コードに表現されていないインフラなどです。

意図。 AIはコードが何をするかは説明できますが、なぜそのように書かれたかは説明できません。システムを形作ったアーキテクチャ上の意思決定、トレードオフ、制約はコード自体からは見えません。これがADR（Architecture Decision Records）が依然として不可欠な理由です。AIは構造を発見しますが、人間が意図を文書化します。

ドリフト検出：ドキュメンテーションの正直さを保つ

発見は作成の問題を解決します。ドリフト検出はメンテナンスの問題を解決します。

アーキテクチャドリフトとは、ドキュメンテーションが述べていることとコードが実際に行っていることの間のギャップです。名前が変更されたのに図では古い名前のままのサービス。廃止されたのにまだアクティブとして表示されているコンポーネント。アーキテクチャモデルに追加されなかった新しいマイクロサービスなどです。

自動ドリフト検出の仕組み

Archylのドリフト検出は軽量なアプローチを取ります。完全なAI発見パイプラインを再実行しません（それは遅くコストが高いでしょう）。代わりに、ターゲットを絞った検証を実行します。

システム: 文書化されたシステム名がリポジトリ名と一致するか？
コンテナ: 文書化されたコンテナがコードベース内の実際のディレクトリに対応するか？
コンポーネント: 文書化されたコンポーネントが親コンテナの存在を考慮して依然として有効か？
コード要素: 文書化された各コード要素のファイルパスがリポジトリに存在するか？
リレーションシップ: 文書化された各リレーションシップの両端が依然として有効か？

結果は0から100の間のドリフトスコアで、文書化されたアーキテクチャが現実と一致している割合を表します。95%のスコアはドキュメンテーションが高い精度であることを意味します。50%のスコアはドキュメンテーションの半分がフィクションであることを意味します。

ドリフトをアクション可能にする

スコアだけでは十分ではありません。Archylは何がドリフトしたかを正確に示す詳細な内訳を提供します。

コードベースには存在しないが文書化されているコンテナ
もはや存在しないファイルを参照するコード要素
ドリフトした要素に接続するリレーションシップ
コードベースに存在するが文書化されていない新しい要素

この内訳により、「ドキュメンテーションはおそらく古い」という漠然とした感覚が、修正すべき具体的でアクション可能なリストに変わります。

CI/CDでのドリフト

ドリフト検出の最も強力な応用は継続的インテグレーションです。Archylはプッシュごとにドリフトスコアを計算するGitHub Actionを提供しています。

- uses: archyl-com/actions/drift-score@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ secrets.ARCHYL_ORG_ID }}
    project-id: 'your-project-uuid'
    threshold: '70'

しきい値を設定すると、ドキュメンテーションの精度がそれを下回るとビルドが失敗します。これにより、アーキテクチャドキュメンテーションがテストと同様に扱われます。つまり、劣化を防ぐ品質ゲートです。

このアプローチを採用したチームは、ドキュメンテーションに対する考え方の根本的な変化を報告しています。後付けではなく、すべてのコミットでチェックされるファーストクラスの関心事になります。

MCP革命：アーキテクチャを理解するAIエージェント

Model Context Protocol（MCP）は、AIエージェントが外部ツールやデータソースと対話するためのオープンスタンダードです。ArchylのMCPサーバーは、アーキテクチャモデル全体（C4図、ADR、適合性ルール、ドリフトスコア）をMCP互換のあらゆるAIエージェントに公開します。

これにより新しいパラダイムが生まれます。アーキテクチャを認識するAIエージェントです。

仕組み

Claude Code、Cursor、その他のMCP互換AIコーディングアシスタントをArchylのMCPサーバーに接続して使用する場合：

エージェントは get_agent_context を呼び出して、プロジェクトの完全なC4モデル、ADR、適合性ルールを受け取ることができます。
コードを書く前に、エージェントは文書化されたアーキテクチャを理解します。どのサービスが存在し、どのように通信し、どの技術が使用され、どの意思決定がなされたか。
エージェントは get_drift_score をチェックして、ドキュメンテーションの信頼性を評価できます。
エージェントは特定のADRを読んで、特定のアーキテクチャの選択がなぜなされたかを理解できます。

なぜこれが重要か

アーキテクチャのコンテキストがなければ、AIコーディングエージェントは強力ですが盲目です。あなたのアーキテクチャ原則に違反し、望ましくない依存関係を導入し、別のサービスに既にある機能を複製する優れたコードを書くことができてしまいます。

MCPにより、エージェントは以下を認識します。

「このシステムはMongoDBではなくPostgreSQLを使用している。MongoDBのクエリではなくSQLクエリを生成すべきだ。」
「サービス間通信はHTTPコールではなくKafkaイベントを使用している。RESTリクエストではなくイベントをパブリッシュすべきだ。」
「チームはGraphQLに反対する決定をした（ADR-0019）。GraphQL実装を提案すべきではない。」
「アーキテクチャのドリフトスコアは45%だ。文書化された構造に頼る際は注意すべきだ。」

これにより、AIエージェントは単なるコードジェネレーターから、アーキテクチャを認識するコラボレーターに変わります。

適合性ルール

パッシブなコンテキスト以外にも、Archylはアーキテクチャの制約を定義する適合性ルールをサポートしています。

「フロントエンドコンテナはデータベースと直接通信してはならない」
「すべてのサービス間通信はAPI Gatewayを経由する必要がある」
「すべての新しいサービスには関連するADRが必要」

AIエージェントはMCPを通じてこれらのルールを読み取り、生成するコードが準拠していることを確認できます。これは、AI支援開発とともにスケールするアーキテクチャガバナンスです。

現実世界での影響

AI搭載ドキュメンテーション導入前

AI支援なしの典型的なシナリオ：

新しいエンジニアがチームに加わる
コードを読み、質問し、メンタルモデルを構築するのに2〜3週間かける
他の誰にも役立たない個人ノートを作成する
アーキテクチャ図は8ヶ月前に最後に更新され、40%が間違っている
どのADRがまだ関連性があるか誰も知らない
コンテキストが失われているため、すべてのアーキテクチャ議論がゼロから始まる

AI搭載ドキュメンテーション導入後

AI搭載ドキュメンテーションでの同じシナリオ：

新しいエンジニアがArchylを開き、現在のC4モデルを見る（ドリフトスコア：92%）
システムコンテキストからコンテナ、コンポーネントへとナビゲートする
複雑なサービスをクリックして、主要な意思決定を説明するリンクされたADRを読む
アーキテクチャチャットを使って質問する：「注文サービスは決済サービスとどのように通信しますか？」
数週間ではなく数日でコードの貢献を開始する
コードを書くAIエージェントが文書化されたアーキテクチャと意思決定を尊重する

違いは微妙なものではありません。暗黙知と組織的知識の違いです。負担としてのドキュメンテーションと資産としてのドキュメンテーションの違いです。

AIアーキテクチャドキュメンテーションの未来

まだ初期段階です。AI搭載アーキテクチャドキュメンテーションの今後の方向性は以下の通りです。

継続的発見

現在の発見は特定時点の操作です。実行し、結果をレビューし、先に進みます。将来の発見は継続的になります。コードベースの変更を監視し、リアルタイムでアーキテクチャモデルの更新を提案します。新しいサービスを追加するPRをマージすると、システムがそれを検出してC4モデルへの追加を提案します。

振る舞い分析

現在のAI分析は構造的です。コードに何が存在するかを理解します。将来の分析は振る舞いを理解するようになります。コンポーネントがランタイムでどのように相互作用するか、データがシステムをどのように流れるか、エラーがどのように伝播するかです。これにより、静的分析だけでなく、本番トラフィックから生成される動的な図が可能になります。

リポジトリ横断のインテリジェンス

ほとんどの組織は複数のリポジトリにまたがるアーキテクチャを持っています。将来のAI発見はリポジトリ横断の依存関係を理解するようになります。リポジトリAのこのサービスがリポジトリBのあのサービスを呼び出し、それがリポジトリCで管理されるこのデータベースに書き込む。組織全体にわたる統一アーキテクチャモデルです。

自己修復ドキュメンテーション

究極の目標は、自らを修正するドキュメンテーションです。ドリフトが検出されると、AIが更新を生成し、修正されたモデルを含むプルリクエストを作成し、人間の承認を求めます。人間の役割はドキュメンテーションの作成からAI提案の更新のレビューへと移行し、はるかに軽い負担になります。

アーキテクチャを認識するコード生成

AIコーディングエージェントがより高性能になるにつれ、アーキテクチャの認識はクリティカルになります。アーキテクチャを理解するエージェントは以下が可能です。

確立されたパターンに従うコードを生成する
アーキテクチャの目標に沿ったリファクタリングを提案する
提案された変更がドリフトを増加させる場合に警告する
コード変更時にアーキテクチャモデルを自動更新する

始め方

すべてを一度に採用する必要はありません。以下は実践的な段階です。

フェーズ1：発見（初日）

リポジトリをArchylに接続し、AI発見を実行します。生成されたC4モデルをレビューします。明らかな間違いを修正します。これで、おそらく70〜80%の精度のベースラインアーキテクチャモデルが得られます。

フェーズ2：充実化（1週目）

AIが発見できないコンテキストを追加します。主要な意思決定のためのADR、重要なワークフローのドキュメンテーション、アーキテクチャ制約のための適合性ルール。ADRを影響するC4要素にリンクします。

フェーズ3：ドリフト検出（2週目）

ドリフトスコアGitHub Actionを設定します。ベースラインスコアを確立し、しきい値を設定します。プッシュごとにドリフトの監視を開始します。

フェーズ4：MCP統合（3週目）

ArchylのMCPサーバーをAIコーディングツールに接続します。エージェントにアーキテクチャのコンテキストを提供します。アーキテクチャを尊重するコードが生成されるのを確認してください。

フェーズ5：ガバナンス（継続的）

適合性ルールを定義します。ドリフトの傾向を監視します。ADRを四半期ごとにレビュー・更新します。アーキテクチャドキュメンテーションは一度きりのプロジェクトではなく、継続的にメンテナンスされる資産になります。

アーキテクチャドキュメンテーションの未来は、より良い図を描くことではありません。ドキュメンテーションが自ら作成し、自らをメンテナンスし、人間とAIエージェントの両方にアーキテクチャの真実の共有ソースとして機能するシステムを構築することです。

今日からAI搭載アーキテクチャドキュメンテーションを始めましょう。Archylを無料でお試しください -- リポジトリを接続し、数分でアーキテクチャが発見されるのを確認してください。詳細はこちら: AI搭載の発見：仕組み | アーキテクチャドリフトスコア | MCPサーバー：アーキテクチャと対話する。

AI搭載アーキテクチャドキュメンテーション：未来はここにある - Archyl Blog