きっかけ
最近、AI駆動開発を試す中で、こんな場面があった。
「認証フローの仕様をAIに渡して、実装を生成させよう」
と思い、Wordに貼ってあった処理フロー図をそのままコピペしてプロンプトに投げた。
返ってきたコードは、フローの一部を無視していた。
「なぜ？」と思い調べていくうちに、
「AIに仕様を理解させる」こと自体の難しさ
に気づいた。
触ったのは主にこの3つ：
- draw.io
- Mermaid
- Markdown + VS Code
AIはWordの図を"理解"していない
従来の業務では、Word・Excel・PowerPointに図を貼って仕様化することが多い。
しかしAI視点では、Wordの図は"ただの画像"に近い。
人間は矢印・分岐・処理順を直感的に読めるが、AIはかなり苦手だ。
特に、
- オブジェクトの位置関係
- 線の意味（依存？順序？条件？）
- 分岐条件の曖昧さ
を間違えやすい。
冒頭の失敗はまさにこれが原因だった。
「ログイン失敗時のリトライ処理」が図の隅に書いてあったのに、AIはそこを読んでいなかった。
AI向けには「構造化」が重要
そこで注目されているのが、
- Markdown
- Mermaid
- YAML / JSON
のような**「構造化テキスト」**だ。
例えばMermaidなら：
これだけで図になる。
そしてAIは A --> B を「処理の関係性」として理解しやすい。
実際、Wordの図をそのまま渡したときと、Mermaidで書き直したものを渡したときでは、生成されるコードの精度が体感で明らかに違った。
draw.ioは人間に優しい
ただ、Mermaidを人間がゼロから書くのは正直ツラい。
- 構文を覚える必要がある
- 複雑なレイアウトは手書きでは限界がある
- 非エンジニアには敷居が高い
そこで便利なのが draw.io（diagrams.net）。
- ドラッグ＆ドロップで図を作れる
- PowerPoint感覚で直感的
- XMLでの保存なのでGit管理も一応できる
- 無料で使える
実際に使ってみると、フロー図や構成図をサクサク作れて、「これ今まで何でPowerPointで作ってたんだろう」 と思うくらい便利だった。
ただし問題がある。
AIがdraw.ioの図を完全理解するのはまだ難しい。
draw.ioのXMLをそのままAIに渡すと一応読めるが、精度はMermaidには劣る。
「人間には分かりやすい、AIには構造化テキストの方が伝わる」というギャップがここにある。
結局どうなるのか？
今のところ現実的なのは、人間向けとAI向けを分ける運用だ。
| 用途 | ツール |
|---|---|
| 人間向けの図 | draw.io |
| 人間向けのドキュメント | Word / PowerPoint |
| AI向けの構造 | Mermaid |
| AI向けのドキュメント | Markdown |
例えばこんな流れ：
draw.ioで図を書く
↓
Word/Confluenceへ貼付（人間向け）
↓
Mermaid化してMarkdown保存（AI向け）
「Mermaidで書いたものをdraw.ioで開けないの？」問題
ここで一つ素朴な疑問が浮かぶ。
Mermaid化したMDファイルを、draw.ioでもう一度開いて編集することってできないの？
実はこれ、みんなが夢見てる理想だ。
結論から言うと、
「完全にはまだ弱い。ただ一部はできる」
という状態。
なぜ相互変換が難しいのか
draw.ioとMermaidは、そもそも思想が違う。
| draw.io | Mermaid | |
|---|---|---|
| 重視すること | 見た目・レイアウト | 論理構造 |
| 操作 | GUI | テキスト |
| レイアウト | 自由・保持 | 自動配置 |
| 内部形式 | XML（座標・色・サイズ込み） | シンプルな関係記述 |
draw.ioは「どこに何が置いてあるか」まで持っている。
Mermaidは「AはBに繋がる」という関係だけを書く。
だからMermaid → draw.ioへ完全復元しようとすると、座標情報が消えていて再現できない。
現時点での実現度
| やりたいこと | 実現度 |
|---|---|
| Mermaid → 図として表示（VS Code / GitHub） | ◎ |
| Mermaid ⇄ GUI同期編集（Mermaid Chart等） | ○ |
| draw.io → Mermaidへ変換 | △ |
| Mermaid → draw.ioで完全復元 | ✕ |
「Mermaidコードを書きながら、隣で図が更新される」という体験は Mermaid Chart で実現できる。draw.ioほどの自由度はないが、業務フローやシーケンス図には十分使える。
「GUIはビューに過ぎない」という発想
ここで面白い思想がある。
「Mermaidが正本で、GUIはそのビュー」 という考え方だ。
昔のWebと同じ構造で言うと：
昔：HTMLを書く → ブラウザが表示
今：Mermaidを書く → 図として表示
この思想が強くなると、
- AIはMermaidを直接修正する
- Gitで差分管理する
- レビューはテキストベースで行う
という未来が見えてくる。
これは実は、AI駆動開発の最前線テーマの一つだ。
「図を構造化データとして持つ」問題はまだ覇権ツールが決まっていない、ホットな領域でもある。
そして最大の問題：同期地獄
ここで発生するのが 「同期問題」 だ😅
仕様が変更になったとき、
- Word直した？
- draw.io直した？
- Mermaid直した？
- Markdown直した？
- 実装直した？
- テスト直した？
という多重管理地獄が待っている。
「仕様変更のたびに6箇所直す」なんて、そもそも続かない。
現時点での個人的な対処法は、「Mermaid（Markdown）をマスターにして、他はそこからの派生と割り切る」 こと。
draw.ioの図はMermaidに書き直してMarkdownに埋め込み、Wordは最終的な配布用にだけ使う、という整理にしつつある。
完全な解決策ではないが、少なくとも「マスターがどこか」を決めるだけで、かなりマシになる。
AI駆動開発はまだ黎明期
SNSではキラキラした成功事例も多いが、実際には 「どう仕様を持つか」自体がまだ発展途上 だ。
ただ、その中で見えてきた確かなことがある。
AIは「見た目」より「構造」を読む。
だから、
- Markdown
- Mermaid
- Docs as Code
のような文化がこれから強くなっていくのは間違いないと思う。
まとめ
AI駆動開発は「AIが全部作ってくれる未来」というより、
「AIが理解しやすい形へ仕様を構造化する戦い」
に近いと感じた。
そして、その戦いで一番の敵はコードではなく、"同期問題" かもしれない😅
次は Mermaid Chart を実際の業務フローに使ってみること、そして「draw.io → Mermaid変換」の自動化を試してみようと思っている。うまくいったら記事にする予定。
この分野はまだ覇権ツールが決まっていないので、今が一番面白い時期かもしれない。
この記事はAI駆動開発を試しながら気づいたことをまとめたものです。まだ模索中の段階なので、コメントで「うちはこうしてる」があればぜひ教えてください！