この記事のポイント
- 生成AIに設計書を渡して実装やレビューを任せると、書き方があいまいなほど見当違いの答えが返ってきます。人間なら行間を補って読んでくれますが、AIはそこまで気を利かせてくれないためです。
- 効くのは特別なテクニックではなく、「あいまいさを減らす」という地味な工夫です。本記事では、(1) 見出しや表で文書の構造をはっきりさせる、(2) 同じ事実は1か所だけに書く、(3) 紛らわしい言葉は最初に意味を決めておく、の3つのポイントに整理しました。
- なぜAIが読み違えるのかも、できるだけ専門用語をかみくだいて説明します。理由が分かると、どこから直せばよいかが見えてきます。
- 各ポイントには「なぜ効くのか」「直す前と後の例」「やりすぎたときの注意点」を添えました。図と表の使い分けや、誰にとっても読みやすくする配慮にも触れます。
- これらは結局、人間にとって読みやすい書き方とほぼ同じです。「AI向けに身構える」というより、読み手にAIも加わっただけ、と考えると気楽に取り組めます。
はじめに
この記事は、生成AIに設計を渡して実装・レビュー・要約を任せ始めた方に向けて、曖昧さを消す設計書の書き方を扱います。軸は3つです。曖昧さを消す構造、事実の単一ソース化、用語の定義。読むと、何がAIを混乱させるのか、なぜそれが起きるのか、どこを直すと効くのか、どこで過剰にやりすぎるのかが分かるようにまとめました。
複数の事業や案件を並行して進めていると、設計書が一箇所にまとまらなくなりがちです。ある仕様はノート系のSaaSに、別の決定事項はドキュメントツールに、APIの細かい挙動はローカルのMarkdownに、という具合に散らばっていきます。私自身、同じ「正しい仕様」を3か所で見つけて、どれが最新か分からず手が止まった経験があります。
ここに生成AIが加わると、問題が一段はっきりします。人間なら「たぶんこっちが新しい」「この前提は暗黙に共有されている」と補ってくれます。生成AIは、渡された文書をかなり素直に受け取ります。曖昧なら曖昧なまま、矛盾していれば矛盾を抱えたまま、それらしい実装やレビューを返してきます。
扱う範囲をはっきりさせておきます。特定のAIエージェント製品の使い方や、RAGパイプラインの実装には踏み込みません。Markdown・Mermaid・静的サイトジェネレータといった、どの環境でも応用しやすい一般的な手法に絞ります。ベストプラクティスは状況依存なので、断定はできるだけ避け、「私はこうした」「こういう傾向がある」という形で書きます。異論や別解は歓迎します。
前提・実行環境
- ドキュメント形式: Markdown（GitHub Flavored Markdown 系を想定）
- 図: Mermaid v11 系（バージョンにより記法差があるため、手元の対応状況を確認してみてください）
- 静的サイト: MkDocs + Material for MkDocs を例に挙げますが、Docusaurus 等でも考え方は同じです
- 生成AI: 特定製品に依存しない一般的な大規模言語モデルを想定
生成AIが設計書を読み違える典型パターン
直し方の前に、まず「何が起きているか」を見ます。原因が分かると、直す優先順位が決めやすくなります。私が実際に遭遇した、あるいは検証用の架空プロジェクトで再現できたパターンを挙げます。
パターン1: 構造がフラットで、どこが見出しか分からない
見出し記号を使わず、太字や全角の装飾だけで章立てした文書は、人間なら視覚で区切りを読み取れます。生成AIにとっては、ただのテキストの羅列に近づきます。「ここからが認証の話」という境界が曖昧になり、前のセクションの前提を引きずったまま回答を作ることがあります。
パターン2: 同じ事実が複数箇所にあり、しかも食い違う
「タイムアウトは30秒」と書いた箇所と「タイムアウトは60秒」と書いた箇所が、別ファイルに同居しているケースです。人間は「最近の議事録のほうが正しいだろう」と推測します。生成AIは、両方を根拠として扱ったり、片方だけ拾ったりします。どちらを拾うかは入力の与え方で変わるため、再現性のないバグの温床になります。
パターン3: 用語が定義されないまま、独自の意味で使われる
たとえば「ユーザー」が、ある節ではログイン済みの会員を、別の節では未登録の訪問者を指している場合です。生成AIは一般的な語義で補完しがちなので、設計者の意図とずれます。略語（たとえば架空の「PCS」のような社内用語）が定義なしで出てくると、まず一般的な展開を当てはめて誤読します。
パターン4: 前提と制約が本文に溶けている
「この設計は1日10万リクエストまでを想定」という前提が、本文の途中にさらりと書かれているだけだと、生成AIはそれを設計の中心的な制約として重み付けしにくくなります。結果、想定を超えるスケールの実装案を平然と返してくることがあります。
パターン5: 図が画像で、中身が読めない
構造図をPNGやスクリーンショットで貼ると、その図に含まれる関係性の情報は、テキストとしては失われます。図のキャプションが薄いと、生成AIはその図から手がかりを得にくくなります。人間の読者にとっても、図の中の文字が検索に引っかからない、コピーできない、という不便があります。
これらに共通するのは、人間の補完力を前提にした省略です。逆に言えば、補完に頼っている箇所を明示に変えるのが、整える作業の核になります。次章で、なぜこうした省略がAIに効くのかを少し掘り下げてから、3つのポイントに進みます。
なぜ生成AIは曖昧な文書を読み違えるのか
「AIは曖昧に弱い」と言うと当たり前に聞こえます。なぜそうなるのかを、トークン化・文脈窓・確率的補完という3つの観点で一段だけ掘っておくと、直し方の納得感が変わります。私の理解の範囲で、断定しすぎない形で整理します。
観点1: 確率的補完 ― 空白を「それらしさ」で埋める
大規模言語モデルは、与えられた文脈から次に来る語をもっともらしく予測します。設計書に空白（書かれていない前提）があると、その空白を一般論で埋めます。たとえば「ユーザー」という語に明示がなければ、世間一般でよくある「ログイン済みの利用者」あたりを当てはめます。これは賢い補完ですが、設計者の意図と一致する保証はありません。明示された定義があれば、補完に頼る余地が減り、ずれも減らせます。
ここが重要な点です。生成AIは「分かりません」と立ち止まるより、確率的にもっともらしい解を返す傾向があります。つまり、曖昧さは「質問」ではなく「補完」として処理されやすいわけです。明示された定義があれば、補完の出番がなくなり、ずれが減ります。これが後述の「用語定義」が効く理由の土台になります。
観点2: トークン化 ― 構造の記号は「読み方の地図」になる
モデルは入力をトークン（語や記号の断片）に分割して処理します。見出し・箇条書き・表といったMarkdownの記号は、人間にとっての視覚的な区切りであると同時に、モデルにとっても文書の構造を示すトークン列になります。階層を順に刻んだ見出しは、概念どうしの関係（どれが親で、どれが子か）を伝える手がかりになると、複数の解説が指摘しています(Webex Developers Blog）。
逆に、装飾だけで作った擬似見出しは、構造のトークンとしては機能しにくくなります。なお、同じ本文でもHTMLのようにタグや属性が多い形式は、開始・終了タグや属性のぶん冗長になり、Markdownよりトークン数が増える場合があると報告されています(file2markdown Blog）。トークンを無駄に使わず、かつ構造を伝えられる点が、Markdownが好まれる理由の1つです。
観点3: 文脈窓 ― 真ん中の情報は見落とされやすい
モデルが一度に扱えるトークン数（文脈窓）には上限があります。さらに、窓に収まっていても、入力の中央付近に置かれた情報は見落とされやすいという報告があります。Liuらの研究は、関連情報が入力の先頭か末尾にあるとき性能が高く、中央にあると性能が大きく下がる傾向を示しました(Liu et al., 2023）。性能が先頭・末尾で高く、中央で下がる、U字型の傾向として観測されることがあります。
この性質は、設計書の書き方に直接効きます。前提・制約・用語といった「最初に効いてほしい情報」は、本文の中ほどに埋めず、冒頭にまとめて置くほうが拾われやすくなります。後述する「メタ情報を先頭に置く」「前提と制約を専用の節に出す」は、この観点に基づく工夫です。
ここで挙げた性質は、モデルの世代や実装によって程度が変わります。最新の長文脈モデルでは中央の見落としが緩和されているという報告もあります。「常にこうなる」と決めつけず、「曖昧さや分散は、こうしたリスクを増やしやすい」という傾向として捉えるのが安全です。
ここまでが背景です。次に、これらの観点に対応する3つのポイントを見ていきます。
3つのポイントで曖昧さを消す
直し方は数多くありますが、効きどころは次の3本に集約できます。前章の3観点に、それぞれ素直に対応します。
| ポイント | 何をするか | 主に効く観点 |
|---|---|---|
| ポイント1: 曖昧さを消す構造 | 見出し階層・箇条書き・表で骨格を記号化する | トークン化・文脈窓 |
| ポイント2: 単一ソース化 | 同じ事実を1か所に集約し、他はリンク参照 | 確率的補完（揺れの除去） |
| ポイント3: 用語定義 | 固有の意味を持つ語を冒頭で定義する | 確率的補完（補完の抑止） |
図と表の使い分け、前提・制約の明記、アクセシビリティは、この3つのポイントを支える共通の作法として後段でまとめて扱います。
ポイント1: 曖昧さを消す構造
効く理由
見出し階層・箇条書き・表は、文書の骨格を記号として表に出す手段です。前章のトークン化・文脈窓の観点で言えば、構造の記号は「どこからどこまでが1つの話か」「どれが親でどれが子か」をモデルに伝えるトークン列になります。見出しの階層を飛ばさず順に刻むこと、各セクションが単独で読んでも意味が通ること（セクションの自己完結性）が、解釈精度に効くと複数の解説が指摘しています(Fern, Webex Developers Blog）。
セクションの自己完結性は、検索拡張（RAG のような）構成でも効きます。文書を断片に分けて渡す場合、断片が自己完結していないと、切り出された瞬間に意味が崩れます。見出し単位で完結させる書き方は、この崩れを防ぐ効果があります。
Before / After（見出しを意味の階層として刻む）
装飾ではなく、意味の入れ子を見出しレベルで表現します。h1 は文書に1つ、その下に h2、さらに下に h3、と順に下ります。レベルを飛ばさないのが要点です。
雑な例から見ます。
# 決済設計
決済の全体像です。
**カード決済について**
外部の決済プロバイダを使います。失敗時はリトライします。
**リトライ**
3回までです。
この書き方だと、「リトライ」がカード決済の下位なのか、決済全体の話なのかが曖昧です。太字は見出しではないので、構造としては全部が同じ階層に見えます。
意味の階層を見出しで表すと、こうなります。
# 決済設計
## 全体像
本書はオンライン決済の処理フローと制約を定義します。
## カード決済
外部の決済プロバイダ（例: example-pay）を利用します。
### リトライ方針
通信失敗時は最大3回までリトライします。
ビジネス上の二重課金を避けるため、冪等キーを必須とします。
見出しを追うだけで「決済設計 > カード決済 > リトライ方針」という入れ子が読み取れます。人間にとっての目次が、そのまま生成AIにとっての構造ヒントになります。
表で属性を固定する
項目ごとに属性が並ぶ仕様は、表が向きます。文章で「タイムアウトは30秒で、リトライは3回、認証は必須」と書くより、表のほうが生成AIも人間も拾いやすくなります。Markdownの表は、構造が保たれた軽量なテキストとして扱える点が利点です(file2markdown Blog）。
文章で書いた例です。
注文APIはPOSTで、認証が必要で、タイムアウトは30秒です。
取得APIはGETで、認証は任意で、タイムアウトは10秒です。
これを表にします。
| エンドポイント | メソッド | 認証 | タイムアウト | 冪等性 |
|---|---|---|---|---|
| `/orders` | POST | 必須 | 30秒 | 必要（冪等キー） |
| `/orders/{id}` | GET | 任意 | 10秒 | 不要 |
属性の軸（メソッド・認証・タイムアウト）が列として固定されるので、項目が増えても比較しやすくなります。生成AIに「認証が必須のエンドポイントは?」と尋ねたとき、表があると正確に拾いやすくなります。
落とし穴: 過剰構造化
すべてを表と見出しに分解すると、かえって読みにくくなります。数行で済む補足まで表にすると、視線が細切れになります。散文で流れを説明したほうが伝わる箇所もあります。構造化は手段で、目的は「伝わること」です。1〜2項目しかない表や、中身が1行の見出しは、たいてい過剰のサインです。人間が読みにくいほど構造化された文書は、トークンも無駄に増えやすく、AIにとっても親切とは限りません。
ポイント2: 単一ソース化（Single Source of Truth）
効く理由
同じ事実は1か所だけに置き、他の場所からはリンクで参照します。前章の確率的補完の観点で言えば、事実が複数箇所にあると、モデルがどれを根拠に使うかは入力の順序や量で揺れます。これがパターン2を「再現性のないバグ」にする理由です。
ここがこのポイントの肝です。曖昧さを後工程の検証で潰すより、構造の段階で「揺れる対象そのもの」を消すほうが、コストが小さくなります。複製をやめれば、矛盾は構造的に発生しなくなります。
Before / After（再掲をリンクに置き換える）
Before は、読みやすさのつもりで同じ仕様を2か所に書いた例です。
<!-- order.md -->
注文APIのタイムアウトは30秒です。認証は必須です。
<!-- batch.md -->
バッチから注文APIを呼びます。タイムアウトは60秒で動かします。認証は必須です。
タイムアウトが2か所にあり、しかも食い違っています。人間なら「用途で違うのかな」と察しますが、生成AIは両方を正として扱うことがあります。
After は、事実を1か所に寄せ、もう片方はリンクで参照します。
<!-- order.md（ここが唯一の正） -->
## 注文API
| 項目 | 値 |
|---|---|
| タイムアウト | 30秒 |
| 認証 | 必須 |
<!-- batch.md -->
## バッチからの呼び出し
注文APIの仕様（タイムアウト・認証）は `order.md` を唯一の正とします。
ここには再掲しません。バッチ固有の事情は以下のみ記載します。
- 呼び出し間隔: 5分ごと
数値を batch.md に書かないことで、片方だけ更新されて食い違う未来が消えます。図をコードで書く（diagrams as code）手法も、このポイントの延長にあります。図とコードを同じリポジトリで版管理すれば、変更時に1つのテキストを直すだけで済みます(Material for MkDocs, IO Tools）。
ディレクトリと命名で「唯一の正」を見つけやすくする
単一ソース化は、ファイルの置き方とも関係します。どこが正なのかが命名から分かると、再掲の誘惑が減ります。架空の構成で示します。
docs/
design/
00-overview.md
01-glossary.md
10-auth.md
20-order.md
90-constraints.md
diagrams/
order-flow.mmd
数字プレフィックスで読む順序を固定し、glossary（用語集）や constraints（制約）を独立ファイルにしています。ファイル名から中身が推測できると、生成AIに渡す対象を選びやすく、人間にとっても迷子になりにくくなります。1ファイルが巨大だと必要な部分だけを渡しにくいため、独立して読める単位に分割するのも有効です。
さらに、ドキュメント一覧を機械可読な形で置く llms.txt という提案もあります（新興の慣行です）。これはサイトのルートに、主要ドキュメントへのリンクをMarkdownで列挙する提案で、2024年9月にJeremy Howard氏が公開しました(llms.txt（一次情報））。文脈窓にサイト全体は収まらないため、要点への入口を1か所にまとめる、という発想です。まだ発展途上の慣行なので、必須ではなく「余裕があれば」程度に捉えています。
落とし穴: 二重管理と「AI最適化の目的化」
単一ソースを掲げながら、つい「読みやすさのために」同じ仕様を複数箇所に書いてしまうことがあります。私もやりました。コピーした瞬間に、片方だけ更新されて食い違う未来が確定します。再掲したくなったら、リンクに置き換えられないかをまず疑うようにしています。
もう1つ、llms.txt を整え、メタ情報を盛り、と手段が増えると、いつのまにか「AIに最適化すること」が目的になりがちです。一次の目的は、人間とAIの両方に正しく伝わることです。この2つはおおむね同じ方向を向きます。
ポイント3: 用語定義
効く理由
文書内で特別な意味を持つ語は、冒頭に用語集として並べます。前章の確率的補完の観点で言えば、定義のない語はモデルが一般語義で補完します。「ユーザー」「セッション」「ジョブ」のような一般語ほど、プロジェクト固有の意味を持ちやすいので、補完とのずれが起きやすくなります。
定義を冒頭に置くのには、文脈窓の理由もあります。先頭は注意が高まりやすい位置なので、定義を最初に出すと、以降の本文を読むときの土台になりやすくなります。略語は初出で展開します。
Before / After（語の意味を固定する）
Before は、「ユーザー」が節ごとに別の意味で使われている例です。
## 登録フロー
ユーザーがメールアドレスを入力すると確認メールを送ります。
## 集計バッチ
ユーザーごとの利用回数を日次で集計します。
前者の「ユーザー」は未登録の訪問者、後者は登録済みの会員を指していますが、文面からは区別がつきません。生成AIは一般語義で補完するため、集計対象に未登録者を含める実装を返すかもしれません。
After は、冒頭で語を定義し、本文では定義済みの語に寄せます。
## 用語
- 訪問者: 未登録の利用者（メールアドレス確認前を含む）
- 会員: メールアドレス確認を完了した登録済みの利用者
## 登録フロー
訪問者がメールアドレスを入力すると確認メールを送ります。
## 集計バッチ
会員ごとの利用回数を日次で集計します。
「ユーザー」という曖昧な語を捨て、「訪問者」「会員」に分けただけで、補完の余地が消えます。略語も同様に、PCS（架空の社内用語: 商品分類サービス） のように初出で展開します。
落とし穴: 用語集の陳腐化と過剰定義
用語集も、更新を怠れば古い定義が残ります。本文で使う語と用語集がずれると、かえって混乱の元になります。また、辞書を引けば分かる一般語まで全部定義すると、用語集が膨らんで読まれなくなります。定義するのは「プロジェクト固有の意味を持つ語」「誤読が実際に起きた語」に絞るのが現実的です。完璧を目指さず、5〜10語から始めると続けやすくなります。
3つのポイントを支える共通の作法
3つのポイントに加えて、どのポイントでも効く作法を3つ挙げます。
図と表を使い分ける
関係性・フロー・状態遷移は図（Mermaid）に、項目ごとの属性は表に向きます。逆をやると読みにくくなります。たとえば「リクエストがどう流れるか」を表で書くと縦に長くなり、「各APIのパラメータ一覧」を図で書くとごちゃつきます。
図は画像ではなく Mermaid のコードブロックで書きます。テキストなので版管理でき（ポイント2に効く）、生成AIも中身を読めます（ポイント1に効く）。最小のフロー図から始め、分岐を1つずつ足していくのがコツです。
```mermaid
flowchart LR
Client[クライアント] --> API[APIゲートウェイ]
API --> Auth{認証OK?}
Auth -->|はい| Order[注文サービス]
Auth -->|いいえ| Reject[401を返す]
```
{ } は判断（ひし形）、[ ] は処理（長方形）を表します。矢印のラベル（|はい|）で分岐の条件を明示します。この条件ラベルが、生成AIに分岐の意味を伝える情報になります。ノードのラベルには A、B のような無意味なIDだけでなく、意味のある日本語を入れておくと、生成AIがそのまま語彙として使えます。
前提と制約を専用の節に出す
想定する負荷・対象外の範囲・依存する外部条件を、本文に溶かさず専用の節に書き出します。前章の文脈窓の観点で言えば、これは「最初に効いてほしい制約を、見落とされやすい中央ではなく冒頭に置く」工夫でもあります。生成AIにも人間にも、「この設計が成り立つ条件」が一目で分かるようにします。
メタ情報を先頭に置く
各ドキュメントの冒頭に、何の文書か、いつ更新されたか、どのバージョンが対象かを宣言します。
---
title: 注文サービス設計
status: ドラフト
updated: 2026-06-15
target-version: v2
owner: order-team
---
## この文書の対象
注文サービス（example-order）のAPIと制約を定義します。
認証の詳細は `10-auth.md` を参照してください（ここには再掲しません）。
最後の一文がポイントです。「認証はこちらに書いてある」とリンクで示し、再掲しません。これが単一ソース原則（ポイント2）の実装です。
Before / After 総合例
ここまでの3つのポイントと作法を、1つの架空の設計メモにまとめて適用します。Before は、よくある「人間にはなんとか伝わるが、AIには曖昧」な書き方です。
Before（雑な設計メモ）
# バッチ設計メモ
毎晩バッチを回します。ユーザーのデータを集計してレポートを作ります。
失敗したらリトライ。だいたい数万件くらい。Slackに通知も飛ばします。
DBはいつものやつ。タイムアウトは適宜。
この文には、整えるべき箇所が詰まっています。「毎晩」が何時か不明（前提の欠落）、「ユーザー」が誰か未定義（用語の欠落）、「だいたい数万件」「適宜」が曖昧（制約の欠落）、「いつものやつ」は暗黙知です。生成AIにこれで実装を頼むと、想定と違う時刻・違う規模・違うエラー処理で返ってくる確率が上がります。
After（人にもAIにも読める設計）
まずメタ情報・用語・前提を冒頭に明示します（ポイント3＋共通の作法）。
---
title: 夜間集計バッチ設計
status: レビュー中
updated: 2026-06-15
target-version: v1
---
## 用語
- 対象ユーザー: 直近30日にログインした会員（未登録の訪問者は対象外）
- 集計レポート: 会員ごとの利用回数を1行で表す日次レポート
## 前提・制約
- 実行時刻: 毎日 02:00（タイムゾーンは Asia/Tokyo）
- 想定件数: 1回あたり最大5万件
- 対象外: リアルタイム集計、月次の請求処理
次に、処理フローを Mermaid で示します（ポイント1＋共通の作法）。この図は主要フローのみを示し、保存失敗・通知失敗の挙動は後述の表で定義します。ここで accTitle と accDescr を入れると、スクリーンリーダー向けのタイトルと説明がSVGに埋め込まれ、Mermaid はこれらを ARIA 属性として出力します(Accessibility Options | Mermaid 公式）。
accTitle / accDescr は Mermaid のアクセシビリティ機能で、生成されるSVGにタイトルと説明を埋め込みます。古いバージョンや、ホスティング側（Qiita 等）の Mermaid 実装では挙動が異なる場合があるため、利用前に対象環境で表示を確認してみてください。
```mermaid
flowchart TD
accTitle: 夜間集計バッチの処理フロー
accDescr: 02時に起動し対象ユーザーを抽出して集計、レポート保存後にSlack通知。失敗時は最大3回リトライ。
Start([02:00 起動]) --> Fetch[対象ユーザーを抽出]
Fetch --> Agg[利用回数を集計]
Agg --> Save[レポートを保存]
Save --> Notify[Slackへ完了通知]
Agg -->|失敗| Retry{リトライ3回以内?}
Retry -->|はい| Agg
Retry -->|いいえ| Alert[Slackへ失敗通知]
```
最後に、エラー処理の仕様を表で固定します（ポイント1）。
| 事象 | 挙動 | リトライ | 通知先 |
|---|---|---|---|
| 集計失敗 | 最大3回リトライ | あり（3回） | 失敗時に Slack |
| 保存失敗 | 即時中断 | なし | 即 Slack |
| 通知失敗 | 処理は成功扱い | なし | ログのみ |
Before と After を並べると、増えた情報量が見えます。After では、時刻・対象・規模・エラー処理が、すべて曖昧さなく定義されています。これは生成AIのためだけの工夫ではありません。半年後に自分が読み返したとき、あるいは新しいメンバーが引き継いだときにも、同じだけ助かります。
アクセシビリティの補足
図の表現は色だけに頼らない配慮も入れておくと安全です。たとえばフローの分岐を「赤＝失敗、緑＝成功」の色だけで区別すると、色覚特性のある読者やモノクロ表示では区別できません。ラベル（|失敗|）や形（ひし形＝判断）でも区別できるようにします。画像で図を貼る場合は、内容を表す代替テキスト（alt）を必ず添えます。
これは人間のアクセシビリティの話ですが、テキストのラベルや代替テキストは生成AIにも届きます。アクセシビリティ対応とAI可読性は、ここでも同じ方向を向きます。
どこから手をつけるか（移行の順序）
既存の設計書がたくさんある場合、全部を一度に整えるのは現実的ではありません。私は3つのポイントを、費用対効果の高い順に次のように進めています。あくまで一例です。
- 冒頭にメタ情報と前提・制約を足す。本文を書き換えずに先頭へ追記するだけで効果が出ます。最も安く、文脈窓の観点でも効きやすい工夫です。
- 用語集を1ファイル作る（ポイント3）。固有の意味を持つ語を5〜10個だけ定義します。完璧を目指さず、誤読が多い語から並べます。
-
見出しを意味どおりに刻み直す（ポイント1）。太字の見出しを
##／###に置き換え、階層を飛ばさないよう整えます。 - 食い違っている事実を単一ソースに寄せる（ポイント2）。重複を見つけたら、片方をリンクに置き換えます。ここで矛盾が一掃されます。
- 画像の図をMermaidに置き換える。手間が大きいので最後に回します。頻繁に変わる図から優先すると、更新コストの削減を実感しやすくなります。
1〜2は数十分で終わり、効果が大きい割に低リスクです。3以降は、変更頻度の高いドキュメントから順に回すと、投じた手間が回収しやすくなります。
まとめ
生成AIに渡す設計書は、特別な書き方を覚えるというより、人間の補完力に頼っていた省略を、明示に変える作業だと捉えると見通しが良くなります。鍵は3つのポイントです。曖昧さを消す構造、事実の単一ソース化、用語の定義。これらは、確率的補完・トークン化・文脈窓というモデルの性質に素直に対応します。
すべてを一度に直す必要はありません。まず1つのドキュメントで、用語と前提を冒頭に出し、見出しを意味どおりに刻むところから始めると、効果を体感しやすいはずです。ここで挙げた手法はどれも一般的なもので、唯一の正解ではありません。手元の規模やチームの慣習に合わせて、取捨選択していただければと思います。
参考文献
- Lost in the Middle: How Language Models Use Long Contexts（Liu et al., 2023, arXiv:2307.03172）（文脈窓内の位置と性能の関係。先頭・末尾が拾われやすく中央が弱い傾向）
- Write LLM-friendly docs | Fern（LLM向けドキュメントの構造化、見出し階層、セクションの自己完結性）
- Boosting AI Performance: LLM-Friendly Content in Markdown | Webex Developers Blog（Markdownの構造がLLMの解釈精度に与える影響）
- Why Markdown Is the Lingua Franca of AI | file2markdown Blog（Markdownの構造保持・トークン効率）
- The /llms.txt file（一次情報・llmstxt.org）（llms.txt 仕様の一次情報。2024年9月、Jeremy Howard 提案）
- Diagrams - Material for MkDocs（MkDocs での Mermaid 設定）
- Mermaid Diagrams: Document Architecture in Markdown | IO Tools（diagrams as code の利点・更新運用）
- Accessibility Options | Mermaid 公式（accTitle / accDescr と ARIA 属性）
本文中のサービス名・ディレクトリ名・コード例はすべて架空で、example 系の予約値を使用しています。ベストプラクティスは状況に依存するため、断定を避けて記述しています。誤りや別解のご指摘は歓迎します。