flowchart LR
subgraph Input["💭 曖昧な設計"]
D[設計説明]
end
AI[🤖 AI]
subgraph Output["🔍 可視化された問題"]
F1[矢印多すぎ]
F2[責務重複]
F3[循環依存]
end
D --> AI
AI --> F1
AI --> F2
AI --> F3
style Input fill:#fff3e0
style Output fill:#ffebee
コードは書けるのに、説明できない
「ここの処理、図にしてもらえますか？」
設計レビューでこう頼むと、意外と固まる人が多い。
コードは書ける。動いている。テストも通っている。でも「図にして」と言われると、急に手が止まる。
ホワイトボードの前で、マーカーを持ったまま「えーと、まずここからリクエストが来て…いや、その前にこっちの処理があって…」と迷走が始まる。
私は長年、業務システムの設計レビューをやってきた。そして気づいたことがある。
図を書けない設計は、だいたいその人自身も理解していない。
コードは書ける。動く。でも「なぜそう書いたのか」「何がどこに依存しているのか」が頭の中で整理されていない。だから図にできない。
最近、私はAIに図を書かせるようになった。ClaudeやChatGPTに「この設計を図にして」と頼む。Mermaid記法で出力させて、プレビューする。
そうしたら、面白いことが起きた。
設計の粗が、残酷なほど可視化されるのだ。
なぜ「図」にすると粗が見えるのか
言葉で説明するときと、図にするときでは、要求される「理解の精度」が違う。
言葉は曖昧さを許容する。
「このサービスがデータを処理して、結果を返します」
これで説明が通ってしまうことがある。聞き手も「なんとなく分かった」気になる。
でも図にしようとすると、曖昧さが許されない。
- 「このサービス」とは何か？ 四角を1つ書くのか、3つ書くのか？
- 「データを処理して」の「データ」はどこから来るのか？ 矢印をどこから引くのか？
- 「結果を返す」のは誰に？ 矢印の先は？
図は、構造を強制的に明示させる。曖昧なままでは、四角も矢印も書けない。
言葉と構造のズレ
よくあるのが、「言葉では1つに見えるものが、実際は3つだった」パターンだ。
「注文サービスがあって…」
図にしようとすると、
- 注文を受け付けるAPI
- 注文データを保存するロジック
- 注文完了を通知する処理
これ、全部「注文サービス」の中に入っているのか？ それとも別々のコンポーネントなのか？
言葉だと1つに聞こえていたものが、図にすると「これ、分けるべきでは？」という疑問が湧いてくる。
境界が曖昧な責務
もう1つよくあるのが、「責務の境界が図にすると重なる」問題だ。
「認証サービスと、ユーザーサービスがあって…」
図にしようとする。
- 認証サービスはログイン処理を担当
- ユーザーサービスはユーザー情報を管理
でも、「ユーザーのパスワード」はどっちが持つ？ 「ログイン履歴」は？ 「セッション管理」は？
図を書こうとすると、2つの四角の間に置くべきか、どちらかに入れるべきか、判断を迫られる。そして、その判断ができないということは、設計段階で責務の境界が曖昧だったということだ。
AIに図を書かせると、何が起きるか
ここでAIの出番だ。
私は最近、設計を説明するときに「まずAIに図を書かせる」というプロセスを入れている。自分の設計をAIに説明し、「これを図にして」と頼む。
AIは素直だ。人間のように「なんとなく察する」ことをしない。
AIは「理解したふり」をしない。
だから、設計の穴がそのまま図に出る。
違和感1：矢印が多すぎる
AIが出力した図を見て、最初に感じることが多いのがこれだ。
「矢印、多くない？」
自分では「シンプルな設計」だと思っていたのに、図にすると矢印が縦横無尽に走っている。AがBを呼び、BがCを呼び、CがまたAを呼んでいる。
これは「依存関係が複雑になりすぎている」というサインだ。
矢印の数は、コンポーネント間の結合度を可視化する。矢印が多いということは、1つを変更したときの影響範囲が広いということ。
自分で図を書くと、無意識に矢印を省略してしまうことがある。AIは省略しない。だから現実が見える。
違和感2：責任範囲が重なっている
AIは、説明された通りに四角を描く。
「注文サービスが在庫を確認して…」と言えば、注文サービスから在庫への矢印を引く。 「在庫サービスも注文データを参照して…」と言えば、在庫サービスから注文への矢印を引く。
結果、双方向の矢印が発生する。
これを見て「あれ、これって責務が重なってないか？」と気づく。
どちらが「データの所有者」なのか。どちらが「問い合わせる側」で、どちらが「答える側」なのか。
双方向矢印は、設計の責務境界が曖昧なサインだ。
違和感3：登場人物が多すぎる
AIに図を書かせると、自分が説明の中で言及したコンポーネントが全部出てくる。
「APIゲートウェイがあって、認証サービスがあって、注文サービスがあって、在庫サービスがあって、通知サービスがあって、ログ収集があって、監視があって…」
図にすると、四角が10個並ぶ。
「これ、1つの画面に収まらないな」と思った時点で、設計が複雑すぎる可能性がある。
もちろん、大規模システムなら登場人物が多いのは当然だ。でも「この機能を説明するのに10個のコンポーネントが必要」なら、それは抽象化のレベルを間違えているかもしれない。
実際に気づける設計の問題
AIに図を書かせて気づいた、具体的な設計問題をいくつか紹介する。
問題1：Producer / Consumer の責務混在
あるバッチ処理の設計をAIに図にしてもらった。
出てきた図を見ると、1つのコンポーネントから矢印が5本出ていた。データを取得し、加工し、キューに入れ、結果を保存し、通知を送る。全部1つの箱の中でやっていた。
「これ、Producerの責任範囲を超えてないか？」
Producerは「キューにメッセージを入れる」までが責任のはずだ。その後の処理はConsumerの仕事だ。
図を見て初めて、「この設計、責務が混在している」と気づいた。言葉で説明しているときは、流れを追うのに必死で、責務の境界を見失っていた。
問題2：同期・非同期の境界が不明
別の設計をAIに図にしてもらったときのこと。
出てきた図は、全部の矢印が同じスタイルだった。でも実際には、ある部分は同期呼び出し、ある部分はキュー経由の非同期処理だった。
「この図、同期と非同期の区別がつかないな」
AIに「同期呼び出しと非同期呼び出しを区別して」と頼んだ。すると、図の中に2種類の矢印が現れた。
そこで気づいた。同期と非同期が混在しすぎている。
ユーザーのリクエストを受けて、一部は同期で処理し、一部は非同期でキューに流す。でもその境界が明確じゃない。どこまでが「ユーザーを待たせる処理」で、どこからが「バックグラウンドに回していい処理」なのか。
図にしたことで、この境界を意識的に設計し直す必要があると分かった。
問題3：循環依存
これは図にしないと絶対に気づかなかった問題だ。
サービスA → サービスB → サービスC → サービスA
矢印が一周して戻ってきている。
言葉で説明しているときは気づかなかった。「AがBを呼んで」「BがCを呼んで」「Cは結果を返すためにAの情報を参照して」——それぞれは自然に聞こえる。
でも図にすると、明らかに循環している。
循環依存は、デプロイの順序問題、テストの困難さ、変更影響の予測困難など、あらゆるトラブルの温床になる。図にしていなければ、本番で障害が起きるまで気づかなかったかもしれない。
人間がやること、AIに任せること
AIに図を書かせることの価値が分かったところで、役割分担を整理しておこう。
AIに任せること：可視化
AIは「説明を図に変換する」作業が得意だ。
- 言葉で説明した設計をMermaid記法に変換する
- 複数の説明から一貫した図を作る
- 「もっと詳細に」「もっと抽象的に」とレベルを変えた図を作る
これらは人間がやると時間がかかる。AIなら数秒だ。
私は最近、設計ドキュメントを書くときに「まずAIに図を3パターン出させる」ことをやっている。概要レベル、詳細レベル、データフローレベル。そこから良いところを組み合わせて、最終的な図を作る。
人間がやること：判断
AIが出した図を見て「これはおかしい」と判断するのは人間の仕事だ。
- 「矢印が多すぎる」→ 設計を見直すべきか判断する
- 「責務が重なっている」→ どう分割するか決める
- 「循環している」→ どこを切るか選択する
AIは問題を可視化してくれる。でも「それが本当に問題なのか」「どう解決すべきか」は人間が決める。
これは設計レビューの本質と同じだ。レビューアは問題を指摘する。でも最終的にどうするかは、設計者が判断する。
AIは「疲れないレビューア」として使える。何度でも図を書き直してくれる。何度でも指摘してくれる。遠慮もしない。
私の使い方
具体的に、私がどうAIを使っているか紹介する。
ステップ1：雑に説明する
まず、設計を口頭で説明するように、雑にテキストで書く。
注文が入ったら、在庫を確認して、OKなら決済して、
完了したらメール送って、分析用のログも残したい
これをAIに投げて「図にして」と頼む。
ステップ2：出てきた図を見て違和感を探す
AIが出した図を眺める。
「あれ、全部同期処理になってる」 「メール送信が注文APIの中に入ってる」 「分析ログへの矢印、ここから出るの変じゃない？」
違和感を言語化する。
ステップ3：設計を修正して、もう一度図にする
違和感をもとに設計を見直す。
「メール送信は非同期にしよう。キューを挟む」 「分析ログは別のConsumerにしよう」
修正した設計を再度AIに説明し、図を出させる。
ステップ4：図がすっきりするまで繰り返す
図を見て、まだ違和感があれば繰り返す。
最終的に「この図なら、人に説明できる」と思えたらOK。
このプロセス自体が、設計のブラッシュアップになっている。AIと対話しながら、自分の理解を深めている。
まとめ：図を書かせる＝設計をテストすること
AIに図を書かせることは、設計のテストだ。
コードを書いたらテストを走らせる。設計を考えたらAIに図を書かせる。
テストが失敗したら、コードに問題がある。図が変になったら、設計に問題がある。
AIは正直だ。「なんとなく良さそう」で誤魔化してくれない。説明が曖昧なら、曖昧な図が出てくる。責務が混在していれば、矢印がぐちゃぐちゃになる。
図を書けない設計は、たぶん動かない。動いても、保守できない。
だから私は、設計を考えたら必ずAIに図を書かせる。それが、一番手軽で、一番正直な設計レビューだから。
やってみよう
今日からできることを1つ提案する。
今作っている機能の設計を、AIに図にしてもらおう。
やり方は簡単だ。
- AIに「以下の設計を図にして」と頼む
- 自分の設計を、説明するように書く
- 出てきた図を眺める
違和感があったら、それが設計の粗だ。
違和感がなければ、その設計は少なくとも「図にできる程度には整理されている」ということ。
5分でできる。でも、その5分で「本番障害の芽」を1つ潰せるかもしれない。
試してみてほしい。
設計判断の背景
手書きや専用ツールではなく「AIに図を書かせる」という方法を選んだのには理由がある。手書きは早いが、無意識に都合の悪い部分を省略してしまう。専用ツールは綺麗だが、図を整えることに時間を使いすぎて本来の目的を見失いやすい。AIに任せると「説明した通りにしか書かない」ので、自分の理解度がそのまま図に出る。設計のセルフチェックとしては、この「容赦のなさ」が一番役に立つ。
現場での判断基準
設計レビューでは「図を書いてもらえますか」を最初の質問にしている。これは意地悪ではなく、お互いの時間を節約するためだ。図にできない設計は、言葉で説明してもらっても結局どこかで齟齬が生じる。逆に、図がすっきり書ける設計は、実装時のトラブルも少ない傾向がある。経験上、図にするのに10分以上かかる設計は、実装にも想定外の時間がかかることが多かった。
見るべきポイント
図を見るときは、まず「矢印の方向」と「矢印の数」を確認する。双方向の矢印は責務境界の曖昧さ、1つのボックスから出る矢印が3本以上なら責務の集中を疑う。次に「図に出てこなかったもの」を考える。エラー処理、リトライ、タイムアウトなど、正常系だけで図を書いていないか。これらが図に含まれていない設計は、異常系で破綻することが多い。