動的アーキテクチャ図のすすめ

こんにちは、リチェルカのソフトウェアエンジニアのもっち(X: mottyzzz)です。

この記事では、新しい環境でシステムの全体像をつかむためにやってみた「動的アーキテクチャ図」を紹介します。

入社して託されたテーマの1つが、デプロイやE2Eテストなど、システムのリリース周りの改善の検討でした。リチェルカには複数のプロダクトがあり、それぞれが連携しあって動いています。どの単位で、どの順番でデプロイすればいいかを決めるには、プロダクトをまたいで、どのサービスがどこに依存しているのかを知る必要があります。愚直に調査を進めると全体像をつかむのに時間がかかってしまいます。

これまでは、システム構成図やアーキテクチャ図を見て、気になったところをソースコードで確かめる、というのが経験上のやり方でした。今回は生成AIでシステム全体の構成図を描いて、ドリルダウンしたり処理の流れを再生したりできる図にしてみました。

やってみて、よかったことは3つです。

• 全体から入って、必要なところだけ降りていけるので、全体像をかなり速くつかめた
• 構成と処理の流れを同じ画面で見られるので、「処理の動き」を掴みやすい
• 生成AIによって、ほしい図をほしいタイミングで足していくことができ、気になったところはその場で質問などもできる

C4モデルとは

C4モデルは、Simon Brownさんが提唱した、ソフトウェアアーキテクチャを図で表すための考え方です。システムを4つの詳細度（レベル）に分けて、レベルごとに別の図に描き分けます。4つのレベルで描く対象は、Context、Container、Component、Codeです。

• Level1システムコンテキスト図（System Context diagram）: システムを1つの箱として、それを使う人や、つながる外部システムとの関係を描く
• Level2コンテナ図（Container diagram）: システムの中で動くアプリケーションやデータベースと、そのつながりを描く
• Level3コンポーネント図（Component diagram）: 1つのコンテナの中を、主な部品とその役割に分けて描く
• Level4コード図（Code diagram）: 1つのコンポーネントが、コードでどう実装されているかをUMLのクラス図やER図などで描く。公式でも「任意」とされていて、IDEなどのツールでその都度生成できるので、長く使うドキュメントにはおすすめされていない。今回もLevel3までにしている

ここでいう「コンテナ」は、Dockerのコンテナとは別の意味です。WebアプリケーションやAPI、データベースのように、システム全体が動くために動いている必要があるアプリケーションやデータストアを指します。

C4モデルで図を見ていくのは、地図アプリで縮尺を変えていく感覚に近いと思っています。日本地図から都道府県、市区町村へと降りていくように、Level1で全体の輪郭をつかんでから、気になるところだけLevel2、Level3へ降りていけます。

1枚の図に全部を詰め込まなくていいのが、C4モデルのいいところです。どの図も「その縮尺で見るべきもの」だけが描かれているので、いま自分がシステムのどのあたりを見ているのかを見失いにくい。

この4つのほかに、処理の流れを描く動的図（Dynamic diagram）や、インフラへの配置を描くデプロイ図（Deployment diagram）などの補助的な図も用意されています。

動的アーキテクチャ図とは

静的な図で終わらせずに、操作しながら行き来できるアーキテクチャ図のことを、この記事では「動的アーキテクチャ図」と呼んでいます。C4モデルの動的図とは別の言葉で、ここでの「動的」は、図そのものを操作できるという意味です。今回作ったのは、次の2つです。

• C4モデルの図をLevel1 → Level2 → Level3とドリルダウンできるアーキテクチャマップ
• Level2の図の上で、ユースケースごとの処理の流れを1ステップずつ再生できるコミュニケーション図

構成図を1枚描くだけだと、細かく描けば全体が見えなくなるし、全体を描けば中身が分からない。静的な図には、処理の流れまでは載せきれません。操作できる図にすると、全体の輪郭から入って、必要なタイミングで必要な詳細度まで降りていくことができます。

ドリルダウン可能なC4モデル

C4モデルは、もともと自分でもアーキテクチャを描くのによく使っていました。なので今回も、C4モデルで描いてみることにしました。

既存のC4モデルの構成図はなかったため、アプリケーション・デプロイ設定・インフラの3つのリポジトリをClaude Codeに読ませて、Level1から1段ずつ描いてもらいました。一気にLevel3まで描いたのではなく、まずLevel1を描いて確認し、そこにドリルダウンするようにLevel2を足していく。図を足しながら、自分の理解も深めていった感じです。

今回はClaude Opus 5.5で、レイアウトまでそのまま使える図が出てきました。これまでも生成AIにC4モデルを書いてもらってはいましたが、Opus 5.5では図の作成能力がかなり向上した印象です。ほぼ手で直さなくてよかったので、図を描くコストはほとんどかかっていません。

C4モデルの図ができて、構成の見通しはかなりよくなり、キャッチアップにはぴったりでした。いい感じ。

ただ、drawioのファイルが1枚ずつ出てきても、Level1からLevel3へ降りていくのにいちいちファイルを開き直すことになって、結局追いかけるのが大変でした。処理の流れも相変わらず見えません。

そこで、図をHTMLにして、Level1からLevel3までをドリルダウンして見られるアーキテクチャマップにしました。全体を表示した状態から、詳細図のある要素をダブルクリックすると1つ下の階層に降りられるような作りです。箱を選ぶと、そのコンテナが何のためにあって、どんな機能を持っているのか説明も表示できるようにしています。説明は、システムをあまり知らない人でも分かるように、図からは読み取れない目的や機能を中心にしてもらいました。

C4モデルの「縮尺を変えながら見る」という考え方が、そのまま画面の操作になった形です。

イメージはこんな感じです。Level1からダブルクリックでLevel2、Level3へ降りていき、箱を選ぶと右に説明が出ます。

※ 記事中の画像は、すべてこの記事のために用意した架空のシステムのものです。細かいところは省いています。

作成方法

プロンプト上の工夫はほとんどありません。リポジトリを読ませて、Level1から順に作成します。以前は構成図の作成用のSkillsなどを作ってなんとか作成していたのですが、Opus 5.5であればSkillsがなくてもここまで作成できるようになりました。

下記のリポジトリを徹底的に参照して、C4モデルで Level1 から Level3 までの図を描きたい。
<出力先> に drawio で出力してほしい。
配置は描画して確かめながら作ってほしい。

- <アプリケーションのリポジトリ>
- <デプロイ設定のリポジトリ>
- <インフラのリポジトリ>

まずは Level1 から作成してください。

あとはLevel1を見て確認しながら、「Level2も描いてください」「Level3を描いて。まずは中身が複雑なコンテナから」と1段ずつ進めました。最後に「Level1→Level2→Level3と辿れるHTMLを作って。箱を選択したときに説明を見られるようにしてほしい」と頼みました。

C4モデルのコンテナ図を使ったコミュニケーション図

もう1つ動的アーキテクチャ図にしたのが、Level2の図の上にユースケースごとの処理の流れを重ねるコミュニケーション図です。「動き」を知るためのものですね。

• 手順をクリックするか「順に再生」を押すと、その手順の矢印と説明が図の上に出る
• 関係するコンテナだけが濃く表示される
• 同期の呼び出しか非同期（キュー・イベント・定期実行）かを線の種類で見分けられる

ユーザーにとっては1回の操作でも、裏ではいくつものコンテナをまたいで、いくつものステップを通ります。

これをシーケンス図で描くこともできるんですが、それだと「このやりとりが、システム全体のどこで起きているのか」が見えにくくなります。Level2の図の上で矢印を動かすと、構成の中を処理が流れていく様子がそのまま見えます。構成と動きを同じ画面で見られるのが、このコミュニケーション図のポイントです。これが大きい。

下は、架空のシステムで「画像を添付する」を再生しているサンプルです。ブラウザから直接ストレージに上げた画像を、キューを通してワーカーがサムネイルにするまでを順に追えます。

ユースケースという単位にしたのも、良かったところです。プロダクトの機能や使い方もまだよく分かっていない状態で、機能を把握しながらアーキテクチャや実装まで同時に理解していくのは難易度があがります。ユースケースごとに処理とアーキテクチャを追えると、「ユーザーがこういう操作をすると、裏ではこう流れる」が分かりやすく、使い方とコードを別々に追わなくて済みました。

作成方法

ユースケースの洗い出しも、リポジトリを調べて生成AIにやってもらっています。Level2の図ができたあと、「Level2の図の上で、関係するコンテナと手順の矢印を順番に再生できるHTMLを作ってほしい」と指示しています。

公式は「控えめに」と言っているけど

実はC4モデルの公式サイトでは、こういう処理の流れを示す図（動的図）は控えめに使うべきだと書かれています。動的図のページの「多くのチームにおすすめか」という項目への答えが、こうです。

No, dynamic diagrams should be used sparingly to show interesting/recurring patterns or features that require a complicated set of interactions.

理由までは書かれていないんですが、ユースケースごとに1枚ずつ描くことになるので、手で描いて保守するには手間がかかりすぎるからだと思っています。

そこは生成AIに任せられます。実際、ユースケースはプロダクトごとに一通り図を作ったので、かなりの数になりました。キャッチアップ用なら、このくらい網羅してしまってもいいのかなと思っています。ただし、保守の手間はゼロにはなりません。

同じ発想のツール

• IcePanel: C4モデルのレベルをズームで行き来できる。Flowsという機能では、図の上でユースケースの手順を1ステップずつ進めて見られる。新しいメンバーのオンボーディングに使う例も紹介されている
• Structurizr: C4モデルの作者が作ったツール。動的図を、関係を順に表示するアニメーションで見せられる

今回はこういうツールを使わず、Claude Codeにコードから直接作ってもらいました。生成AIの進化に頼っているところは大きいのですが、ほしい図をほしいタイミングで作れるのがいいなと思っています。「Level3も描いて」「この流れを図の上で見たい」と思ったその場で、足していけます。

必要になった図を追加していく

作成するコストがほとんどかからないので、ほかの図も、ほしくなったそのタイミングで追加しています。

インフラ構成図

AWSの公式アイコンを使った、リソースとそのつながりの構成図です。C4モデルでいうと、補助的な図のデプロイ図に近いものです。実際に描いたものは、アカウントやVPC、サブネットの中にリソースを配置して、ネットワークのつながりも線で描いています。

デプロイ順序

C4モデルのLevel2の粒度で、どのコンテナをどの順番でデプロイするかを描いた図です。CIのジョブの依存関係やマイグレーションの順序から、順序の制約を洗い出しています。下の画像は、架空のシステムで、リポジトリから環境を作ってアプリを出すまでの順序を組み立ててもらったものです。

ほかにも試してみたいこと

まだやっていないんですが、同じような考え方で作れそうなものもあります。

• ドリルダウンできるシーケンス図: コミュニケーション図の手順から、そのコンテナの中で何が起きているかをシーケンス図で見に行く。Level2の流れからLevel3の流れへ降りていくイメージ
• C4モデルの図とつながったインフラ構成図: インフラ構成図は描いたものの、今はC4モデルの図とは別々。Level2のコンテナから、それが実際にどのクラウドのリソースで動いているかへ移れるようにしたい
• 画面からドリルダウンできるデータモデル: 画面の項目から、それを返しているAPI、保存しているテーブルへと降りていく

おわりに

この記事では「動的アーキテクチャ図」というものを紹介しました。図を描いて終わりにせず、HTMLにして動的アーキテクチャ図にしたことで理解が進みました。今後、図が「読むもの」から「触って確かめるもの」に変わっていくんじゃないかと感じました。

最近は「理解負債」という言葉も聞くようになりました。生成AIでコードを書く速さに理解が追いつかず、理解のコストを後払いにしてしまうことです。理解負債をためない仕掛けにしていくことも大事ですが、図を描くコストが下がったことで、あとから効率よく理解を追いつかせることもできるようになってきました。

コードから描いた図は、コードが変われば古くなります。定期的に更新する、リポジトリで管理してコードの変更に合わせて更新する、必要なタイミングで作り直す、といった選択肢はあるため、チームの状況に合わせて検討してください。

おわり。