はじめに
メンテナンスモード設計を AI とペアで詰めている最中、3 シナリオ (通常稼働 / アプリ層 READ-ONLY / エッジ層 FULL_STOP) の挙動が議論を周回しました。コードと文章で説明し直すたびに「で、ここの状態はどちらでしょう?」「読み取り失敗時は通すのか、止めるのか?」が再浮上します。
困って SVG を描いて埋め込んだら、その後の議論が一気にスムーズになりました。「文字で説明する」と「絵を見せる」の差 が、AI 協業文脈ではこれまで以上に大きい、と気づいた経験を共有します。
何が起きていたか
メンテナンスモードの設計ドキュメントは文字で書かれていました:
- エッジ層 (Cloudflare Worker) の役割
- アプリ層 (NestJS Global Middleware) の役割
- エッジ層とアプリ層の使い分け (表 1 つ)
これだけでも論理的には伝わるはずなのですが、実際の会話を振り返ると次のようになります。
- 「inMaintenance=false の時、Worker は何をするのでしょう?」(→ pass-through)
- 「逆でしょうか?」「いえ、逆ではありません」
- 「READ-ONLY モードの時、GET はアプリ層で止まるのか、通るのか?」
- 「allowedPaths は KV のどこにあるのでしょう?」
部分理解の積み上げが噛み合わない という症状でした。AI 側 (Claude) は適切に答えているのですが、こちらが質問の文脈をうまく作れず、毎回違う方向から尋ね直してしまっていました。
SVG を入れたら何が変わったか
3 シナリオ対比の SVG を 1 枚作って設計書に埋め込みました:
[ 通常稼働 ] [ アプリ層 READ-ONLY ] [ エッジ層 FULL_STOP ]
User User User
↓ ↓ ↓
CF DNS CF DNS CF DNS
↓ ↓ ↓
CF Worker CF Worker CF Worker
✓ pass ✓ pass ✗ block (KV: inMaintenance=true)
↓ ↓ ↓
GCLB GCLB 503 HTML
↓ ↓
NestJS Guard NestJS Guard
✓ pass ✗ block (DB flag)
↓ ↓
Controller 503 JSON
↓
200 OK
各列が 1 シナリオで、上から下に処理経路が降りていく構造です。色分け (緑 = pass-through、赤 = block) で「どこで止まるか」が一目で分かります。
埋め込んだ直後の会話は次のようなものでした。
- 「アプリ層 READ-ONLY では Worker は素通りなのですね」
- 「state.inMaintenance はエッジ層だけが見て、アプリ層は別の DB flag を見るのですね」
- 「allowedPaths はエッジ層の概念で、アプリ層は読み取り安全とマークしたエンドポイントで個別判定するのですね」
それまで 3 ターンかかっていた確認が 1 ターンで済む ようになりました。
なぜ AI に対して SVG が効くか
これは AI のコンテキスト処理特性に関係しています。
文章ベースの設計書の限界
AI は文章を順次的に読みます。複数のシナリオが文章で長く説明されている場合、
- 「シナリオ A はこう動きます。ただし B のときは違って…」
- 「上記のうち X の場合は別経路で…」
の枝分かれを 読み手が脳内で図にまとめ直す 必要があります。AI もこの再構成を裏でやっていますが、再構成のたびに少しずつ意味がずれていく (= 部分理解が積み上がる) 現象が起きます。
SVG / ダイアグラム の効能
SVG が埋め込まれていると、AI は 同じ視覚情報 を見ることができます。Claude のような multimodal AI は SVG (実体は構造化テキスト) を直接読めるので、
- 「左列が通常稼働、中列がアプリ層 READ-ONLY、右列がエッジ層 FULL_STOP」
- 「緑矢印は pass-through、赤矢印は block」
という 構造ラベル が共有された状態で会話できます。これは人間同士でホワイトボードに描きながら話すのと近い体験です。
SVG を埋め込む具体的なテクニック
niyase の設計書では以下を実践しています:
1. シナリオ対比は必ず横並び
n シナリオを比べる場合、列を横に並べて 同じ高さで対応点を読み比べられる ようにします。縦並びだと「あの矢印」「この矢印」が指せなくなります。
2. 色は意味で固定
- 緑 = pass-through (機能している方向)
- 赤 = block (停止方向)
- 紫 = bypass (特別な経路、ADMIN)
- 橙 = 緊急時経路
色を意味と結びつけると、AI も人間も 「この色 = この概念」 と参照できるようになります。
3. 数値や文字列は最小限
SVG は文字を含められるので欲張りがちですが、「読んでもらう情報」と「見てもらう構造」は分けます。詳細は近接する文章で書き、SVG は構造だけ示します。
4. ファイルパスを明記して再利用
_assets/ 配下に置いて、設計書からの相対パスで参照します。AI が「この SVG の何行目を見て」と指せるようにします。
「設計書 = AI と人間の共有メンタルモデル」
設計書 (design doc) の伝統的な役割は 「未来の自分 + チーム」に向けて記録する ことでした。が、AI 協業時代では役割が拡張されます:
| audience | 役割 |
|---|---|
| 未来の自分 | 思考の足場、立ち戻る場所 |
| チームメンバー | 引き継ぎ、レビュー |
| AI 協業相手 (Claude 等) | 共有メンタルモデル、誤解防止 |
3 番目の audience が増えたとき、「文章で順次的に読まれる」想定 → 「構造として一目で把握される」想定 に書き方を寄せていく必要があります。SVG はそのための有力なツールです。
派生: 同思想のツール
私たちは SVG 以外にも、AI に「見せる」ための資産を整備しています:
- ブランドプレビュー (HTML) — Light/Dark トグル付きのカラー / タイポ / ロゴ プレビュー (ブラウザで開く)
- インフラ全体俯瞰図 (SVG) — システム構成を一望できる図
- 緊急アクセス経路の図 (SVG) — 緊急時の 3 層フォールバックを示す図
これらはすべて 「文章だと伝わりにくい構造」を視覚化 したものです。AI と人間の双方が同じ画面を見て話せる状態を作ると、議論が圧倒的にスムーズになります。
まとめ
| 観点 | 文章だけの設計書 | SVG 埋め込み設計書 |
|---|---|---|
| AI に伝わる速度 | 順次読解 + 脳内再構成 | 構造として一目で把握 |
| 部分理解の積み上げ | 起きやすい | 起きにくい |
| 「逆か?」の発生頻度 | 高 | 低 |
| 議論の往復 | 多い | 少ない |
| 引き継ぎコスト | 文章 → 図に書き起こす必要 | そのまま使える |
「文章で順次的に読まれる前提」で書かれていた設計書を、「AI と人間が並んでホワイトボードを見る前提」 に書き換える、というのが今回の発見でした。
SVG を 1 枚増やすコストは数十分ですが、その後の議論コストを大幅に下げてくれます。AI 協業を本気でやるなら、設計書には積極的に絵を入れていきましょう。