AIでドキュメント作成を効率化したいエンジニアへ：Mermaid記法を手で覚える mmtutor

はじめに：なぜ今「AI × ドキュメント効率化」なのか？

ChatGPT、GitHub Copilot、Claude… 生成AIが日常化した今、設計ドキュメントを“機械が読める構造”で残すことが生産性に対して大きな影響を与えると感じています。
これまで主流だったExcel / PowerPointは自由度が高い一方で、AIが解析しづらく再利用に弱い。検索・変換・差分レビューにもコストがかかり、手戻りの温床になりがちです。

そこで効くのがMarkdown + Mermaid。これはAIフレンドリーなドキュメント形式で、検索・要約・図表生成の自動化に強く、人間にも読みやすい。

• Markdown：見出しや箇条書きが明示的 → AIが文脈単位で解析・要約しやすい
• Mermaid：フローチャートやシーケンス図をプレーンテキストで定義 → AIが生成・整形・変換に使いやすい
• Git運用：図がテキストなので差分レビューが容易。図の“意味”が履歴として残る

「AIが図を描けるのに、なぜ自分で覚えるのか？」

もっともな疑問です。しかし、自分の手で書けることは依然として大きな差を生みます。

• 依頼の精度：AIに正確な依頼をするには、構文の語彙が要る
• リアルタイム性：レビューや会議で矢印一本を即修正するなら、AIより人のほうが速い
• 合意形成：顧客折衝でその場で図示できると、認識合わせが段違いに速い

つまり「AIを活かす側」になるには、Mermaidを理解しており、最小単位で手打ちもできることが近道であると考えます。

mmtutor：Mermaidを“手で覚える”ローカル教材

mmtutorはvimtutorをオマージュしたMermaid反復トレーニング環境です。
ブラウザに左＝教材 / 右上＝入力欄 / 右下＝ライブプレビューを並べ、書けば即、図になる最短ループを提供します。

対応トピック（12章）

1. フローチャート / 2. シーケンス図 / 3. クラス図 / 4. ガントチャート / 5. ER図 / 6. 状態遷移図 / 7. 円グラフ / 8. Gitグラフ / 9. ユーザージャーニー / 10. マインドマップ / 11. タイムライン / 12. 4象限チャート

• 即時レンダリング
• ライト/ダーク切替、UIは日本語、Mermaid v10系に最適化
• ローカル実行なので高速・オフライン

3分で始める（Quick Start）

git clone https://github.com/hiroki-imai/mmtutor
cd mmtutor
npm install
npm run dev
# → 表示された URL を開けば、教材＋入力欄＋プレビューの3面が起動

ブラウザで右上に打つだけで右下に図がプレビューされます。

mmtutorサンプル画面1 フローチャート

mmtutorサンプル画面2 シーケンス図

mmtutorサンプル画面3 4象限チャート

現場で効く使い方（AI活用のコツ）

1. 文章に“薄い図”を添える
   議事録・仕様の段落ごとに3～5行のFlow/Sequenceを差し込む。
   → AI指示例：「次の段落をMermaidのフローチャートで最小行数に。コードブロックのみ。」

2. レビューは“その場修正”
   mmtutorを共有し、ノード名や矢印一本を直しながら合意形成。
   → 差分はテキストなのでGitレビューが軽い。

3. 命名の一貫性でAI精度UP
   図のノード / メッセージ / 属性名をコード・テストと揃える。
   → 「この図をもとに雛形コードとテストを」と頼んだときの再現性が上がる。

どこから学ぶ？（システム開発における頻度×効果との優先順位）

• 必修5種：フローチャート / シーケンス図 / クラス図 / ER図 / 状態遷移図
• 状況対応：ガントチャート（進捗共有） / Gitグラフ（ブランチ戦略） / 4象限チャート（優先順位合意）
• UX/事業：ユーザージャーニー / マインドマップ / タイムライン / 円グラフ

mmtutorの教材は“雛形 → 指示どおりに小改変 → 即可視化”。
vimtutor的に「書いてあるとおりに直せば動く」設計とし、毎日の10分ドリルとして何度かやれば基礎構文が身につく構成にしています。

注意点（実装Tips）

• Mermaidはバージョン差で細部が異なります。教材はv10系前提
• 4象限チャート・タイムラインは改行や空白がシビア。付属サンプルを雛形に
• 図が大きくなったら分割し、文章の“薄い図”を複数添えると読みやすい

まとめ：AIを活かす鍵は「構造理解とそれを手でも書ける力」

AIはドキュメントを生成・補助するが、構造を理解して書ける人が最も速いです。mmtutorはその基礎力を短時間で身につけるための反復教材として作成しました。
今こそ「AIに優しいドキュメント形式」である Markdown + Mermaid を標準化し、現場のドキュメント効率化を進めるタイミングです。

👉 リポジトリマーメイド記法を手で覚える mmtutor

git clone → npm install → npm run dev で、今日から AIフレンドリーなドキュメント習慣を始めましょう。

おまけ：mmtutor作成までの工程

使ったAI：

• ChatGPT（企画・仕様・本文） 「vimtutorを模倣したmermaidtutorを作りたい」という要望から壁打ちしてCodexのためのAGENTS.mdを生成してもらう
• Codex（実装・配布整備） AGENTS.mdのとおり実装してもらい、バグとUX改善
• Claude Code（教材・UI改善） 教材の内容をブラッシュアップ

役割分担してプロンプト→差分実装→再指示を回すと、想像以上にぱぱっと形になります。AI便利。

手動でのプログラミングは一切していません。もうプログラマーじゃなくてもほしいアプリ構想さえあればAIへの指示だけで作れる時代ですね。