ハクソク

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

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

2026年3月22日原文(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年この分野にいるけど、こういう図が役に立った回数は指で数えられるくらい少ないよ。むしろ、何かの役員が見たいって言ったから作られたのに、その後一度も更新されなかったケースの方が多い。

Hacker Newsで議論の続きを見る