技術記事に図を入れたいとき、どうしてますか。

自分はずっとこれが面倒で、「文章だけでなんとかできないか」と逃げてきた節があります。ただ、最近claude codeでドキュメントを書く機会が増えていて、処理フローの図がどうしても必要になりました。最初は Claude Code にSVGを生成してもらえば十分かと思っていたのですが、微修正のたびに座標を追う手間が気になって、他の方法も試してみることにしました。それがこの記事のきっかけです。

試したのは、Claude Code に頼んで手書きSVGを生成してもらう方法、Mermaid、そして最近知った Gridgram です。環境は macOS で、Claude Code と Gridgram CLI を使っています。

同じ図を3通りで描いて比べてみました。

お題：シンプルなWebリクエストのフロー

こういう図が欲しいとします。

ブラウザ → APIサーバー → DB
              ↓
           キャッシュ（Redisなど）

シンプルだけど、矢印の向きとラベルと分岐があって、よくある構成。これを3つの方法で描きます。

1. Claude Code に手書き SVG を生成してもらう

コードを書くのと同じノリで「こういう図のSVGを作って」と頼めば、それなりのものが出てきます。実際に生成されたものがこれです。

<svg xmlns="http://www.w3.org/2000/svg" width="520" height="300" viewBox="0 0 520 300">
  <defs>
    <marker id="arrow" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
      <polygon points="0 0, 10 3.5, 0 7" fill="#94a3b8"/>
    </marker>
  </defs>
  <rect width="520" height="300" fill="#f8fafc" rx="12"/>
  <!-- ブラウザ -->
  <rect x="30" y="110" width="100" height="40" rx="8" fill="#1e293b"/>
  <text x="80" y="135" text-anchor="middle" font-size="13" font-weight="600" fill="white" font-family="sans-serif">ブラウザ</text>
  <!-- APIサーバー -->
  <rect x="200" y="110" width="120" height="40" rx="8" fill="#1d4ed8"/>
  <text x="260" y="135" text-anchor="middle" font-size="13" font-weight="600" fill="white" font-family="sans-serif">APIサーバー</text>
  <!-- DB -->
  <rect x="390" y="110" width="100" height="40" rx="8" fill="#16a34a"/>
  <text x="440" y="135" text-anchor="middle" font-size="13" font-weight="600" fill="white" font-family="sans-serif">DB</text>
  <!-- キャッシュ -->
  <rect x="200" y="210" width="120" height="40" rx="8" fill="#d97706"/>
  <text x="260" y="235" text-anchor="middle" font-size="13" font-weight="600" fill="white" font-family="sans-serif">キャッシュ</text>
  <!-- 矢印 -->
  <line x1="130" y1="130" x2="198" y2="130" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
  <line x1="320" y1="130" x2="388" y2="130" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
  <line x1="260" y1="150" x2="260" y2="208" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrow)"/>
</svg>

画像にするとこうなります。

生成自体はすぐ出てきます。ただ、「ノード間の余白をもう少し広げたい」といった微修正をしようとすると、x="200" とか y="110" という数値を目で追って計算し直す羽目になります。図は出てくるけど、自分でメンテするのが地味につらい、という感じでした。

良いところ：色・サイズ・レイアウトを自由に指定できる。凝ったデザインにしたいときは最強。

しんどいところ：ちょっと変更したいだけでもSVGの座標を追わないといけない。再利用もしにくく、ファイルも大きくなりがち。

2. Mermaid

シンプル。コードが短くて読める。GitHubやZennでそのままレンダリングされるのも強みです。

試していて気になったのは、ノードの色を変えようとした瞬間に style browser fill:#1e293b みたいな記述が増えて、急に読みにくくなるところです。ちょっとしたスタイル変更で、宣言的だったコードが命令的に変わる感じがします。

良いところ：書くのが速い。テキストで管理できる。シーケンス図やクラス図など、図の種類が豊富。

しんどいところ：見た目の調整が途端に煩雑になる。アイコンはほぼ使えない。

3. Gridgram

Gridgram は、グリッドベースで図を描くツールです。CLIで .gg というDSLファイルを書くと、SVGやPNGに変換してくれます。

doc { cols: 3 }

icon :browser @A1 tabler/world        "ブラウザ"
icon :api     @B1 tabler/server       "APIサーバー"
icon :db      @C1 tabler/database     "DB"
icon :cache   @B2 tabler/database-cog "キャッシュ"

browser --> api   ""
api     --> db    ""
api     --> cache ""

画像にするとこうなります。

最初に Claude Code が生成した .gg ファイルで構文エラーが出ました。doc { } のブロックは JSON5 形式なので、プロパティの間にカンマが必要なのですが、それを忘れて invalid character というエラーになっていました。Claude Code がエラーログを読んで自力で直しましたが、その間こちらは何が起きているのかよく分からず眺めていました。結局は doc {} 内のプロパティ間にカンマが必要だった、という単純な話でした。

慣れてからは、「こういう図を作って」と Claude Code に頼むと .gg ファイルを出力してくれて、ほぼそのまま動くのが快適でした。自分は「図の微修正のしやすさ」と「LLMに頼んで直しやすいか」を重視していたので、今の用途には一番合っている気がしています。

自分は箱だけの図だと後から見返したときに意味を取り違えがちなんですが、アイコンがあるだけでだいぶ助かっています。Tabler というアイコンセットが大量に使えるので、ノードの意味を視覚的に補足できるのが地味に便利です。

良いところ：グリッドで位置を指定するので、レイアウトが直感的。アイコンが豊富でノードに意味が乗る。.gg ファイルはテキストなので管理しやすい。LLMとの相性が良い。

しんどいところ：まだ情報が少ない。構文エラーのメッセージが慣れるまで少し読みにくい。

Gridgramの導入方法

Claude Code を使っている場合、Claude Code プラグインを入れるのが一番早いです。

/plugin marketplace add ideamans/claude-public-plugins
/plugin install gridgram@ideamans-plugins
/reload-plugins

あとは「gridgram CLI をインストールして」と Claude Code に頼むと、OS を検出して $PATH の通った場所に配置してくれます。自分の環境ではこれで CLI のセットアップまで通って、すぐ動きました。

gg --help が通れば準備完了です。

並べてみると

	手書きSVG	Mermaid	Gridgram
コード量	多い	少ない	中くらい
デザインの自由度	高い	低め	中くらい
アイコン	自前で書く	ほぼ使えない	Tablerが大量
テキスト管理	つらい	楽	楽
LLMとの相性	良い	良い	かなり良い

自分の用途では「微修正のしやすさ」と「LLMと一緒に直しやすいか」を重視しているので、関係図・フロー図なら今は Gridgram が一番しっくりきています。Mermaid のシンプルさも好きですが、見た目を少し整えようとした瞬間に手間が増えるのは自分には合わなかったです。

補足

Gridgram はあくまで「関係図」に特化していて、シーケンス図やクラス図はサポートしていないです。そういうケースは引き続き Mermaid を使うのが素直だと思っています。

Gridgram 自体まだ新しいツールなので、今後どう拡張されていくかは楽しみにしているところです。