Mermaid でシーケンス図を書いたら GitHub では表示されるのに Notion では崩れた、という経験はないでしょうか。
あるいは draw.io で丁寧に仕上げたアーキテクチャ図を Git で管理しようとして、diff が数百行の XML の塊になって途方に暮れた、とか。
図を「テキストで書けて、差分が取れて、AI にも触らせられる」状態にしたい——その欲求を真正面から受け止めているのが、cathrynlavery/diagram-design というリポジトリです。
Claude Code と組み合わせると、図の編集をエージェントに任せるワークフローがかなり現実的になります。
そのリポジトリがなぜ AI エージェントと相性がいいのかを構造的に説明しつつ、実際に Claude Code に指示を出して図を編集するところまでのイメージを具体的に掴んでもらえるように書きます。
Mermaid と draw.io の「どこが痛いか」を整理する
Mermaid の一番の問題は、レンダリング環境への依存です。
同じ記法を書いても、GitHub・Notion・社内 Wiki・Confluence でそれぞれ見え方が違う。
「ちゃんと表示されるか」を確認するためだけに複数環境を開く、という無駄な往復が発生します。
スタイルの自由度も低いですよね。
ノードの色を変えたい、フォントを揃えたい、と思っても Mermaid の記法でできることはかなり限られています。
ビジネス側に見せる資料に使おうとすると、どうしても「エンジニアが作った感」が出てしまう。
draw.io はその逆で、GUI で綺麗に仕上げられる代わりに、ファイル管理がつらくなります。
.drawio ファイルの実体は XML ですが、座標・スタイル・メタデータが混在した冗長な構造で、人間が読んで意味を取れるものではありません。
Git で差分を取っても「何が変わったか」がほぼ分からない。
AI に直接編集させようとすると、構造を壊すリスクが高くなります。
整理すると、こういう二項対立になります。
Mermaid は「テキストで書けるが、AI が触りにくく、環境依存がある」。
draw.io は「GUI で綺麗に仕上げられるが、差分管理できず、AI が直接編集しにくい」。
この両方の痛みを、diagram-design は別のアプローチで解こうとしています。
diagram-design の設計思想：外部依存ゼロの自己完結 HTML + SVG
cathrynlavery/diagram-design は、Claude Code 向けに設計された 29 種類のダイアグラムテンプレート集です。
GitHub 上で 2,800 以上のスターを集めていて、フォーク数も 200 を超えています。
リポジトリの説明文には「No shadows, no Mermaid-slop」と書いてあって、設計思想がそのまま出ています。
ファイル構成は、テンプレートが skills/diagram-design/ 以下に格納されていて、references/style-guide.md にブランドカラーやフォントを記述する仕組みになっています。
スタイルガイドを一度書けば、そこから生成するすべての図に設定が波及します。
このリポジトリの特性は、大きく3つにまとめられます。
- 外部依存ゼロ：CDN も npm パッケージも不要。HTML ファイルを開くだけで表示できる
- テキストとして完全に読める SVG 構造：ファイルの中身がそのまま意味のあるテキストで、Git diff が機能する
- デザイン統一：シャドウを排除し、スタイルガイドで色・フォントを統一管理する
シャドウを排除しているのは、見た目の好みの問題ではなく実用的な理由があります。
印刷したとき・スライドに貼ったとき・ダークモードで見たときに、シャドウが意図しない見え方になるケースが多い。
「どこでも同じように見える」を担保するための設計判断です。
外部依存ゼロという点も、地味に効いてきます。
Mermaid はレンダラーが必要で、draw.io はアプリが必要です。
draw.io の公式スキルを使えば Claude Code から .drawio を生成できますが、結果を確認するためにはアプリを開く必要があります。
draw.io の SVG エクスポートは content 属性に元の XML を埋め込む仕組みで、ブラウザで直接開いても編集に戻れる設計ですが、それでも「アプリありき」の前提は変わりません。
diagram-design の HTML ファイルはブラウザさえあれば確認できる。
これが後述するビジュアル検証ループの軽量さに直結しています。
SVG テキスト構造が Claude Code に向いている理由
Claude Code がファイルを操作するとき、基本的にやっていることは「ファイルを読んで、差分を当てる」です。
つまり、ファイルの中身がそのまま LLM のコンテキストに乗ります。
ここで Mermaid と SVG の違いが効いてきます。
Mermaid は「記法 → レンダラー → 画像」という間接変換が入るので、AI が出力を視覚的に確認できません。
「この記法を書けばこう表示されるはず」という推論に頼ることになる。
draw.io の XML は確かにテキストですが、座標・スタイル・ID が混在していて、どこを書き換えれば何が変わるかを AI が推論するのは難しい構造です。
一方、SVG のテキスト構造はこんな感じです。
<!-- Mermaid 記法（記述は簡潔だが、レンダラーがないと結果が分からない） -->
graph TD
A[決済処理] --> B[メール通知]
<!-- diagram-design の SVG（意味が直接読める） -->
<rect x="100" y="50" width="160" height="48" rx="6" fill="#2563EB" />
<text x="180" y="80" text-anchor="middle" fill="#fff" font-size="14">決済処理</text>
<line x1="180" y1="98" x2="180" y2="146" stroke="#64748B" stroke-width="2" />
<rect x="100" y="146" width="160" height="48" rx="6" fill="#2563EB" />
<text x="180" y="176" text-anchor="middle" fill="#fff" font-size="14">メール通知</text>
SVG の rect は矩形、text はテキスト、line は線です。
属性の意味も直感的で、fill は塗り色、x・y は座標、width・height はサイズ。
AI が「どこを書き換えれば何が変わるか」を推論しやすい構造になっています。
もう一つ大きいのが、ビジュアル検証ループの軽量さです。
Claude Code が SVG を編集したら、ブラウザで HTML を開いて確認して、また指示を出す。
このサイクルが外部ツールなしで回せます。
Mermaid だとレンダラー環境が必要で、draw.io だとアプリが必要で、それぞれ確認のための文脈切り替えが発生します。
「生成 → ブラウザで確認 → 再指示」が一番シンプルに回せるのが、diagram-design の HTML + SVG という形式です。
Claude Code で図を編集するワークフロー
実際の流れはシンプルです。
まずリポジトリをクローンして、references/style-guide.md に自分のプロジェクトのブランドカラーとフォントを書き込みます。
ここを一度設定しておけば、以降に生成するすべての図に設定が引き継がれます。
次に、使いたいテンプレートを skills/diagram-design/ から選んで開き、Claude Code に指示を出します。
実務でよく使う図を3つ例に挙げると、それぞれこんな場面で使います。
フロー図 は、決済処理・認証フロー・エラーハンドリングの分岐など、処理の流れを示すときに使います。
PR レビューで「このフローで合ってる？」と確認するときに、コードだけより図があると話が早い。
シーケンス図 は、外部 API 連携や複数サービス間のやり取りを時系列で示すときに使います。
「どのタイミングで誰が誰に何を送るか」が一目で分かるので、設計レビューや障害調査に重宝します。
ER 図 は、テーブル追加・カラム変更のたびに更新が必要になる図です。
ここが AI エージェントとの相性が出やすい場面で、「このテーブルを追加したから ER 図を更新して」という指示を自然言語で出せると、更新コストが大きく下がります。
実際のプロンプトはこんな感じになります。
skills/diagram-design/flow-diagram.html を開いて、
「決済処理」ノードの直後に「メール通知」ステップを追加してください。
新しいノードには style-guide.md のアクセントカラーを使い、
既存のノードのスタイルと揃えてください。
これを受けて Claude Code が行う変更は、SVG の中に rect と text を追加し、既存ノードから新ノードへの line または path を追加する、という操作です。
変更前後の差分はこんな形になります。
<!-- 変更前：決済処理ノードで終わっていた -->
<rect x="100" y="50" width="160" height="48" rx="6" fill="#2563EB" />
<text x="180" y="80" text-anchor="middle" fill="#fff" font-size="14">決済処理</text>
<!-- 変更後：メール通知ノードを追加 -->
<rect x="100" y="50" width="160" height="48" rx="6" fill="#2563EB" />
<text x="180" y="80" text-anchor="middle" fill="#fff" font-size="14">決済処理</text>
<line x1="180" y1="98" x2="180" y2="146" stroke="#64748B" stroke-width="2" marker-end="url(#arrow)" />
<rect x="100" y="146" width="160" height="48" rx="6" fill="#F59E0B" />
<text x="180" y="176" text-anchor="middle" fill="#fff" font-size="14">メール通知</text>
結果の確認はブラウザで HTML を開くだけです。
エクスポートが必要な場合は、リポジトリに含まれる /export-diagram コマンドで PNG または SVG として書き出せます。
Figma やスライドに貼りたいときはこのエクスポートを使う流れになります。
現時点の限界と、Mermaid・draw.io との使い分け
正直なところ、万能ではありません。
一番ハマりやすいのは、ノード数が多い・矢印が入り組んでいる複雑な図です。
SVG は座標を直接書く形式なので、ノードが増えると AI の座標計算が破綻しやすくなります。
「なんか重なってる」「矢印が変な方向に向いてる」という状態になったとき、人間が手で直すのも一苦労です。
テンプレートの範囲内に収まる図、つまりノード数が10〜15程度までの図に向いていると思っておくのが現実的です。
Mermaid や draw.io を完全に置き換えるものでもありません。
それぞれに得意な文脈があります。
- AI エージェントが繰り返し編集する図（ER 図・フロー図の更新など）→ diagram-design
- 人間が GUI で細かく調整したい図（複雑なアーキテクチャ図・レイアウトにこだわりたい図）→ draw.io
- コードと同期させたい軽量な図（README に埋め込む・CI で自動生成する）→ Mermaid
結局のところ、「どのツールが最強か」という問いの立て方があまり意味を持たない領域です。
誰が主体的に触るか で選ぶ、というのが一番シンプルな判断軸だと思っています。
人間が GUI でこだわって仕上げたいなら draw.io、コードと一緒に管理したいなら Mermaid、AI エージェントに繰り返し更新させたいなら diagram-design。
AI エージェントが開発フローに入ってくると、「AI が触りやすいか」という軸が図のフォーマット選択に加わってきます。
diagram-design はその軸を最初から意識して設計されていて、だからこそ Claude Code との組み合わせで実用的なワークフローが組めます。
まずはクローンして、手元の図を一つ Claude Code に編集させてみるところから始めてみてください。
株式会社ホコサキは、山口県宇部を拠点に Web 制作・業務システム開発・AI 活用支援を手がけています。
Claude Code を使った開発ワークフローの整備や、AI エージェントを実務に組み込む取り組みも日常的に行っています。
ご相談があれば お問い合わせページ からお気軽にどうぞ。