設計書をExcelからMarkdownへ移しました。Gitで差分を追えて、AIにも読ませやすい。この変更自体は、以前書いた開発の進め方を変えた話の中でも、やってよかったことの一つです。
ただ、別の困りごとが出ました。
読んでも、全然頭に入ってこない。
VS Codeでプレビューを開く。文字、文字、文字。設計を細かくするほど文字が増え、だんだん読む気がなくなってきます。Mermaidで図にしても、情報を足すほど「小っちゃ」となる。拡大すれば見えるけど、今度は全体が見えません。線のつながりも気になる。見えはするけど頭に入らない。
そこで、大枠の処理フロー、詳細な処理フロー、業務フローを、AIにSVGで作らせてみました。これが思った以上に頭に入ってきた。実装前にAIが作った設計書の下書きを自分で見直す中で、例外処理、メール通知、ステータス変更、DBやサーバーの境界の不足にも気づけました。
Mermaidをやめるつもりはないし、シーケンス図は今も見やすくて好きです。単純な図はMermaid。全体を眺めながら設計の漏れを探したい図はSVG。今はそんな感じで分けています。
設計書では、最初にSVGで作った全体フローを載せ、少し説明を挟んでから詳細なフローを置いています。その後にセクションを分けて、処理の細かい条件を書いています。業務フローもSVGにして、PowerPointへ取り込み、図形に変換して使えるようにしてみました。
Mermaidも図なのに、なんか頭に入らない
Mermaidで作った図にも、必要な情報は載っています。文章だけよりは追いやすい。シーケンス図なら、かなり好きです。
困るのは、情報を追加した後でした。
- ノードが増えるほど、プレビュー上の文字が小さくなる
- 拡大すると一部分は読めるが、全体の流れが見えなくなる
- コネクタの交差や経路が気になり、処理そのものに集中できない
- すべての要素が同じ強さに見え、どこから読むか迷う
大枠の処理フローや業務フローは、全体を眺めながら「この後に何が起きる？」「別システムとの境界は？」と考えたい。文字が読めるだけでは足りませんでした。特にAIが作った設計書を初めて読む時は、文章から処理の形を頭の中で組み立てるのがしんどい。私は普段、文字を読みながら図を想像していたのだと思います。
シーケンス図は上から下へ時系列を追えばいいので、Mermaidでも読みやすい。私がつらかったのはMermaidそのものではなく、レイアウトを細かく触りたい図まで、全部Mermaidで作ろうとしていたことだと思います。
議事録を画像にしたら、思ったより簡単だった
きっかけは、たまたま議事録を1枚の画像にまとめてみる作業でした。
最初は「AIに画像を作らせるの、面倒そうだな」と思っていました。ただ、必要なのは写真のような画像じゃない。文字をフローにして、まとまりごとに色を付けるくらいです。実際にやってみると、案外簡単でした。
以前、AIにフロー図を画像で作らせた時は、意図したものになりませんでした。今回は文字や流れが狙いに近かった。ただ、以前はSVGで作っていなかったので、AIの精度だけが上がったとは言い切れません。
その後、AIと壁打ちしている時に「SVGがいいんじゃないか」という話が出ました。SVGは、XMLを基に2次元のベクター画像を書く形式です。画像なのに、中身はrect、path、textなどが並ぶテキストです。
文字を正確に置けるし、XMLなのでGitの差分も見られる。ブラウザやVS CodeのMarkdownプレビューでは普通の画像として見えるし、PowerPointへ持っていくこともできます。
これなら仕事の設計書でも使えそう。そう思って試してみました。
Lunaで作ったら、最初は全部直すことになった
仕事では、GitHub Copilot上のGPT-5.6 LunaにSVGを作らせました。Lunaは、OpenAIがコスト重視の大量処理向けとしているモデルです。
もちろん、最初からきれいにはできませんでした。
- タイトル、ヘッダー、本文の文字サイズの強弱
- ノード内の余白
- 箱同士や箱と外枠の重なり
- 余白が足りず、枠線同士がくっついて見える箇所
- 箱や外枠からはみ出した文字
- 文字と線の重なり
- 直角になっていないコネクタ
- 大きすぎる矢印
- ヘッダーの文字色
- 用途が分からないアイコン
- 業務フローなのに人型アイコンがなく、追加すると今度は人型の形がおかしい
- 拡大しないと読めない文字
- フォントをメイリオに指定
気になったところは、ほぼ全部です。最初は何度か修正を頼み、それなりにラリーも発生しました。
ただ、文字サイズや余白、コネクタ、矢印、重なりのルールを一度定義すると、その後のラリーは減りました。回数や消費量の記録は残していないので、どれだけ減ったかを数字では言えません。それでも、始める前に想像していたほど重たい作業ではなかったです。
以前、巨大なプロンプトを書くのをやめた話で、共通ルールはリポジトリ側へ置く運用を書きました。SVGも同じでよさそうです。毎回長いプロンプトを貼らず、文字や余白のルールはSKILLへ置く。今回変わる処理と関係だけを渡す。今はこの形にしようとしています。
アイコンがないんじゃなく、処理そのものがなかった
SVGにして一番よかったのは、きれいに見えたことではありません。AIが作った設計書の下書きを、実装前に自分でレビューしていた時に、設計の漏れに気づけたことです。
図を見た時、最初はメール通知のアイコンを置き忘れただけだと思いました。でも、よく見ると違いました。設計の中に、メール通知の処理そのものがなかった。
ほかにも、いろいろ抜けていました。
- 失敗時の例外処理がない
- 処理後のステータス変更がない
- DBへ保存する境界が曖昧
- どこまでが同じサーバー内の処理か分からない
文章や小さな図でも、一つずつ追えば確認はできます。ただ、全体が目の前に並ぶと、「ここから先がない」「この境界を越える線がない」と分かる。抜け方が目に見えたので、AIに指摘して設計書を直してもらいました。
別にSVGが設計を検証してくれたわけではありません。同じ画面で全体と詳細を見られるようになり、把握とか理解の余裕ができたのが大きかったのだと思います。
仕事で漏れに気づいた図は、ここには載せていません。代わりに、以前書いたAIにコードを書かせた後、rg・fzf・Yazi・Neovimで読むの流れを、公開用の例としてSVGにしました。AIがコードを変更した後、Gitで変更範囲を見て、rgで手掛かりを絞り、Neovimで関係を追う。必要な箇所だけ直し、最後にGit差分とテストで確かめます。
このブログの画像アップロードはPNG前提なので、掲載用だけPNGへ変換しました。元のSVGもリポジトリに残しています。
横長の図は、スマートフォン幅まで縮めると文字が読めません。同じ流れを縦に並べた版も作りました。狭い画面ではこちらのほうが追いやすいです。
SVGはGitで差分を見られる。ただ、油断すると全部変わる
SVGはXMLなので、ラベル、色、座標、接続線の変更をGitで確認できます。
とはいえ、SVGなら勝手にきれいな差分になるわけではないです。
ノードを一つ足しただけなのに、AIがすべての座標を動かし、要素の順番まで変える。そうなると、差分上はほぼ全部変更です。これではレビューしにくい。
そこで、今作っているSKILLには次のルールを入れました。
- ノード、線、境界へ意味の分かるIDを付ける
- 座標は8px単位を基本にし、小数を増やさない
- 要素の並び順を固定する
- 既存SVGの修正では、関係ない要素を動かさない
- プレビューで読めない量になったら、文字を小さくせず図を分ける
- 例外、通知、ステータス変更、DB、外部システムの境界を確認する
- 箱、枠線、文字を重ねず、拡大しなくても読める余白を取る
- 処理フローの線は直角にし、矢印を大きくしすぎない
- フォントはメイリオを指定し、タイトル、ヘッダー、本文の順に強弱を付ける
- 謎のアイコンを作らず、業務フローの人型は形まで確認する
見た目の指定だけでなく、設計の漏れを探すチェックリストも一緒に持たせています。まだ調整中ですが、単にSVGを出すだけでは弱い。レビューに使えるSVGを作るSKILLにしたいです。
PowerPointへ持っていくと、ちょっと崩れる
Microsoft 365のPowerPointでは、対応するSVGをOfficeの図形へ変換し、各要素を編集できます。設計書の図を説明資料へ持っていく時には便利です。
ただ、私が試すと少し崩れました。特に文字位置やコネクタは、ブラウザで見た時と完全には一致しません。
今は、PowerPointへ持っていくSVGでは複雑な変形や装飾を避け、文字と座標を明示するルールを試しています。もちろん変換後の確認も必要です。
ここはまだ解決していません。ただ、SVGから変換して、崩れた文字位置やコネクタだけを直すなら、一から図を作るよりずっと楽です。作る人によって「ちょっと昔っぽい」と感じる図やアイコンになることも、同じSVGから始めれば減らせそうです。SVGはGit管理の元データとして残し、PowerPoint側は説明用に微調整する。今はこれでよさそうです。
Markdownは残す。読む時だけSVGを足す
Markdownは、設計内容を正確に残し、検索し、AIに読ませるには使いやすいです。SVGだけにすると、細かな条件や判断理由まで一枚へ詰め込みたくなる。たぶん、また読みにくくなります。
今の使い分けは次の通りです。
| 形式 | 私が使う場面 |
|---|---|
| Markdown | 正式な設計内容、条件、判断理由 |
| Mermaid | シーケンス図、単純な関係やラフな図 |
| SVG | 大枠・詳細の処理フロー、業務フローなど、俯瞰してレビューしたい図 |
| PowerPoint | 会議で説明し、その場で編集したい資料 |
Markdown設計書へ移したこと自体は失敗ではありません。AIが読みやすく、Gitで管理しやすい状態は残したい。
私が設計書を作るのは、情報を残すためだけじゃなく実装する前に同じ流れを見て、「メール通知は？」「失敗したらどうする？」と指摘できるようにするためです。
細かな条件や判断理由はMarkdownに残し、重要なフローはSVGで見渡せるようにしています。
PowerPointで一から図を描く手間が減ったのもよかった。でも、一番大きいのは、文字だけでは頭に入らなかった設計書を見て、メール通知や例外処理の抜けを自分で指摘できたことです。SKILLのルールはまだ調整中。図をきれいにするだけでなく、漏れに気づける図にしていきたいです。
確認した公式情報
2026年9月19日に、次の公式情報を確認しました。
コメント