構成図は重要
新しく入ったシステムを理解するとき、最初に開くのは構成図だと思います。どこに入口があって、要求がどこを通って、データがどこに残るのか。文章で読めば数ページかかることが、1枚の図から、すばやく頭に入ります。
構成図が雄弁なのは、関係が形として見えるからです。箱の並びと線のつながりを目で追うだけで、依存の向きと深さが分かります。この速さは、文章では出せません。
人が図を描くと、3つのことが起こる
まずは、描き手によって読みやすさが変わります。同じシステムでも、人が変われば箱の並べ方も粒度も変わるからです。前任者の図を引き継いだ人が、まず自分の描き方に直すのは珍しくありません。
2つめは、結線の複雑さによる誤解です。要素が増えるほど線は交差します。交差が増えると、どの線がどこへ向かっているのかを目で追いにくく、誤解が生じます。
3つめは、コードの更新に追いつかないことです。デプロイのたびに構成は変わりますが、図は誰かが気づいたときだけ直ります。半年後に見た図が、いま動いているものと同じである保証はありません。
だから、コードから図を起こす取り組みがある
誰が起こしても同じ図になり、コードが変われば図も変わる。この考え方に立つ道具は、すでにいくつもあります。
| ツール | 描画元 |
|---|---|
| terraform graph | Terraformの定義から、依存関係のグラフをDOT形式で出します |
| TerraVision | Terraformのコードから構成図を描きます |
| InfraMap | Terraformのコード、または状態ファイルから構成図を描きます |
| IceShore | ADLによるユースケース定義（TerraformやCloudFormationなどのコードを内部参照）から図を起こします |
| cdk-dia | AWS CDKを合成した結果から図を起こします |
図そのものをテキストで書く道具もあります。PlantUML、Diagrams、Structurizrがそれで、図の記述を版管理に載せられます。ただしこちらは、インフラの定義から図が導かれるわけではありません。インフラを変えても、人が記述を書き直すまで図は変わりません。
IceShoreは正確さの先を目指している
コードから起こした図は、構造については正確です。どのリソースがどのリソースを呼んでいるかは、定義ファイルを読めば判定できます。
ただし一般的な構成図では、そのシステムが業務で何をしているか（ユースケース）までは読みきれません。
コードのどこにも「この経路が止まると受付の予約業務が止まる」とは書かれておらず、業務との関連づけは大抵、担当者の頭の中と、不完全な資料、会議録に埋もれているからです。
一方でIceShoreには、構成図にユースケースを取り入れる取り組みがあります。独自の定義言語「ADL（Architecture Description Language）」を使うことで、構成図にユースケースを注入しています。
そこには、誰が（アクター）、何を（リソース）、どのように使うか（ユースケース）という情報が記述されます。またリソースについては、ADLが既存のプロビジョニングコード（Terraform、CloudFormation、Azure Resource Manager、Google Cloud Deployment Manager、Alibaba Cloud ROS、Serverless Framework）を参照することで表現されます。よってそれらの構造を一から写しとる無駄はありません。構造の出どころは、いま動いているものを作ったそのファイルのままです。ADLが足すのは、その上に載せるユースケースです。
業務との関連づけを載せると、人もAIも影響範囲がたどれる
業務との関連づけが図に入っていると、「このデータベースを止めたら誰が困るか」に、図をたどるだけで答えが出ます。止まる経路を先頭まで遡れば、その業務影響と困る相手がわかります。
ひとつのリソースから、波及する業務と、その利用者数までたどれます。IceShoreに掲載された公開サンプル「Clivasoft 診療記録・予約システム」を、接続したAIが読んだ結果です。
AIに保守を任せるとき、この関連づけが役立つ
生成AIで開発が速くなり、手元のシステムが増えています。それを保守するには、AIの力が必要です。
その時、AIに既存のコードだけを渡しても足りません。既存コードから読み取れるのは構造までで、ユースケースはそこに書かれていないからです。AIに保守を任せるほど、既存コードでは読み切れない、システムと業務の関連性に関する情報を渡す必要が増します。
またバイブコーディング問題への一つの回答は、システムが肥大化する前に除却して、作り直すことなどと言われます。その時もまた、業務依存が不明瞭なままでは、簡単に除却も作り直しもできません。
ADLとは
IceShoreは有償ですが（無料プランがあり、1人で使う分には足りる）、それが使う構成図の宣言コード、ADL（Architecture Description Language）はオープンソースです。言語仕様とスキーマは、Reindeer Technology Pte. Ltd. がApache License 2.0で公開されています。
図の配置は自動
ADLに書くのは要素と関係だけで、座標を書く欄がありません。図の配置は描画アルゴリズムが決定します。
つまり、描き手によって図の見え方が変わることも、線の交差を人が手で整えることもありません。ドローツールで手間のかかる作業が、そもそも発生しません。
左のテキストが書くもので、右の図は自動で描かれます。公開サンプル「Nuvela ホスピタリティ予約プラットフォーム」の一部です。
ユースケースが、必須フィールド
ここが、システム構造だけを記述するツールとの違いです。先に挙げたツールはどれも、そのリソースが業務で何をしているかを書く欄を必須にしていません。ADLでは、その欄を省くと妥当なファイルになりません。
IceShoreのMCPを使えば、AIに書かせられる
IceShoreには、ADLの作成と登録をガイドするMCPがあります。お使いのAIを繋いで「システム構成図を書いて」というだけで、既存資料から簡単にADLが生成できます。
この時重要なポイントは、AIで記述できた内容は、AIによるシステム理解の投影という点です。出来上がった構成図をあなたが見てAIに補正させ、その結果をAIにフィードバックすれば、AIのシステム理解も深まります。
IceShore
https://iceshore.ai/?utm_source=qiita&utm_medium=referral&utm_campaign=launch2610&utm_content=a-p3-1
ADL文書中で宣言が必須なのは、6要素
宣言が必須なのは、reindeer、self、info、actors、resources、useCasesの6つです。（reindeerはADL仕様そのもののバージョンで、本執筆時点の公開サンプルでは「2.0.0」です。）
参照の形が決まっているので、AIが処理の流れを辿れる
要素どうしのつながりは、文字列の参照で表します。例えばユースケースA（Web閲覧）がアクターX（ゲスト）のリクエストで始まり、リソースP（データベース）へのデータ保存で終わるといった形です。
形が決まっているので、参照をたどる処理をAIが書けます。終点は参照の配列なので、どのトラフィックがどのリソースで終わるかを集計できます。
情報の機微も、必須の真偽値
infoTypeの定義は、confidentialとprivacyという2つの真偽値を必須で持ちます。各経路はこの定義を参照し、データが残る場合はstoredInfoTypeを別に指定します。
したがって、個人情報が流れる経路と、それが保管されている場所は、2つの参照をたどれば列挙できます。セキュリティ審査のたびに人が作り直していた一覧が、構成図から引けます。
差分を行単位でチェックできる
テキストなので、変更は行の差分で表示されます。書き出したADLをリポジトリに置けば、構成の変更も既存のコードと同じ手順でレビューできます。
ドローツールのファイルは、開いて見比べるまで何が変わったのか分かりません。ADLでは、変わった行だけが見えます。
ADLは仕様が公開されているので、ご自身のツールにも組み込める
定義スキーマはja/reindeer-schema_cds.jsonとen/reindeer-schema_cds.jsonの2本です。必須フィールドは両者で一致していて、違うのは説明文の言語です。
Apache License 2.0なので、社内の道具に組み込んでも、別のサービスから読み書きしても構いません。IceShoreとの契約は要りません。
実物を見る
IceShoreサイトで、サンプルの構成図を確認できます。
会員登録なしで開けるため、気軽に試せます。
なおIceShoreはシステム構成図の作成後、AIがシステム保守の質問に答える時にそれを読ませ、回答精度をあげることに価値を置いています。よってお使いのAIにMCPを繋ぎ、「構成図を見て保守回答して」という使い方まで確認すれば、IceShoreの真価がわかります。（もちろん、構成図をさくっと作成させるという用途でも使えますが）
お使いのAIを繋いで「診療記録のデータベースを止めたら誰が困るか」と聞けば、この記事で見た参照の連なりを、AIがたどって答えます。
以上です。
みなさまの開発ワークが少しでも充実するよう、ご参考になれば嬉しいです。