（人間ではなく）LLM向けのドキュメントに求められる記法

最近、LLM（大規模言語モデル）向けのドキュメントを見かけるようになりました。

実際に、Svelte公式が「https://svelte.dev/docs/llms」というLLM向け専用ドキュメントを公開したことからも、今後は人間だけでなくAIに向けての情報設計が標準になると考えられます。

また、従来のSEO対策はもはや意味をなさなくなりつつあり、AIによる概要への情報源として掲載されることの方が、より重要になりつつあるのでは？と感じています。

なので、これを機に LLM が内容を正確に把握しやすいドキュメントの書き方・構造について、実際の記法例をまとめてみました。

まず、 LLM が内容を正確に把握しやすいドキュメントの書き方・構造について言及します。その後、なぜ「ドキュメント構造」が重要なのかを言及します。

LLM向けドキュメントに求められる仕様・記法の特徴

1. 明確な構造（Structure）

   • Markdownをベースとした構造化された文書が多い（.mdファイル）
   • セクション（##）、リスト（-や1.）などを明示的に使う
   • コードブロックは で囲み、使用言語を指定（例: svelteや ```ts ）

2. 意味論的に明確なラベル

   • 各セクションの見出しに意図が込められている
     • 例: Usage, Parameters, Example, Return value, Error cases
   • これは、LLMが特定の情報を抽出しやすくするためです

3. 自然言語とコードの分離

   • コードスニペットとその説明が明確に区別されている
   • コードの直前や直後に、その意図や実行結果を記述するのが望ましい

4. 冗長性の排除と一貫性のある用語と表記

   • 同義語や曖昧な用語を避け、同じ概念には常に同じ表現を使う
     （例: storeとstateを混同しない）
   • 「型」「返却値」「例外」などを明示的にラベリングする
   • LLMが意味を安定的に理解するための工夫

5. 定義と使用例の明示

   • 型定義や関数シグネチャを最初に明示
   • そのあとで使用例を示す（例: type → exampleの順）

具体的な仕様・設計に関わるドキュメント例としての、Svelte公式の取り組み（参考）

Svelteの LLM向けドキュメント では、以下のような構造設計が徹底されています。

• .md形式で、構文が完全に構造化
• セクションのタイトルと内容が一致
• コードブロックは明示的にラベリング
• SYSTEMセクションなどでメタ情報も提供

以下、その一部と抜粋します。

このページはSvelteがLLM（AI）に学習・参照させるために構築している 構造化されたドキュメントのメタ仕様 を説明しています。

<SYSTEM>This is the full developer documentation for Svelte and SvelteKit.</SYSTEM>

# 概要
Svelte は Web UI 構築のためのコンパイラベースのフレームワークです。

```svelte
<script>
	function greet() {
		alert('Welcome to Svelte!');
	}
</script>

<button on:click={greet}>click me</button>

このようなドキュメントは、LLMがコードの文脈や意味を理解しやすいように、構造化・設計されています。

• .jsonや.tsファイルではなく、LLMが自然言語として読めるMarkdownベースの書き方
• セクション名やラベル名に一貫性がある

LLM向けドキュメントを書く際に意識すべき点（要約）

項目	内容例
フォーマット	`arkdown（.md）が主流
セクション構造	## Usage, ## Parameters, ## Example
コードブロック	```ts など、言語指定
意味論的見出し	タイトルと内容が一致
自然言語とコードの分離	どちらも明確に区切る
曖昧な表現の排除	一貫した表記を使用
機械に読みやすく、人にも読みやすく	両立が重要

実際にLLMが処理しやすいフォーマット例

### Function: `getUserData`

ID でユーザーデータを取得します。

#### Parameters

- `userId: string` — 取得するユーザーのID

#### Returns

- `Promise<UserData>` — ユーザーデータを解決するPromise

#### Example

```ts
const data = await getUserData("abc123");
console.log(data.name);

Errors
- Throws UserNotFoundError if the user does not exist
...```

このような「明示的な構造 + サンプルコード + 統一された用語」が、LLMにとって最も有用です。

この方法は、Claude CodeのCLAUDE.mdなど、AIコーディングエージェントへの指示方法にもそのまま活かせると思います。

なぜ「ドキュメント構造」が重要なのか

従来：検索エンジンベースのアクセス（人間中心）

従来のWebでは、ユーザーが「Google検索」などを使い、

• キーワードを入力し、
• 検索結果の中から人間が情報を読む

という 人間の読解と評価 が前提の仕組みでした。

そのため、情報発信側は以下のような「SEO（検索エンジン最適化）」を意識していました。

• タイトルにキーワードを含める
• メタタグを整える
• リンク数や滞在時間などを意識する

現在：LLMはWebページを“読解”して情報を理解・要約する

ChatGPT や Claude のような LLM（大規模言語モデル） は、検索エンジンとは異なり、以下のような方法でドキュメントを処理します。

特徴	内容
文法と構造に基づいて理解	セクション、見出し、パラグラフの論理的関係
意味論ラベルに基づいて分類	Parameters, Example, Error cases などのラベルを理解
コードと自然言語の関係を推論	関数の意図や戻り値の型を文脈から理解
JSON/Markdownなどの構造を活用	明示的な構造がある文書は「意味の単位」が抽出しやすい

つまり、「検索キーワードに一致する文を探す」のではなく、「構造的に意味を理解し、回答のための素材として利用する」のです。

結論

従来のSEOは「キーワードマッチ」や「リンク評価」でしたが、LLMは構造や文脈で意味を理解します。

人間の検索	LLMによる読解
Googleで「Svelte store example」を検索	Markdown内の## Storeや### Exampleを即座に抽出・要約
リンクを開いて探す	LLMがコードと自然文を一体的に要約
SEO施策で上位表示	セクション構造と一貫性が重要

検索エンジンがインターフェースとして利用されていた時代から、AIエージェントをインターフェースとして利用するようシフトして行きそうな昨今、「検索エンジンでの発見されやすさ」よりも「AIがドキュメントを機械的に読んで意味を理解できるか」 が重要になってきていると感じます。

特に以下のようなケースではその傾向が顕著です。

• RAG（Retrieval-Augmented Generation）で社内ドキュメントから回答生成する場合
• LangChainやLlamaIndexでナレッジを取り込む場合
• API仕様をLLMに読み込ませる場合（例: OpenAPIやSvelteのLLM向けドキュメント）

まとめ

• LLM時代の技術ドキュメントは「構造」が命
• Markdown + 意味のある見出し・記述パターンが有効
• SvelteやLangChainなどもすでにこの方向に移行中

✍️ あとがき

AI時代の「技術の書き方」を考える上で、これは重要な転換点かもしれません。
ご自身の技術文書も、“AIに読ませる”前提で再設計してみてはいかがでしょうか？

自身も今後はこれがどのように効果を発揮していくのか？を検証していきたいと思います。