はじめに
私はクラウドサービスのプロダクトオーナーをしています。
プロダクトオーナーはプロダクトの抱えるリスクについてを上司やチーム外の関連部署に報告、承認を得ながらリリースする場面があります。そしてプロダクトが抱える代表的なリスクとしてはセキュリティですが、そのリスクを説明するためにはネットワーク構成図が求められます。
もちろんプロダクトに実施するすべての変更のたびに、ネットワーク構成図について更新すると決め、都度メンテしていくのがベストではあります。しかしながら、この手の説明が求められる場面は年1回程度と少なく、そして作っている時と使われるときに大きな時間差があります。従って、どうせ読まれないと思ってメンテされにくかったり、いざ報告するときに適した形ではなく作り直しになることもあります。
ドキュメントを作るコスト自体も無視できるものではなく、可能な限りプロダクトのアップデートに使いたいものです。そんな昨今、AIは日増しにできることが増えており、どうにか自動で作ってもらえないかと思ったのが本記事の背景です。
実現したい体験
下記のような流れで日々の開発が回ればいいと思いました。
- プロダクトオーナーがバックログを起票
- エンジニアがバックログを解釈、設計を明示的にor頭の中で行う
- 設計に従って実装・テストする
- バックログによる作業内容をGitHubにコミット
- プルリクエストによって他エンジニアからレビューを受ける
- Staging環境へのブランチにマージされ、リリースプロセスに入る
このとき、手順3と5で設計に対してフィードバックがかかり、実態とドキュメントが乖離したり、メンテナンスする手間を感じたりするタイミングになります。なので、できればGitHubにコミットするごと、遅くともStaging環境へのマージまでには、ドキュメントに実態を反映したいと考えました。
今回やりたいこと
- Terraformやソースコードを解析
- 図表生成
例えばClaude CodeはGitHub Actionsの中でも使用できるので、自動化までは実施しないこととします。
使用する技術・ツール
- GitHub Actions
- Claude Code (Anthropic API)
- Terraform
- Mermaid図 / PlantUML / Diagrams.net
- Python / Node.js (解析スクリプト用)
一口に図を書くといっても、複数の出力方法があります。今まではmiroやDraw.ioなどで手書きすることが多かったのですが、AIで書くのはなんとなく難しそうですね（グラフィカルなので）。
お題
Amazon API Gateway HTTP API to AWS Lambda to RDS Proxy
RDS, Lambda, API Gatewayあたりをよく使うため、それをお題にしてみます。
リンク先からさらにジャンプするとアーキテクチャ図があります。それを正解とします
いろいろな出力方法を試してみる
まずはTerraform Graph + Graphviz
公式から提供されているのはありがたいものの、ちょっと物足りないというか、人が読んで把握するのは難しそうな感じがします。
Claude Code -> Mermaid
Claude Codeに「AWSアーキテクチャ図作って」と雑にお願いしたら出力してくれました。Terraform Graphの例より見やすいですし、グラフ自体も正しそうです。
正解の例ではログ出力ルートまでは書いていなかったので修正してもらいます。あとできればAWSアイコン使ってもらえないかも。
さらに詳細に要件を指定するとうまく書いてくれるように
何度か手直しを要求したら遜色ない図が出来上がりました。
要件として下記のように指定しました。
- シンプルなデータフローで書いてください。認証やログなどの詳細を省き、主要なデータの流れに焦点を当てます。これによりデータ全体の流れが把握しやすくするためです
- グラフィカルな表現にしてください。AWSの公式アイコンを使用して視覚的にわかりやすく表現します
- VPCおよびサブネット構成を明示してください。Public Subnet、Private Subnet内に配置を明示します。これによりインターネットとの接続性がわかりやすくなるためです
- 左から右へ書いてください。クライアントからデータベースまでの一連の流れを把握しやすくするためです
さらに切り口を追加
構成図を書くと一言で言っても、欲しい文脈は色々とあります。例えば「ちゃんとログを撮ってるのか？」という指摘に対応するためには、AWSリソースと、どのログが、どこに出力されているかを説明できると便利です。
そこで下記のように要件を設定し、システム構成図の下に追加するよう指示しました
- 上記システム構成図のシンプルなデータフローに追加して
- AWSのどのリソースに対するログが、どこに出力されているかを明示してください。それにより必要なログが漏れていないかを視覚的にチェックすることができます
すると、先ほどのワークフローをベースに、どのAWSリソースで、どのログを、どこに保存しているかを図示してくれるようになりました。
例えばよりセキュリティを重視した説明のために、認証認可に絞って関係図を出したりと、切り口を変えていろんな図を出し分けできるのが良いですね。
まとめ
ということで、シンプルなワークフローであれば、AIで必要十分なアーキテクチャ図を書けることがわかりました。一方で、システム全体の構成図のようなものをソースコードから書くのには工夫が必要そうです（網羅的になりすぎる）。そこは人間が人間に図を書いてもらうときに指示するように、どれくらいの粒度で書いて欲しいのかをもっと明確に指示する必要がありそうですね。
備考1
記事を書いているときに同じようなネタでより良いものを見つけてしまいました
https://zenn.dev/mixi/articles/3fa996617eacc6
備考2
システム構成図をDraw.ioで出力するようにお願いしてみました。
Draw.ioでもバッチリ書けましたし、見栄えもMermaidより良いですね。ただAWSリソース同士が無駄に曲がった直線で繋がっていたり、ブロック図の余白が気になる...
何度か指示してみたもののうまく直らず。やはりDraw.ioはキレイに描ける反面自由度が高すぎるのかもしれない。
Mermaidだとマークダウンで扱えて、他の情報と一緒に表示できるので、今のところはMermaidがよいように思う。ただ、ある程度以上の規模になってくるとMermaidも破綻してくるので、どこまでの粒度で書くかをよく考える必要がありそうである。