第 03 章「デザインをする ── Mermaid と Claude デザインで作る」の主張を裏付ける。

章のどの主張に対応するか

Mermaid 図 1 枚の Git 差分: 1 行追加・1 行削除、レビュー 30 秒で済む。同じ変更を PowerPoint でやると、ファイル全体が "binary changed" としか見えない。

20 年前の .ppt ファイル: フォント置換で図形がずれ、再現困難。同じ時代の Markdown / Mermaid ファイルは、今のレンダラで完全再現。

(章本文「実例: 数字で見る」より)

やること

業務で書く 5 種類の図を、全部 Mermaid テキストで定義し、コマンドで SVG/PNG に焼く。

ファイル	種類	内容
`system-architecture.mmd`	フローチャート	Web + API + DB + Claude のシステム構成
`sequence-order.mmd`	シーケンス図	注文受付の API 呼び出しフロー
`er-customer.mmd`	ER 図	顧客 / 注文 / 商品のスキーマ
`gantt-launch.mmd`	ガントチャート	1 人 + AI で SaaS をローンチする 4 ヶ月計画
`state-order.mmd`	状態遷移図	注文状態のライフサイクル

合計 5 ファイル、ソース合計 2,488 byte(2.4 KB)。これを Markdown 記事にそのまま埋め込めば、GitHub も Notion もネイティブで描画する。コマンドでも SVG / PNG に変換できる。

構成

example-1/
├── README.md
├── Makefile
├── puppeteer-config.json   ── headless chromium を root で動かす設定
├── results.md
├── src/                    ── ソース (5 つの .mmd, 計 2.4 KB)
│   ├── system-architecture.mmd
│   ├── sequence-order.mmd
│   ├── er-customer.mmd
│   ├── gantt-launch.mmd
│   └── state-order.mmd
└── out/                    ── 生成物 (SVG ×5, PNG ×5)

実行

# 必要なツール
sudo apt install fonts-noto-cjk
npm install -g @mermaid-js/mermaid-cli

make clean && make all

なぜこれが「実例」になるのか

5 種類の業務図(構成、API シーケンス、スキーマ、計画、状態遷移)を、 合計 2.4 KB のテキスト 5 ファイルで定義できる。

PowerPoint なら、それぞれ別ファイル、計数 MB、編集すると差分が見えない、バージョン管理に乗らない、AI に渡しても XML を解凍することから始まる。

Mermaid なら:

ソースは Git の通常の diff で見える(1 行追加が 1 行追加に見える)
Markdown に直接埋められる(GitHub・Notion・VS Code がレンダリング)
Claude が読める・書ける(graph TD の文法で出してくれる)
コマンドで SVG / PNG / PDF に焼ける(mmdc -i x.mmd -o x.svg)
10 年後も同じ文法で動く(Mermaid は OSS、Mermaid.js が読める限り)

これが章で言う「Mermaid はテキストだ。Git の差分が出る、AI が読める、書き換えられる、10 年後も読める」の具体形。

計測結果 — 第 03 章 example-1

実行環境: Linux 6.18 / @mermaid-js/mermaid-cli 11.14 / Node 22

ソース vs 出力サイズ

図	`.mmd` ソース	`.svg`	`.png` (1600px)
`system-architecture`	543 B	22,158 B	36,112 B
`sequence-order`	467 B	29,404 B	47,617 B
`er-customer`	509 B	70,730 B	39,516 B
`gantt-launch`	603 B	13,061 B	28,985 B
`state-order`	366 B	37,448 B	31,983 B
合計	2,488 B (2.4 KB)	172,801 B (169 KB)	184,213 B (180 KB)

ソースは 1 ファイルあたり 366〜603 byte の極小テキスト。

Git diff の比較(章本文の主張の検証)

例えば sequence-order.mmd に「キャッシュチェック」のステップを 1 行入れると、git diff はこう見える:

   API->>DB: INSERT orders
+  API->>Cache: 重複チェック
   API->>Claude: 「住所を整形して」

1 行追加が 1 行追加に見える。レビュアーは「キャッシュチェックを DB の後に入れたんだな」と 5 秒で理解できる。

同じ修正を PowerPoint でやれば、git diff は:

Binary files a/sequence.pptx and b/sequence.pptx differ

何が変わったかわからない。レビューが成り立たない。

Claude に書いてもらう例

あなた: 注文確定 API のシーケンス図を書いて。
        顧客 → Web → FastAPI → DB → Claude(住所正規化)
Claude: (sequence-order.mmd 相当のテキストが返る)

あなた: そこに、決済 API への呼び出しを追加して
Claude: (1 行差分)

人間は「描いて」いない。意図を伝えただけ。Claude が文法を当てて、 mmdc が画像に焼く。

描画コマンド

mmdc -i src/sequence-order.mmd -o out/sequence-order.svg \
     -b transparent -t neutral

各図 1 〜 2 秒で SVG / PNG 完成。CI で自動レンダリングして PR コメントに付けることも容易。

10 年後の互換性

Mermaid 11.x の文法は、graph TD sequenceDiagram erDiagram gantt stateDiagram-v2 ── どれもプレーンテキストの DSL。

Mermaid.js が GitHub に存在し続けるかぎり、これらは同じレンダリング結果を返す。仮に Mermaid 自体が消えても、ソースを Claude に渡して別の DSL に変換してもらえる。ソースが構造として残っているから。

PowerPoint の .ppt 形式は仕様変更のたびに過去ファイルが壊れる。Mermaid のソースは壊れない(壊れるとしたらレンダラだけで、書き直せる)。

再現手順

sudo apt install fonts-noto-cjk
npm install -g @mermaid-js/mermaid-cli
make clean && make all

Mermaid 5 種類を SVG / PNG に焼く