仕様書の図はAIに読ませるな — 軽量コードを添える設計パターン

SHARE

目次

AIと一緒に仕様書を書く

ども！最近AIを使った仕様書作りの検証とかに取り組みだした龍ちゃんです。

「AIと人間の両方で仕様書を効率的に管理するため」にはという課題に取り組んでいた時の内容です。

今回はAIツールを開発に使ってるチームで、仕様書をGitで管理してる人向けの話です。

この記事で話すこと:

  • なぜ仕様書の図はAIに伝わりにくいのか
  • 図解にソースコードを添える設計パターン（3パターン）
  • 実際に試して分かった制約と注意点

まず完成形のイメージを見せます。

<!-- この図のソースコード（AI向け）:
sequenceDiagram
    Client->>+Server: ログインリクエスト
    Server->>+DB: ユーザー照合
    DB-->>-Server: 結果
    Server-->>-Client: トークン発行

設計意図: DB直接参照を避け、サービス層を経由する設計。
理由: テスタビリティとマイクロサービス移行への備え。
-->
![認証フロー図](./images/auth-flow.png)

これはMarkdownファイル（.md）に書きます。リポジトリのdocs/配下に仕様書として置いておくだけ。今はなんとなく雰囲気だけ掴んでもらえればOKです。具体的な書き方は後で3パターン紹介します。

このコメントには3つ詰め込んでます。

  1. 図のソースコード（Mermaid記法）→ AIが構造を正確に読める
  2. 設計意図（なぜこの構造にしたか）→ AIが「なぜ」を理解できる
  3. 注釈（制約や前提条件）→ AIがスコープを把握できる

人間はPNG画像を見るだけで、AIはHTMLコメントの中身を読む。両方が同じファイルに収まることでAIの理解と人間の視認性を確保することができます。

今の仕様書、AIに読める形になってますか？

「仕様書にきれいな図を描いた。シーケンス図、アーキテクチャ図、状態遷移図。人間のレビューは問題なく通る。」

でもこの仕様書、AIに渡したらどうなるか考えたことありますか？

AIは仕様書の図を「推測」で読んでいる

試しに仕様書の図をAIに見せて「この設計について説明して」と聞いてみてください。それっぽい回答が返ってきます。実際には、2つの「推測」が存在しています。

推測その1: 構造の推測

PNG画像からAIが読み取る構造は、厳密ではないです。矢印の方向、条件分岐の条件、サービス間の依存関係。人間なら「見ればわかる」ものも、AIは画像のピクセルから推測しています。シンプルな図なら当たることが多いけど、複雑になるほど精度が落ちます。

推測その2: 意図の推測

仮に構造を正確に読めたとしても、「なぜこの構造にしたのか」は画像のどこにも書いてない。「なぜこの構成にしたのか」「なぜこのサービスを分けたのか」。AIは設計意図を推測するしかない。推測が当たることもあるけど、外れることもある。

つまりAIは、構造も意図が含まれていなければ推測が入ります。これからAI駆動開発を始めたい人も、既にやってる人も、ここがボトルネックになります。

じゃあ全部テキストで書けばいい？

テキストだけの仕様書だと人間が読むのがしんどいんですよね。構造が一目でわからない。フローの分岐とか、サービス間の依存関係とか、図解があるから仕様書として機能してる部分があります。

推測をなくすには

ここにジレンマがあって。

  • 人間のためにはPNG画像がほしい
  • AIのためにはテキスト（Mermaid/PlantUMLコード + 設計意図）がほしい

ソースコードを添えれば構造の推測がなくなる。設計意図を書いておけば意図の推測がなくなる。この2つをセットで、同じファイル内に持たせる方法があります。次のセクションで具体的に見せます。

図解にソースコードを添える — 人間の視認性とAIの理解を両立する

ここからが本題です。

やることはシンプルで、Markdownの仕様書内で図のPNG画像の直前に、HTMLコメントとして以下を書く。

  1. Mermaid/PlantUMLのソースコード — 図の構造そのもの
  2. 設計意図 — なぜこの構造にしたか
  3. 注釈（必要なら）— 異常系の考慮、将来の拡張方針など

人間の視認性とAIの理解、両方を1つのファイルで実現する方法です。

なぜHTMLコメントなのか

Markdownの中にHTMLコメント（<!-- -->）を書くと、GitHubやドキュメントビューアで表示されない。人間がドキュメントを読むときには見えないんですよね。

でもAI（Claude CodeやCopilot等）がファイルを読むときは、HTMLコメントの中身もテキストとして見える。

つまり「人間には見えないけどAIには見える」メモ欄として機能する。人間は画像を見る。AIはコメントの中身を読む。お互い干渉しない。

リポジトリに置くだけでいい

自分がこのパターンを気に入ってる理由は、「食わせる（AIへのコンテキスト注入）」作業が簡単になるという点です。

GitリポジトリのMarkdownにHTMLコメント付きで置いておくだけで、Claude Codeが勝手に読んでくれる。Claude Codeはプロジェクトのリポジトリ内のファイルを直接参照できるので、わざわざプロンプトに貼り付ける必要がない。RAGの仕組みを作る必要もない。リポジトリにあるドキュメントをAIが自然に参照できる状態にしておくだけ。

これは自分が以前書いた「AIフレンドリーなドキュメント管理」や「調査→構造化→注入の設計パターン」の記事と同じ考え方です。テキストドキュメントをリポジトリに集約するアプローチの「図解版」ですね。

「それ、二重管理じゃない？」

この後のパターン集では ![認証フロー](./images/auth-sequence.png) のようにPNG画像を参照する形で書いてます。「ソースコードとPNG画像の両方を管理するのは二重管理では？」という疑問が出ると思います。

結論から言うと、PNG画像が必要になるタイミングとソースコードが必要になるタイミングは別なので、問題にならないかなと考えています。

  • エンジニア同士で設計を進めるフェーズでは、Mermaid/PlantUMLのソースコード + テキスト注釈だけで十分。AIも読める。ここでは図の記法で爆速で構造を整理していくことに集中すればいい
  • PNG画像が必要になるのは、非エンジニア（お客さん、品質管理チームなど）に資料を出すタイミング。その瞬間にソースコードから生成すればいい
  • 生成はMermaid CLIやPlantUML Web Service・HTML＋Claude Codeを使用して自動化できる

管理するのはソースコードだけ。PNG画像は必要なときに生成する出力物。二重管理ではなく「ソースが1つ、出力が必要なときに作る」という発想です。Claude Codeを使えばMermaidもPlantUMLも爆速で書けるので、ソースコードの作成・修正も苦になりません。具体的な方法は以下の記事で解説しています。

Mermaid/PlantUMLを知らなくても始められる

記法を知らないから無理、と思った人もいるかもしれません。でもAIに「この図のMermaidコードを書いて」と頼めば書いてくれます。既存のPNG画像を渡して「このPNG画像をMermaid記法に変換して」という方法もあります。

入門（ソースコード作成）

発展（見た目カスタマイズ + PNG変換）

記法の習得はあとからで大丈夫です。最初の一歩としては、設計意図のコメントを書くところから始めてみてください。

実装パターン集

ここからは具体的なコードサンプルを3つ見せます。全部コピペして使えます。自分の仕様書に近いパターンを選んでください。

  • パターン1: シーケンス図（API設計書の認証フローなど）
  • パターン2: アーキテクチャ図（マイクロサービス構成など）
  • パターン3: 状態遷移図（注文ステータス管理など）

まず: Mermaid と PlantUML どっちを使う？

ソースコードの記法は2種類あります。迷ったらこの表で判断してください。

こういう図ならこっちを使う
フローチャート、簡易シーケンス図、状態遷移、ER図Mermaid
アクティビティ図、ユースケース図、コンポーネント図PlantUML
UML準拠が求められる設計書PlantUML
10ノード以上の大規模な図PlantUML

迷ったらMermaidで始めて、限界を感じたらPlantUMLに切り替えればいい。AIとの相性はMermaidが最高、PlantUMLも高い。どちらを選んでもAIは読み取れます。

パターン1・3はMermaid、パターン2はPlantUMLで書いてます。使い分け表の通り、コンポーネント構成はPlantUMLのほうが得意です。

設計意図の書き方

パターンに入る前に1つだけ。前のセクションではHTMLコメントに「何を入れるか」（ソースコード・設計意図・注釈）を説明しました。ここでは設計意図の「書き方」の話です。ソースコードだけ貼っても、AIは構造は読めるけど「なぜ」がわからない。コメント内に最低限書くべきはこの3つ。

  1. 設計意図: なぜこの構造にしたか（1-2行）
  2. 制約・前提: この設計が成り立つ条件（あれば）
  3. スコープ外: この図が扱わない範囲（あれば）

全部書く必要はないです。「なぜ」だけでも十分価値がある。以下の3パターンで書き分けの実例を見せます。

パターン1: シーケンス図 + 設計意図コメント

ユースケース: API設計書の認証フロー

<!-- AI向けソースコード:
sequenceDiagram
    Client->>+API Gateway: POST /auth/login
    API Gateway->>+Auth Service: validateCredentials()
    Auth Service->>+User DB: findByEmail()
    User DB-->>-Auth Service: User
    Auth Service-->>-API Gateway: JWT Token
    API Gateway-->>-Client: 200 OK + Token

設計意図: Gateway がトークン発行の責務を持たず、Auth Service に委譲。
理由: 認証ロジックの変更（OAuth追加等）時に Gateway を触らなくて済む。
注意: Rate Limiting は Gateway 側で実装。Auth Service には到達しない前提。
-->
![認証フロー](./images/auth-sequence.png)

上記のソースコードから生成した図がこちら。右側の注釈パネルは、HTMLコメント内の設計意図をビジュアル化したもの。

  • 人間が見るもの: きれいなシーケンス図の画像
  • AIが読むもの: Mermaidコード + 「なぜGatewayがトークンを発行しないか」の設計意図
  • 制約: Mermaidシーケンス図は4参加者・8メッセージ以下が読みやすい（検証済み）

パターン2: アーキテクチャ図 + 責務定義コメント

ユースケース: システム構成書のマイクロサービス構成

<!-- AI向けソースコード:
@startuml
package "Frontend" {
  [SPA - React] as SPA
  [BFF - Next.js] as BFF
}
package "Backend" {
  [Auth Service] as Auth
  [User Service] as User
  [Order Service] as Order
}
package "Data" {
  database "User DB" as UserDB
  database "Order DB" as OrderDB
  database "Redis Cache" as Cache
}
SPA --> BFF
BFF --> Auth
BFF --> User
BFF --> Order
Auth --> UserDB
User --> UserDB
User --> Cache
Order --> OrderDB
Order --> Cache
@enduml

責務定義:
- BFF: フロントエンド専用のAPI集約層。バックエンドサービスへの直接アクセスを防ぐ
- Auth Service: 認証・認可のみ。ユーザー情報の参照はUser Serviceに委譲
- Cache: Read-through パターン。書き込みはDB直接
技術的制約: サービス間通信は gRPC。BFF→Backend のみ REST
-->
![システム構成図](./images/architecture.png)

上記のソースコードから生成した図がこちら。責務定義が右側の注釈パネルに対応している。

  • 人間が見るもの: マイクロサービスの全体像が一目でわかる構成図
  • AIが読むもの: PlantUMLコード + 各サービスの責務定義 + サービス間の通信方式 + キャッシュ戦略
  • PlantUMLの利点: database や queue の専用記号が使える。パッケージでレイヤーを明示できる

パターン3: 状態遷移図 + 異常系注釈コメント

ユースケース: 業務フロー仕様書の注文ステータス管理

<!-- AI向けソースコード:
stateDiagram-v2
    [*] --> 注文受付
    注文受付 --> 在庫確認中
    在庫確認中 --> 決済処理中: 在庫あり
    在庫確認中 --> キャンセル: 在庫なし
    決済処理中 --> 出荷準備中: 決済成功
    決済処理中 --> 決済エラー: 決済失敗
    決済エラー --> 決済処理中: リトライ(最大3回)
    決済エラー --> キャンセル: リトライ上限超過
    出荷準備中 --> 出荷済み
    出荷済み --> 配達完了
    配達完了 --> [*]
    キャンセル --> [*]

異常系の設計:
- 決済エラー → リトライは最大3回。exponential backoff（1秒→2秒→4秒）
- 在庫なし → 即キャンセル。仮押さえはしない設計（在庫ロック競合を避ける）
- 出荷後のキャンセル → この図の範囲外。返品フローは別仕様書を参照
-->
![注文ステータス遷移図](./images/order-state.png)

上記のソースコードから生成した図がこちら。正常系（青）と異常系（赤）を色で区別している。

  • 人間が見るもの: 注文の正常系・異常系が一目でわかる状態遷移図
  • AIが読むもの: 状態遷移のルール + 異常系のリトライ戦略 + スコープ外の明示
  • 制約: 状態遷移図は8-10状態が上限（検証済み。それ以上は縦に伸びて見切れる）

3つのパターンに共通しているのは、ソースコードだけでなく「なぜ」を書いていること。パターン1は設計意図、パターン2は責務定義、パターン3は異常系の設計判断。AIが読んで「この設計の理由」まで理解できる状態にしてます。

実際に試して分かったこと

ここまでのパターンを実際に検証して分かった注意点を2つ共有します。

ノード数の上限は思ったより低い

Mermaidで図を描くとき、ノード（箱や状態）を増やしすぎると自動縮小されて文字が読めなくなります。1280x720pxの描画領域で検証した推奨上限はこれです。

図の種類推奨上限
フローチャート8-10ノード
シーケンス図4参加者・8メッセージ
状態遷移図8-10状態

上限を超えたら図を分割してください。1つの図に全部詰め込みたくなる気持ちはわかるけど、分割したほうが人間にもAIにも読みやすい。

PlantUMLはサーバー側で描画するので、Mermaidほど厳しくないです。10ノード以上の大規模な図が必要なら、PlantUMLのほうが安全。

本当にAIが読み取れるのか？ — 試してみてほしい

「HTMLコメントをAIが読めるって言うけど、本当に？」と思った人へ。自分で試すのが一番早いです。

  1. パターン1のMarkdownをそのままファイルに保存する
  2. Claude Code（またはお好みのAIツール）にそのファイルを読ませる
  3. 「この仕様書の認証フローについて説明して。設計意図も含めて」と聞く

HTMLコメント内の設計意図まで含めて回答してくれるはずです。「GatewayはRate Limitingだけを担当し、トークン発行はAuth Serviceに委譲しています」みたいな回答が返ってきたら、AIがコメントの中身を正確に読み取れている証拠。

やってみてください。

まとめ

仕様書の図を「人間だけが読むもの」から「人間とAIが読むもの」にする。やることはシンプルです。

図のPNG画像の横に、HTMLコメントでソースコードと設計意図を添える。

Mermaid/PlantUMLを使えば、AIが推測ではなく正確に設計構造を理解できる。設計意図を書いておけば「なぜこの構造にしたか」まで伝わる。

「AIに仕様書を食わせる」んじゃなくて、AIが自然に読める仕様書をリポジトリに置いておく。これだけ。

これは仕様書を書いてる人にしかできないことです。設計意図を知っているのは仕様書の著者だけだから。このパターンをチーム内で共有しておくと、AIを使ったレビューやコード生成で「設計の意図を汲んだ」出力が得られるようになります。

まずは1つの図から試してみてください。

ほなまた。

関連ブログ・参考リンク

関連ブログ

参考リンク

ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？

役に立った 役に立たなかった

0人がこの投稿は役に立ったと言っています。
エンジニア募集中!

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

前の記事

PlantUMLの表現力をTailwind CSSで設計書品質…

次の記事

【2026年2月】OSSサポートエンジニアが気になった！OSS…