ハクソク

世界を動かす技術を、日本語で。

システムアーキテクチャ図を作成する際に避けるべき一般的なミス

46日前原文(ilograph.com)

概要

  • システムアーキテクチャ図のよくある7つの追加ミスを解説
  • リソース名の未記載や未接続リソースなどの具体例を紹介
  • 「マスター図」の危険性やアニメーションの無意味さを指摘
  • ファントラップやAI自動生成図の限界についても説明
  • 各ミスの回避策と改善例を簡潔にまとめ

システムアーキテクチャ図で犯しがちな7つの追加ミス

  • リソース名未記載

    • リソースをアイコンやタイプ名のみで表記し、 固有名詞 を記載しないミス
    • タイプだけでは リソースの役割や違い が分かりにくい
    • アイコンでタイプを示す場合は、 名前を明記 することで識別性向上
    • 例：「Orders Table」「Results Bucket」など、 名前＋タイプ の併記が推奨

  • 未接続リソース

    • 図中で他のリソースと 何の関係も持たない孤立リソース を配置するミス
    • 例：Amazon Route 53が他リソースと 未接続 で役割不明
    • システム構成図は リソース間の関連性 を示すのが目的
    • 無理に全要素を入れず、 複数図に分割 するのが有効

  • 「マスター図」の作成

    • 全要素を1枚に詰め込む「 マスター図」の作成は 情報過多 で逆効果
    • 例：Ilographのバックエンド図で 依存関係・DNS・CDNなど を全て一括表示
    • 視点ごと に図を分割し、 ストーリー性 を持たせるのが効果的
    • モデルベース図なら 複数視点でリソース共有 も可能

  • コンベアベルト症候群

    • リソース間の実際の 往復や複雑なやり取り を省略し、 一方向フロー のみを描くミス
    • 経験の浅い閲覧者に 誤解を与える 危険性
    • 解決策は シーケンス図 （UML等）を用い、 詳細なやり取り を明示

  • 無意味なアニメーション

    • 技術的価値のない 派手なアニメーション や 動く矢印 を多用
    • 主にマーケティング目的で使われ、 本質的な情報は追加されない
    • 技術資料では 静的で分かりやすい図 が最適
    • 不要なアニメーションは避ける ことが重要

  • ファントラップ

    • 中間リソース（例：メッセージブローカー）で 個別の関係性が消失 する現象
    • 例：全ての通信が1つのブローカーに集約され、 端点間の具体的な関係が不明
    • 対策は 中間リソース内に詳細な要素（例：トピック）を追加 し、 個別経路を明示
    • 追加リソースが難しい場合は 他の解決法 も検討

  • AIによる図の自動生成への過信

    • AIは ホワイトボード的な支援 は可能だが、 ソースコードからの自動図生成 は精度が低い
    • 生成図は 曖昧・誤情報・上記のミス を多く含む傾向
    • 原因は 学習データ不足・コード解析の困難さ・選択判断の未熟さ
    • 現状では 人間による詳細な設計・図作成が不可欠

まとめ

  • システムアーキテクチャ図作成時は リソース名記載・接続性・情報整理 を徹底
  • 一図完結主義や装飾重視 を避け、 複数視点や適切な図式 を活用
  • AIの活用は補助的に留め、 最終的な品質管理は人間が担う べき
  • 詳細質問や意見は LinkedInまたはメール（billy@ilograph.com） にて受付

Hackerたちの意見

いくつかのコメント:

「リソース名にタイプのサフィックスを追加するだけで済むこともある（例: 注文テーブル、結果バケット）。名前にタイプをエンコードするのはやめよう。」 それに、名前が本当に必要だとはあまり思わないな。 「マスター図を作る」 こういう図は役に立つと思うけど、各トップレベルの「ボックス」にすべてのサブコンポーネントを含める必要はないよね。

└

「名前にタイプをエンコードするのはやめよう。」 なんで？ハンガリアン記法は行き過ぎかもしれないけど、単語が過剰に使われる場合はタイプをエンコードするのが役立つこともあるよ（例: 画像ファイル、画像テーブル、画像バケット）。

└

名前が本当に必要だとはあまり思わないな。アイコンだけの図が欲しいの？それでも、各アイコンの意味を説明する凡例がどこかに必要になるよ。そうしないと、図を読む人数と同じだけ解釈が生まれちゃうからね。それに、最初の画像は実質的に役に立たないと思う。リソースコンポーネントを並べるだけじゃ、システムの動作と結びつける価値がほとんどないから、結局その図は大きな文脈の中でしか理解できない。通常、図はそういう使い方をされないから、議論のメインの焦点になっちゃうんだよね。

図はコミュニケーションツールで、ターゲットとゴールを意識して作るのが一番だよ。C4フレームワークは、複数の抽象レベルや異なるタイプの視聴者に対応するのに良いと思う。ビジネスの役員は、システムをデバッグしている人が必要とするような詳細は求めていないからね。

一番よく見る間違いは、矢印が何を表しているのか合意が取れていないことだね。A-(顧客データ)->Bは、AがBにデータを要求しているのか、Aが顧客データをBに送っているのか？もちろん、シーケンス図では制御とデータが異なる方向に流れるときに2つの矢印で明確に示されるけど、たくさんの図は「昔ながらのボックスと矢印」タイプのものだからね。

└

高レベルの図について話していると思うけど、A --> BはAが何らかの形でBを「使っている」って意味だと思っている。これで十分だよ。

└

だからC4モデルはインタラクションに動詞を使ってラベルを付けることを強調してるんだよ。（例: 「データを読み書きする」、「レポートを送る」など）。この記事の図のほとんどは、実際にはこの点でひどいと思う。

└

僕がうまくいった解決策は、各矢印に色を付けて、図の左上にその色が何を表しているかを説明する凡例を追加することだよ。こうすることで、色が制御やデータ、時にはその矢印を実装することが期待されるチームを示すこともできる。特に、クロスチームの会議では、各グループが自分たちに最も影響を与える部分に集中できて、仮定や仕様の不足に対して的確なフィードバックを与えるのに役立つんだ。

└

そうそう、制限されたネットワークシステムからデータレイクにデータが流れる図を見たとき、まさにそんな問題があったよ。データはそのシステムによって生成されて所有されていて、レイクには二次的なコピーがあるんだけど、物理的にはレイクが接続を開いてデータを引っ張る形になってる。これがどういうわけか禁止されていて、ファイアウォールの人たちと数ヶ月も戦ってた。フォーチュン50は楽しいね。

└

実際には3つ目があるんだよね：ビルド時の依存関係。制御：オブジェクト/モジュール/関数Aがオブジェクト/モジュール/関数Bを呼び出す。データ：その呼び出しはデータをプッシュしたりプルしたりできる。ビルド依存関係：呼び出しは直接（AがBに依存）か、インターフェース/コールバックなどを介した間接的なもの（AとBがそのインターフェースに依存）になる。理想的には、すべての設計文書にはこの3つが別々の図として含まれているべきなんだ。

└

うん、別々のシーケンス図が必要だね。

これは彼らのサービスの宣伝に過ぎないね。20年この分野にいるけど、こういう図が役に立った回数は指で数えられるくらい少ないよ。むしろ、何かの役員が見たいって言ったから作られたのに、その後一度も更新されなかったケースの方が多い。

└

完璧な図を追い求めるのは、自己欺瞞の運動になりがちだよね。インフラが変わった瞬間、描いた図は間違いになるから。もっと厄介なのは、その図が組織内で公式化されて、誰もそれが現実から逸脱していることに気づかないまま何年も経つこと。だから、部族的な知識が公式のチャートを毎回上回るんだ。変なことに、実際に何かを作っている人がいる場合、重要な図はホワイトボードや生きたドキュメントに残ることが多い。コンプライアンス監査やVPの見栄のために作られた洗練されたVisioのゴミよりも早く劣化するものは少ないよ。

一番のミスは、自分の聴衆を知らないことだよ。図はマーケティング用？営業提案用？製品を使うビジネスパーソン用？技術的な仲間用？これが分からないと、適切な詳細レベルがあるかどうかも分からない。

└

このスレッドの中で過小評価されているコメントだね。普遍的な抽象やパターンについての主張がたくさんあるけど、それが普遍的じゃないってこと。 （もちろん、この洞察はあらゆる種類の文書コミュニケーション、図や文章に当てはまるよね…）

わからないけど、システムアーキテクチャの図は見た目がかっこよくて情報があるように感じるけど、実際にはプロジェクトに取り組むのに役立つとは思わないな。この記事のミス#3、詰め込みすぎるのもその一因だと思う。だから、https://www.jerf.org/iri/post/2025/on_layers_and_boxes_and_l... の意見は面白いよね。図にリンクを入れて、目次として機能させるっていうのが。これはプロジェクトに取り組む必要がある人にとって最も役立つと思う。同様に、https://haskellforall.com/2026/02/browse-code-by-meaning ではリポジトリの中身をどう見せるかを問うてるけど、ファイルツリーがベストじゃないかもしれないし、リンク付きの図が目次として答えになるかも。実際に言うと、どのツールがどんなコンテキストでも見栄えのいいリンクを簡単に作れるのかは分からないけど、例えばmermaidはGitHubでは表示されるけどテキストエディタではそうじゃないかもしれない。もちろん、他の目的のためには図を自由に描いてもいいけどね。前に同僚がすごく詳細なマスターダイアグラムを描いてて、50〜100個くらいの項目があったんだけど、上司が赤を全部別の色に変えたら、政府の高官たちが感心したって言われた。でも、開発者を方向付ける目的には、リンク付きの目次の方が良さそうだね。

└

わからないけど、システムアーキテクチャの図は見た目がかっこよくて情報があるように感じるけど、実際にはプロジェクトに取り組むのに役立つとは思わないな。タイトルに対する僕の反応は、図を作ろうとすること自体がミスだってことだった。もしそれを文章で説明できないなら、シンプルにしなきゃ。

うちの職場で図を作る担当として、この話題についてのあらゆる議論を本当に感謝してる。図の目的を知ることは、プロセスの中で非常に過小評価されている部分なんだ。サービスフローチャート？システムアーキテクチャ？高レベルのシステム概要？それとも実行可能で追従可能なフローチャート？エンジニアとしては、すべての情報を図に入れたくなっちゃうんだよね、最大限に「正しい」ものにしたくて。でも、それは決して正しい選択ではない。何が含まれているのか、含まれていないのか、そしてその理由をどうやって明確にするか、毎回苦労してる。もっとこの話について議論したいな。

└

あなたが意見に興味があると言ったから、ドキュメント（特に図）で最も過小評価されている側面の一つは、文書の最初にステークホルダーを定義することだよ。これが、理解できないフラストレーションを抱えたユーザーと、制限を理解している幸せなユーザーの違いになる。これに関連して、最良の図は、しばしばチーム間のコミュニケーションラインに沿った境界を持っている。これがコンウェイの法則だよ。そしてその理由は、ほとんどの場合、人々が図を使って「自分たち」がどこにフィットするのかを把握するためだから。これについては経験則しかないけど、私が作った最も役立つ持続的な図は、1) 特定のステークホルダーを定義（そしてそれに従う）し、2) グループやチームによって区切られているものなんだ。

└

複数の相互リンクされた図？異なるレベルや視点からのたくさんの図があって、異なる質問に答えるために設計されてるの？

私にとって一番の問題は、すべてを最新の状態に保つことなんだ。そのために、PlantUMLやMermaidのようなテキストから図に変換するツールに完全に移行したよ。彼らは不完全だけど、図がコードと同じコミット（またはマージリクエスト）で更新されることを強制できるからね。AIツールもそれらと一緒にうまく機能するし。ただ、PlantUMLやMermaidには時々イライラさせられる。図を人間が読みやすい形にフォーマットする力が足りないんだよね。もっと複雑な図に関して、他の人はどうしてるのか気になるな。

└

C4-PlantUMLを試したことある？実際、うまくいかないときにレイアウトを手動で調整する機能があるよ。

よく見る間違いがあって、すごく寂しいんだけど：単純なフロントエンド（アーキテクチャコンポーネント）がバックエンド（これもアーキテクチャコンポーネント）と話してるってこと。いつも「違うよ、みんな、静的ウェブサーバーはどこにも何も送ってない、ただ静的ファイルを提供してるだけだよ」って説明するのに余計な努力をしなきゃいけなかった。

私は常に簡略化されたUMLスタイルを使ってるよ、システム図でもね。OmniGraffleは私にとって欠かせないツールなんだ。矢印や線の種類が何を意味するかをちゃんと説明するよ。私は慣習に頼らない、だって「純粋な」UMLはほとんどの人が知らないものだから、基本的にヒエログリフを書いてるようなもんだ。