Mermaidと作図キャンバス：Diagram as Codeが向く場面、向かない場面

エンジニアリングチームのツール論争で、これほど長く続くものはそう多くありません。すべての図をコードとして Mermaid で書き、プルリクエストでレビューしたい人がいます。一方で、ボックスを動かしながらシステムを見渡せるキャンバスを求める人もいます。どちらも正しいのですが、当てはまる図が違うのです。

このガイドでは、Mermaid と作図キャンバスを率直に比較します。それぞれの得意なこと、行き詰まるところ、よくあるケースの判断表、そして同じ小さなシステムを両方の方法で描いた例を紹介します。

Mermaid の得意なこと

Mermaid は数行のテキストを図に変えます。これには確かな利点があります。

• コードの隣に置ける。 Markdown ファイル内の図は、それが説明するコードと同じプルリクエストで変更され、レビュアーは差分を確認できます。
• エンジニアが普段使う場所で表示される。 GitHub と GitLab は Markdown ファイル、Issue、プルリクエスト内の Mermaid コードブロックを図として表示し、Notion や Obsidian などのツールも表示に対応しています。
• 追加のツールもアカウントも不要。 ファイルを編集できる人なら誰でも図を編集できます。
• シーケンス図が優秀。 4 つのサービス間のリクエストの流れなら、Mermaid のシーケンス構文にかなうものはなかなかありません。
• AI アシスタントがすらすら書ける。 どのチャットアシスタントに Mermaid のフローチャートを頼んでも、たいていは有効な構文が返ってきます。

Mermaid の苦手なこと

• レイアウトを制御できない。 Mermaid はノードを自動で配置します。エッジを 1 本足すだけで図全体が組み変わることがあり、ノードが数十個を超えると読みにくくなります。
• テキストの差分では見た目の変化がわからない。 プルリクエストの 1 行の変更で図の半分が動くことがあっても、レビュアーに見えるのはその 1 行だけです。
• インフラを表す語彙が乏しい。 フローチャートの図形は汎用的です。新しいアーキテクチャ図や C4 図の種類もありますが、フローチャートやシーケンス図ほど成熟していません。
• エンジニア以外はほとんど編集しない。 プロダクトマネージャー、デザイナー、サポートチームは結果を読めても、ソースを変更することはまずありません。
• ライブで共有するセッションがない。 テキストは各自のエディタで編集します。カーソルも、ライブレビューもなく、変更が反映される瞬間を見ている人もいません。

キャンバスの得意なこと

• レイアウトを自分で決められる。 位置そのものが意味を持ちます。信頼境界の線引き、左から右へ流れるリクエスト、中央に集まったクラスターなどです。
• 型付きノードとフレーム。 Archboard のようなキャンバスでは、Kubernetes の Service や C4 のコンテナはポート付きのノードであり、namespace や VPC は中身を収めるフレームです。
• 誰でも編集できる。 リポジトリを開かない人でも、ラベルを直したりメモを追加したりできます。
• ライブでの共同編集と共有。 複数の人と AI エージェントがカーソルを表示しながら一緒に編集でき、ライブリンクや埋め込みを使えば、読む人は常に最新版を見られます。

キャンバスの苦手なこと

• 更新をワークフローに組み込まないと、コードから乖離する。 キャンバスはデフォルトではプルリクエストに含まれません。
• 中身の見えない形式がある。 PNG や独自形式のファイルは、差分を取ることも生成することもできません。Archboard は JSON エクスポートと公開済みの JSON Schema でこれを緩和していますが、それでも JSON ドキュメントは 10 行の Markdown ブロックとは別物です。
• ツールが必要。 閲覧者はアカウントなしで共有リンクを見られますが、編集者にはアカウントが必要です。

使い分けの判断表

パターンはこうです。図が 1 つの変更に属し、コードの中に置かれるなら Mermaid が勝ちます。図がチームに属し、個々の変更よりも長く生き続けるならキャンバスが勝ちます。

同じシステムを両方で描く

Mermaid で書いた小さなシステムです。

flowchart LR
  user([Customer]) -->|HTTPS| web
  subgraph shop [Online shop]
    web[Web app] -->|JSON| api[Orders API]
    api -->|SQL| db[(Orders DB)]
    api -->|OrderPlaced| q[[order-events]]
    q --> worker[Email worker]
  end
  worker -->|SMTP| mail[Email provider]

読みやすく、差分もきれいで、GitHub でも表示されます。次に、同じフローチャートをキャンバスで描きます。このフローチャートを、Mermaid の ID とノードタイプの対応付けと一緒に、MCP で Archboard に接続した AI エージェントに渡しました。user は C4 の人物、web、api、worker は C4 のコンテナ、db は Postgres、q はトピック、mail は外部システムです。エージェントは 1 ステップで図を描き、2 つ目のステップで 2 段に並べました。

subgraph はフレームに、ノードはポート付きの型付きノードになりました。これを出発点に、ほかの図と同じように配置を整え、注釈を加え、共有できます。

意図して両方を使い分ける

多くのチームで機能する分担は次のとおりです。

1. 変更に属する図には Mermaid。 設計ドキュメントやプルリクエストのシーケンス図、コードの隣のステートマシン、README の小さなフローチャート。
2. チームに属する図にはキャンバス。 システム概要、インフラ、セキュリティレビュー、オンボーディング。
3. 両者をつなぐ。 すでに Mermaid があるなら、そこから始めましょう。MCP で Archboard に接続したエージェントは、Mermaid のフローチャートを実際のノードタイプを使ったキャンバスの図に変換できます。コードと一緒にレビューしたいときはキャンバスを JSON としてリポジトリにエクスポートし、README からライブの図にリンクします。

よくある質問

Archboard のエディタに Mermaid を貼り付けられますか？ 現時点では直接はできません。MCP で接続した AI エージェントなら、subgraph を含む Mermaid のフローチャートを、実際のノードタイプを使ったキャンバスの図として描けます。シーケンス図など、ほかの種類の Mermaid 図は変換されません。

キャンバスの図はプルリクエストに表示されますか？ そのままでは表示されません。コードと一緒にレビューしたい場合は JSON か SVG としてリポジトリにエクスポートするか、プルリクエストからライブの図にリンクしてください。

Diagram as Code のほうが常に最新ですか？ 誰かが更新すれば、の話です。誰も触らない Mermaid ブロックは、キャンバスと同じ速さで古くなります。違いは、それを更新すべき変更のすぐ近くにあることです。

PlantUML や Structurizr はどうですか？ トレードオフは同じです。PlantUML は UML とシーケンス図に強く、Structurizr は C4 モデルをコードとして書くために作られています。誰が図を編集するのか、どれだけ長く使い続けるのかで選んでください。

AI アシスタントが扱いやすいのはどちらですか？ どちらもです。アシスタントは Mermaid をすらすら書けますし、MCP を通じてエージェントがキャンバスを直接編集することもできます。キャンバスでは、変更がライブで見え、元に戻すこともできます。

無料で始める — 1 シート、クレジットカード不要。