■ 1. 背景と取り組みの概要
- 取り組みの背景:
- 入社後、デプロイやE2Eテストなどリリース周りの改善検討を任された
- 複数のプロダクトが連携して動いている
- デプロイ単位と順序を決めるには、プロダクトをまたいだサービス間の依存関係を知る必要がある
- 愚直に調査すると全体像の把握に時間がかかる
- 従来のやり方:
- システム構成図やアーキテクチャ図を見て、気になる箇所をソースコードで確かめていた
- 今回の試み:
- 生成AIでシステム全体の構成図を描き、ドリルダウンや処理の流れの再生ができる図にした
- よかった点:
- 全体から入って必要な箇所だけ降りられるため、全体像を速くつかめた
- 構成と処理の流れを同じ画面で見られるため、処理の動きを掴みやすい
- ほしい図をほしいタイミングで足せて、気になった点をその場で質問できる
■ 2. C4モデルの概要
- C4モデルとは:
- Simon Brownが提唱した、ソフトウェアアーキテクチャを図で表すための考え方
- システムを4つの詳細度（レベル）に分け、レベルごとに別の図に描き分ける
- Level1 システムコンテキスト図:
- システムを1つの箱とし、利用者や外部システムとの関係を描く
- Level2 コンテナ図:
- システム内で動くアプリケーションやデータベースと、そのつながりを描く
- Level3 コンポーネント図:
- 1つのコンテナの中を主な部品と役割に分けて描く
- Level4 コード図:
- コンポーネントの実装をUMLのクラス図やER図などで描く
- 公式でも任意とされ、IDE等でその都度生成できるため長期利用のドキュメントには非推奨
- 今回もLevel3までにとどめた
- コンテナの意味:
- Dockerのコンテナとは別物
- WebアプリケーションやAPI、データベースなど、システムが動くために稼働が必要なアプリやデータストアを指す
- 地図アプリの縮尺変更に近い感覚:
- 日本地図から都道府県、市区町村へ降りるように、Level1で輪郭をつかみ気になる箇所だけ降りていける
- C4モデルの利点:
- 1枚の図に全部を詰め込まなくてよい
- 各図にはその縮尺で見るべきものだけが描かれ、システムのどこを見ているか見失いにくい
- 補助的な図:
- 処理の流れを描く動的図（Dynamic diagram）がある
- インフラへの配置を描くデプロイ図（Deployment diagram）などもある
■ 3. 動的アーキテクチャ図
- 定義:
- 静的な図で終わらせず、操作しながら行き来できるアーキテクチャ図を指す
- C4モデルの動的図とは別の言葉で、図そのものを操作できるという意味の「動的」
- 今回作成した2つの図:
- Level1からLevel3へドリルダウンできるアーキテクチャマップ
- Level2の図の上でユースケースごとの処理の流れを1ステップずつ再生できるコミュニケーション図
- 静的な図の限界:
- 細かく描けば全体が見えず、全体を描けば中身が分からない
- 処理の流れまでは載せきれない
- 操作できる図の利点:
- 全体の輪郭から入り、必要なタイミングで必要な詳細度まで降りていける
■ 4. ドリルダウン可能なC4モデル
- C4モデルの採用理由:
- もともと自分でもアーキテクチャを描くのによく使っていた
- 作図の進め方:
- 既存のC4モデル図はなかった
- アプリケーション、デプロイ設定、インフラの3リポジトリをClaude Codeに読ませた
- 一気にLevel3まで描かず、Level1を確認してからLevel2を足すように1段ずつ進めた
- 図を足しながら自分の理解も深めた
- Claude Opus 5.5の作図能力:
- レイアウトまでそのまま使える図が出てきた
- 従来の生成AIと比べ、図の作成能力がかなり向上した
- ほぼ手直し不要で、作図コストはほとんどかからなかった
- C4モデル図の効果:
- 構成の見通しがかなりよくなり、キャッチアップに適していた
- drawioファイルでの課題:
- 階層を降りるたびにファイルを開き直す必要があり、追いかけるのが大変だった
- 処理の流れは依然として見えなかった
- HTMLによるアーキテクチャマップ化:
- 詳細図のある要素をダブルクリックすると1つ下の階層に降りられる
- 箱を選ぶと、そのコンテナの目的や機能の説明が右側に表示される
- 説明は、システムに詳しくない人向けに、図から読み取れない目的や機能を中心にした
- C4モデルの縮尺を変えながら見る考え方が、そのまま画面操作になった
- 記事中の画像:
- すべて記事用に用意した架空のシステムのもので、細部は省いている
■ 5. アーキテクチャマップの作成方法
- プロンプトの工夫はほとんど不要:
- リポジトリを読ませてLevel1から順に作成する
- 以前は構成図作成用のSkillsを作って対応していたが、Opus 5.5ではSkillsなしで作成できる
- 初回のプロンプト:
- 3リポジトリを徹底的に参照し、Level1からLevel3までをdrawioで出力するよう依頼した
- 配置は描画して確かめながら作るよう指示した
- まずLevel1から作成させた
- 以降の進め方:
- Level1を確認しつつ、Level2、Level3（複雑なコンテナから）と1段ずつ依頼した
- 最後に、各レベルを辿れて箱選択で説明を見られるHTMLの作成を依頼した
■ 6. コンテナ図を使ったコミュニケーション図
- 目的:
- Level2の図の上にユースケースごとの処理の流れを重ね、システムの動きを知る
- 機能:
- 手順のクリックまたは「順に再生」で、その手順の矢印と説明が図の上に出る
- 関係するコンテナだけが濃く表示される
- 同期呼び出しと非同期（キュー・イベント・定期実行）を線の種類で見分けられる
- 背景:
- ユーザーには1回の操作でも、裏では複数のコンテナをまたぎ多くのステップを通る
- シーケンス図との比較:
- シーケンス図では、そのやりとりがシステム全体のどこで起きているかが見えにくい
- Level2の図の上で矢印を動かすと、構成の中を処理が流れる様子がそのまま見える
- 構成と動きを同じ画面で見られる点が最大のポイント
- 再生例:
- 架空システムの「画像を添付する」ユースケース
- ブラウザから直接ストレージに上げた画像を、キュー経由でワーカーがサムネイル化するまでを追える
- ユースケース単位にした利点:
- 機能を把握しながらアーキテクチャや実装を同時に理解するのは難易度が高い
- ユーザー操作に対して裏でどう処理が流れるかが分かりやすい
- 使い方とコードを別々に追わずに済んだ
■ 7. コミュニケーション図の作成方法
- ユースケースの洗い出しも、リポジトリを調べて生成AIに任せた
- Level2の図の完成後、関係コンテナと手順の矢印を順番に再生できるHTMLの作成を指示した
■ 8. 動的図の多用と公式見解
- C4モデル公式の見解:
- 動的図は控えめに使うべきとしている
- 複雑なやりとりを要する興味深い、または繰り返し現れるパターンや機能に限定すべきとの立場
- 控えめにすべき理由の推測:
- 公式に理由の記載はない
- ユースケースごとに1枚ずつ描くため、手作業での作図と保守の手間が大きすぎるからと考える
- 生成AIによる解決:
- 作図を生成AIに任せられる
- プロダクトごとにユースケースの図を一通り作り、かなりの数になった
- キャッチアップ用途なら、この程度網羅してもよい
- ただし保守の手間はゼロにはならない
■ 9. 同じ発想のツール
- IcePanel:
- C4モデルのレベルをズームで行き来できる
- Flows機能で、図の上のユースケース手順を1ステップずつ進めて見られる
- 新メンバーのオンボーディングへの活用例も紹介されている
- Structurizr:
- C4モデルの作者が作ったツール
- 動的図を、関係を順に表示するアニメーションで見せられる
- 今回ツールを使わなかった理由:
- Claude Codeにコードから直接作らせた
- 生成AIの進化に頼る部分は大きいが、ほしい図をほしいタイミングでその場で足していける
■ 10. 必要に応じた図の追加
- 作成コストがほぼかからないため、ほしくなった時点で図を追加している
- インフラ構成図:
- AWS公式アイコンを使い、リソースとそのつながりを描いた図
- C4モデルの補助的な図であるデプロイ図に近い
- アカウント、VPC、サブネットの中にリソースを配置し、ネットワークのつながりも線で描いた
- デプロイ順序図:
- Level2の粒度で、どのコンテナをどの順番でデプロイするかを描いた図
- CIのジョブ依存関係やマイグレーション順序から順序制約を洗い出した
- 架空システムで、リポジトリから環境を作ってアプリを出すまでの順序を組み立てさせた
■ 11. 今後試したいこと
- ドリルダウンできるシーケンス図:
- コミュニケーション図の手順から、コンテナ内部の処理をシーケンス図で見に行く
- Level2の流れからLevel3の流れへ降りるイメージ
- C4モデルと連動したインフラ構成図:
- 現状インフラ構成図はC4モデルの図と別々になっている
- Level2のコンテナから、実際に動いているクラウドリソースへ移れるようにしたい
- 画面からドリルダウンできるデータモデル:
- 画面の項目から、それを返すAPI、保存先のテーブルへと降りていく
■ 12. まとめ
- 動的アーキテクチャ図の効果:
- 図を描いて終わりにせず、HTMLで操作可能にしたことで理解が進んだ
- 今後、図は読むものから触って確かめるものに変わっていく
- 理解負債:
- 生成AIでのコード作成の速さに理解が追いつかず、理解のコストを後払いにする状態を指す
- 理解負債をためない仕掛けづくりも大事
- 作図コストが下がり、あとから効率よく理解を追いつかせることも可能になった
- 図の鮮度維持:
- コードから描いた図はコードの変更で古くなる
- 定期更新、リポジトリ管理でのコード変更連動、必要時の作り直しといった選択肢がある
- チームの状況に合わせて選択すべき