【初心者応援】徹底解説_Mermaid記法の書き方

初心者応援・徹底解説シリーズ 【初心者応援】徹底解説 Mermaid記法の書き方 図解を資料に落とし込む技術 要件定義 設計レビュー 公式ドキュメント：mermaid.js.org ／ 根拠論文：ACM CHI 2024 実装 → テスト

WHY — なぜMermaidを学ぶのか 「図がない資料」は、読み手に負担を押し付けている ① 現場のエンジニアは、実はいつも図を描いている ACM CHI 2024の研究では、プログラマーが日常的にコード内へ ASCII図を書き込み、構造や処理の流れを視覚的に補足している実態が報告され ている。テキストだけでは伝わりにくい関係性を、人は自然と図に頼って補っている。 ② 「コードとしての図」はレビューできる Mermaidで書いた図はテキストファイルなので、 Gitで差分管理・プルリクエストレビューが可能。画像で図を管理すると更新の度に手作業でズレ ていくが、Mermaidなら仕様変更にコードと一緒に追従できる。 ③ 文系出身エンジニアほど「先に」武器にすべき 設計や仕様の説明を口頭・文章だけでこなすのは経験値がいる。先に Mermaidを押さえておけば、関係性を図にして見せるだけで、実装前のレ ビューの精度が一段上がる。 【初心者応援】徹底解説 Mermaid記法の書き方 2

WHAT — Mermaidとは何か テキストを書くだけで図になる「 Diagram as Code」 Markdownのような簡易記法を書くと、JavaScriptライブラリが解析してSVG図を自動生成するツール。公式サイト：mermaid.js.org flowchart sequenceDiagram classDiagram 業務フロー・処理の分岐 APIの通信・処理の時系列 クラス設計・データ構造 stateDiagram-v2 erDiagram gantt / timeline ステータスの状態遷移 テーブル間の ER図 スケジュール・工程表 GitHub / Qiita / Notion / VSCode / Confluenceなど主要ツールが標準対応 【初心者応援】徹底解説 Mermaid記法の書き方 3

HOW ① — 基本のフローチャート 最初に覚えるのはこの 5行だけ flowchart TD A[要件定義] --> B{設計レビュー} B -->|OK| C[実装] B -->|NG| A C --> D[テスト] [ ] 四角＝処理・作業 { } 菱形＝分岐・判断 --> 実線矢印＝通常の流れ -.-> 点線矢印＝補助的な流れ |OK| 矢印上のラベルで分岐条件を明示 TD = Top Down（上から下）。左右に流したい場合は LR（Left to Right）に変えるだけ。ノードのIDは半角英数字、表示名は [ ] の中に日本語でOK。 【初心者応援】徹底解説 Mermaid記法の書き方 4

図解サンプル① — フローチャート 同じ5行が、そのままこの図になる コード 描画される図 flowchart TD A[要件定義] --> B{設計レビュー } B -->|OK| C[ 実装] B -->|NG| A C --> D[ テスト] 要件定義 NG 設計 レビュー OK 実装 テスト 左のコードをそのまま Mermaid Live Editor に貼ると、右と同じ図が一瞬で 描画されます。ノード名・矢印・分岐ラベルが、そのまま図の要素に対応し ているのがポイントです。 【初心者応援】徹底解説 Mermaid記法の書き方 5

図解サンプル② — シーケンス図 「誰が誰に何を送ったか」が時系列で見える コード sequenceDiagram ユーザー->>API: リクエスト送信 API->>DB: データ取得 DB-->>API: 結果を返却 API-->>ユーザー: レスポンス 描画される図 ユーザー API DB ①リクエスト送信 ②データ取得 ③結果を返却 ④レスポンス 実線（-->>）は要求、点線（ -->>の破線）は応答。上から下に読むだけで、 通信の順番がそのまま追えます。 【初心者応援】徹底解説 Mermaid記法の書き方 6

図解サンプル③ — 状態遷移図 「今どの状態か」が一本の流れで見える コード 描画される図 stateDiagram-v2 [*] --> 未着手 未着手 --> 対応中 対応中 --> 完了 完了 --> [*] 未着手 対応中 完了 [*] は「開始」と「終了」を表す特殊な状態。矢印でつないだ順番どおりに、 ステータスが一方向に進んでいくことが一目で分かります。 【初心者応援】徹底解説 Mermaid記法の書き方 7

図解サンプル④ — クラス図 「データ構造とその関係」が箱と線で見える コード 描画される図 classDiagram class User { +String name User +String email + name : String +login() + email : String Order 1 many } + id : String + createdAt : Date class Order { + login() +String id +Date createdAt } User "1" --> "many" Order クラス名・属性（ +name等）・メソッド（ +login()）が箱の中に整理され、クラス間の関係は線と多重度（ 1・many）で表現されます。 【初心者応援】徹底解説 Mermaid記法の書き方 8

図解サンプル⑤ — ER図 「テーブル同士のつながり」が線と関係名で見える コード 描画される図 erDiagram USER ||--o{ ORDER : places ORDER ||--|{ ITEM : contains places USER contains ORDER 1 N ITEM 1 N ||--o{ は「1対多（0以上）」を表す記号。読み方を覚えなくても、 ER図 として描画されれば関係は直感的に伝わります。 【初心者応援】徹底解説 Mermaid記法の書き方 9

HOW ② — シーケンス図・状態遷移図 「時系列」と「状態」は書き方が変わる ① API通信の時系列 → sequenceDiagram sequenceDiagram ユーザー->>API: リクエスト送信 API->>DB: データ取得 DB-->>API: 結果を返却 API-->>ユーザー: レスポンス ② ステータスの変化 → stateDiagram-v2 stateDiagram-v2 [*] --> 未着手 未着手 --> 対応中 対応中 --> 完了 完了 --> [*] 使い分けの目安 sequenceDiagram → 「誰が誰に何を送ったか」を時系列で説明したいとき（API設計・障害調査の再現手順） stateDiagram-v2 → 「あるモノの状態がどう変わるか」を説明したいとき（チケットのステータス、注文の流れ） 【初心者応援】徹底解説 Mermaid記法の書き方 10

HOW ③ — 書いたその場で確認する プレビュー環境は 3択、迷ったら Mermaid Live Editor ① ② ③ Mermaid Live Editor VSCode拡張機能 GitHub / Qiita / Notion mermaid.live にコードを貼るだけでブラウザ上に 即描画。インストール不要で最初の動作確認に 最適。公式サイトからリンクあり。 「Markdown Preview Mermaid Support」を入れる と、.mdファイル内の ```mermaid コードブロックを プレビューでそのまま描画できる。 ```mermaid の言語指定でコードブロックを書け ば、投稿・コミット後にそのまま図として表示され る。追加設定は不要。 うまく描画されないときの 3大原因 1. 予約語 end を小文字のノード名やラベルに使ってしまっている 2. ラベル内の記号（( ) : { } など）をダブルクォートで囲んでいない 3. 矢印記号の前後にスペー スが抜けている（A-->B ではなく A --> B） 【初心者応援】徹底解説 Mermaid記法の書き方 11

まとめ Mermaidは「頭の中の関係性」を素早くコード化する武器 1 テキストで書ける図＝Gitで管理・レビューできる図。仕様変更にも追従できる。 2 flowchart / sequenceDiagram / stateDiagram-v2 の3種類を押さえれば、業務資料の大半はカバーできる。 3 Mermaid Live Editorで即確認 → VSCode / GitHub / Qiitaにそのまま貼れる。 公式ドキュメント https://mermaid.js.org/ 参考文献 Chasins, S. et al. "Taking ASCII Drawings Seriously: How Programmers Diagram Code." Proceedings of the 2024 CHI Conference on Human Factors in Computing Systems (ACM), 2024.

• https://mermaid.js.org/