フローチャート・シーケンス図・ER図——誰のために書くドキュメントか
2026.06.11執筆者：DigKnow株式会社 CTO 桑原 脩
リポジトリの`docs/`配下や、Confluenceの片隅に、誰も開かなくなったフローチャートのPDFが眠っている——多くの開発現場で、見覚えのある光景ではないでしょうか。シーケンス図のpngも、ER図のdraw.ioも、似た場所で似たように静かに眠っています。書いた人はそれなりに時間をかけたはずなのに、いつの間にか誰のものでもなくなった図たち。あれは結局、誰のために書いていたのでしょうか？
図というドキュメントは、何のために発明されたか
フローチャートやシーケンス図やER図といった「図のドキュメント」は、文章よりも先に発明されたものではありません。むしろ、文章では伝わりにくい構造を伝えるために、後から考え出された道具です。処理の分岐、時間軸上の通信、エンティティ間の関係——これらは文章にすると、どうしても順序立てて読まないとわかりません。読み手の頭のなかに「同時並列の像」を立ち上げてもらうために、平面の上に空間配置する。それが図の本来の仕事でした。
つまり図は、書き手の頭のなかで一度組み立てられた構造を、読み手の頭のなかに同じ形で再現するための翻訳装置として生まれました。書き手と読み手のあいだに「同じ絵」を共有させるために、わざわざ言葉を捨てて記号で書く。図が背負っていたのは、そういう役割だったはずです。
この前提を踏まえると、いま現場に堆積している大量の図に対して、ひとつ素朴な疑問が湧いてきます。あの図たちは、本当に誰かの頭のなかで組み立てられた構造の写しなのでしょうか。
「読まれないフローチャート」が生まれる三つの導線
現場で図が書かれるとき、その動機は意外と限られています。私が見てきた範囲では、だいたい次の三つに収束します。
① レビュー資料として、その場限りで作られる図。
設計レビューや方針会議のために、説明の補助として描かれます。会議のあと、その図は一応Confluenceかリポジトリに残されます。残されますが、一度も再利用されません。書き手にとっての役割は会議が終わった瞬間に終わっており、保存されたのは惰性です。
② 「ドキュメントを残す」という納品要件のために作られる図。
これは特に受託開発や大型案件で多いパターンです。仕様書のテンプレートに「フローチャート」「シーケンス図」「ER図」という章があるから、埋めなければいけない。誰のための図かは問われません。フォーマットを満たしたかどうかだけが問われます。
③ 書き手自身の思考整理のために描かれた図。
これは実は一番質が高いものです。設計の途中で頭がこんがらがったとき、ホワイトボードや紙に書いてみる。書き終わると視界がクリアになります。ただし、この図は書き手のためのものなので、他人に見せるためのチューニングはされていません。それでも残されてしまうと、後から見た人には意味不明な落書きにしか見えなくなります。
この三つには共通点があります。いずれも、特定の読み手の頭に「同じ絵」を再現させるという、図の本来の仕事から少しズレていることです。会議のため、納品のため、書き手本人のため——図は描かれます。でも「三ヶ月後にこのコードを読む誰か」のためには、ほとんど描かれていません。リポジトリの隅で眠る図の正体は、たいていこの三つのどれかが目的を終えたあとの「抜け殻」です。書かれた瞬間に役目を終えていたものが、ファイル名だけ残って漂っているわけです。
図がコードと乖離していくのは、図の宿命でもある
そして、図にはもうひとつ厄介な性質があります。コードよりも、ずっと早く陳腐化することです。
文章の仕様書は、表現が抽象的なぶん、ある程度の変更には耐えます。「ユーザーがログインすると、認証情報を検証してセッションを発行する」という記述は、認証ロジックの内部実装が変わってもしばらく有効です。粒度が粗いから、細部の変化を吸収してくれます。
図はそうはいきません。シーケンス図は登場人物（コンポーネント）が固定されています。ひとつサービスを分割しただけで、矢印の向きと数が変わります。ER図はテーブルを一つ追加しただけで、書き直さないと嘘になります。フローチャートに至っては、if文が一つ増えるだけで分岐が変わります。
図は精密であるがゆえに脆い——これは、図の解像度の高さが裏返しになった性質です。粒度の粗い文章よりも具体的に伝わりますが、その代償として、コードの変化に対する耐性が低い。だから図は、放置すれば必ず嘘をつきます。書いた瞬間が一番正しく、そこから劣化していく宿命を背負っているのです。ここに、AIコーディングが効いてきます。コードの変化頻度が上がれば上がるほど、図と実装の乖離スピードも上がります。手書きの図でこれを追いかけるのは、もう人間の体力の問題として現実的ではありません。
「図を生成すること」は、解決の半分でしかない
最近、コードから図を自動生成するアプローチが、現実的な選択肢として議論されるようになってきました。シーケンス図やフローチャート、ER図をリポジトリの状態から再構築する。ツールも増えています。これは間違いなく前進だと思います。図がコードと乖離する問題のうち、「鮮度」の部分にはかなり効きます。コードを正として、そこから図を引き直せば、嘘をつく図はかなり減らせます。ただ、ここで満足してしまうと、最初の問いに戻ってきません。生成された図は、誰のためのものか、という問いです。自動生成された図は、コードに対して機械的に正確です。一方、「人間がこの図を見て、何を理解したいか」という観点はそこに含まれていません。実際、すべての関数呼び出しを律儀にシーケンス図に展開された結果、ひとつの図に矢印が百本走っているような出力を見たことが何度かあります。それは正確ですが、伝わりません。
図の本来の仕事に戻ると、図は「同じ絵を読み手の頭に再現させる」道具でした。そのためには、何を描いて何を省くかを選ぶ必要があります。重要なフローを際立たせ、瑣末な内部呼び出しは抽象化する。読み手のレベルに合わせて、粒度を切り替える。これは、ただコードをパースしただけでは出てこない種類の判断です。
つまり、「コードから図を起こす」ことができるようになっても、「読み手の頭に同じ絵を再現させる」という図の本懐に届くには、もうひと段階の工夫がいります。何を主役にするか、どこを省くか、どの読み手のための図か——この部分は、まだ人間と機械の協業の設計が定まっていない領域だと思います。
「誰のための図か」を、書く前に決める
整理すると、フローチャート・シーケンス図・ER図というドキュメント形式そのものに罪はありません。罪があるのは、それらの図を「誰のために描くか」を決めずに、形式だけ満たしてしまう運用のほうです。
書く前に、せめて一行でいいから決めてしまうのが、たぶん一番効きます。「この図は、半年後にこのモジュールを初めて触るエンジニアが、五分で全体像をつかむためのものです」——ここまで読み手と用途を絞ると、何を描くか、どの粒度にするか、どこを省くかが決まります。
逆に、読み手が決まっていない図は、たいてい全方位に対して中途半端になります。新人にとっては細かすぎ、ベテランにとっては当たり前のことしか書かれていない。誰の役にも立たない図がリポジトリに溜まっていくのは、こういうメカニズムです。
そしてこれは、AIで自動生成する時代になっても変わりません。むしろ、生成のコストが下がるからこそ、「誰のためか」を最初に決めておかないと、機械が正確な無意味を量産することになります。図の精度が上がるほど、図の意味のなさも目立つようになる、というのは少し皮肉な話だと思います。
まとめ
フローチャート・シーケンス図・ER図は、書き手の頭のなかで組み立てられた構造を、読み手の頭に同じ形で再現させる翻訳装置として発明されました。ところが現場では、レビューの場、納品要件、書き手自身の思考整理——という、本来の仕事から少しズレた目的で描かれることが多くなっています。コードよりも陳腐化が早いという宿命も加わり、リポジトリには誰のためでもない図が静かに堆積していきます。「誰のために描くか」を一行決めてから書く——たぶん、そこからしか変わりません。
あなたのリポジトリで一番最近更新された図は、誰の頭のなかに「同じ絵」を再現させるために描かれたものですか？
次回からは、ドキュメントを書かない・残さないという選択が時間軸でどのような結末を迎えるのか、というテーマに入っていきます。少し怖い話になりますが、順を追って掘り下げていく予定です。