30 秒で分かる結論：llms.txt のよくある間違いの多くは、書き方ではなく配信の問題
12 個のうち 4 つはサーバーの話です（実はファイルがない、Content-Type の誤り、エンコーディング、ボットの遮断）。4 つは Markdown の構造です（H1、引用、リンクの書式、相対 URL）。4 つは内容です（リンク切れ、大きすぎるファイル、何も言っていない注釈、誰も保守していないファイル）。ブラウザで見る前に curl で取得してください。リストの半分はレスポンスの最初の 10 行に見えています。
| # | 間違い | バリデータの項目 | レベル |
|---|---|---|---|
| 1 | ファイルが HTML のフォールバックページ | content_type_ok | fail |
| 2 | Content-Type の誤り | content_type_ok | warn |
| 3 | UTF-8 でない、または BOM つき | encoding_utf8 | fail / warn |
| 4 | robots.txt や WAF でボットを遮断 | served_at_root, links_reachable | fail |
| 5 | H1 がない、複数ある、先頭にない | has_h1, single_h1, h1_first | fail / warn |
| 6 | 引用の要約がない | has_summary | warn |
| 7 | リンクがリスト形式でない | has_links, link_format_valid | fail / warn |
| 8 | 相対 URL | links_use_http | fail |
| 9 | リンク切れ | links_reachable | warn / fail |
| 10 | 大きすぎる：サイトマップの丸写し | reasonable_size | warn |
| 11 | リンク文を繰り返すだけの注釈 | （人が見る） | |
| 12 | 誰もファイルを保守していない | （人が見る） |
配信の間違い
1. ファイルが HTML のフォールバックページ
最も多い失敗です。サーバーは /llms.txt に 200 を返し、本文はシングルページアプリの外枠かカスタム 404 ページです。ブラウザには普通のページが見え、パーサは見出しを期待した場所に doctype を見つけます。バリデータは Content-Type ヘッダーと本文の先頭 512 バイトの両方で HTML 文書かを調べ、どちらかに該当すれば失敗にします。直し方は、ホストがそのまま配信する静的ディレクトリにファイルを置くか、テキストを返すルートを足し、curl -i https://your-site/llms.txt で本文の 1 行目が # で始まることを確かめることです。
2. Content-Type の誤り
ファイルはあるのに application/octet-stream や型なしで配信されている。ホストがそのパスの .txt に対応する型を持っていないためです。読む側の多くは対処しますが、厳密なクライアントが最初に見るのはこのヘッダーです。text/markdown; charset=utf-8 か text/plain; charset=utf-8 で配信します。このサイト自身のファイルは text/markdown です。
3. UTF-8 でない、またはバイト順マークつき
エディタから古いエンコーディングで保存されたファイルや、UTF-8 の BOM つきのファイルは、1 行目が見出しとして読めません。バリデータは UTF-8 として復号できない本文を失敗にし、BOM、utf-8 以外の charset パラメータ、本文中の置換文字を警告にします。BOM なしの UTF-8 で保存し直し、ヘッダーで charset=utf-8 を宣言してください。Windows のメモ帳や一部の CMS は BOM を付けることがあります。
4. robots.txt やファイアウォールでボットを遮断
ファイルは完璧で、誰も読めない。未知のエージェントにすべてを禁止する robots.txt の規則や、ブラウザ以外のリクエストにチャレンジを返す WAF の既定設定が、ファイルの宛先であるクローラーに 403 やチャレンジページを返します。バリデータはルートで応答なしか 200 以外のステータスを報告し、ファイルは届くのに抽出したリンクがすべて失敗する場合はその旨を言います。対象のエージェントに /llms.txt とリンク先のページを許可し、ブラウザではなく クローラーのユーザーエージェントで試してください。
構造の間違い
5. H1 がない、複数ある、先頭にない
仕様で必須なのはただ 1 つ、プロジェクト名またはサイト名の H1 です。コメント、空の引用、ロゴの行で始まるファイルは、パーサが最初に行う検査に落ちます。H1 が 2 つ（たいていサイト名と製品名）あると、読み手はどちらが題名か迷います。# サイト名 の 1 行を、最初の空でない行に置きます。
6. 引用の要約がない、またはキャッチコピーが入っている
仕様は、ファイルの残りを理解するのに必要な重要情報を含む短い要約の引用を説明しています。バリデータは引用がなければ警告します。捕まえられないのはキャッチコピーの場合です。「もっと速く、もっと遠くへ」はモデルが使える情報を何も含みません。それが何か（名詞）、誰向けか、リンクを読む前に知るべき 1 つの事実、を 1〜2 文で書きます。
7. リンクがリスト項目になっていない
行に裸で置かれた URL、Markdown の表、番号つきリスト、HTML のアンカー。仕様は各項目を、必須のハイパーリンクとコロンの後の任意の注釈を持つリスト項目と定めています。バリデータは有効な項目が 1 つもないファイルを失敗にし、一部の箇条書きが書式に合わなければ警告します。直し方は機械的です。
## ドキュメント https://acme.example/ja/docs/quickstart 1. インストール手順 - https://acme.example/ja/docs/install | 料金 | https://acme.example/ja/pricing | ## ドキュメント - [クイックスタート](https://acme.example/ja/docs/quickstart): インストールから初回実行まで 5 分。 - [インストール手順](https://acme.example/ja/docs/install): 対応プラットフォームとパッケージマネージャ。 - [料金](https://acme.example/ja/pricing): 3 プラン。無料枠は 1 プロジェクトまで。
8. 相対 URL
[ドキュメント](/docs) は基準 URL を知っているブラウザでは動き、それ以外では動きません。仕様の例は絶対 URL で、プロキシやキャッシュ、エージェントが保存した写しを通して読まれたファイルには解決の基準がありません。バリデータは http か https でないリンクを失敗にします。毎回スキームとホストを書き、面倒ならファイルを生成します。
内容の間違い
9. リンク切れ
ページ名の変更、ドキュメントの別ホストへの移転、404 にリダイレクトするようになった末尾のスラッシュ。バリデータはリンクから最大 10 本を抽出して HEAD で確かめ、いくつ応答したかを報告します。クローラーは報告しません。黙ってリンクを飛ばして先へ進みます。サイトの構成を変えるたびに検査を走らせ、変わりやすい深い URL より安定した入口ページにリンクしてください。
10. 大きすぎる：サイトマップを Markdown に丸写し
1 ページ 1 行で書き出す生成ツールは、完全で役に立たないファイルを作ります。何百本ものリンク、名前に値しないセクション、数千トークンしかない読み手が選ぶ手がかりなし。バリデータは 100 KiB を超えると警告し、512 KiB で止まります。よくできたファイルの多くは 15 KB 未満です。索引には本当の質問に答える 10〜50 ページを名前つきのセクションに分けて載せ、全文を公開したいなら llms-full.txt に置きます。
11. リンク文を繰り返すだけの注釈
「[料金](…): 料金ページ。」はすべての自動検査を通り、モデルには何も伝えません。コロンの後の注釈は、読み手が何を見つけ、誰向けかをファイルの中で言える唯一の場所です。題名にない事実を 1 文で書きます。プランの数、対応プラットフォーム、そのページが答える質問。
12. 誰もファイルを保守していない
リリース週に一度だけ手で書かれたファイル。半年後には廃止したページにリンクし、古い料金を書き、改名前の製品を説明しています。本当だった文が本当でなくなったことを捕まえるバリデータはありません。できるならサイトマップと同じデータから生成し、できないなら料金変更・改名・ドキュメント移転のたびのチェックリストに載せ、要約に日付つきの 1 行を置いて、いつ最後に見直されたかを読み手が分かるようにします。
バリデータが体裁として挙げるものがあと 2 つあります。末尾の改行がないファイルと、## セクションがまったくないファイルです。どちらも読み手を壊しませんし、どちらも 1 分で直ります。
自分のファイルを確かめる
まず素の HTTP クライアントでファイルを取得し、次にバリデータにかけます。バリデータは上の検査項目をそれぞれ名前つきで報告し、見つかったセクションとリンクを一覧にします。
llms.txt を検証する
サイトの URL を貼ると、/llms.txt を取得してこの記事の検査項目を実行し、見つかったセクションとリンクをすべて一覧にします。リンクは一部を抽出して到達性も確かめます。
バリデータを開く →よくある質問
llms.txt は 200 を返すのに、バリデータは「ファイルがない」と言います。なぜですか？
本文が HTML だからです。シングルページアプリや一部のホスティングは、未知のパスにアプリの外枠やカスタム 404 ページを 200 で返すため、取得は成功しても中身はウェブページです。バリデータは Content-Type ヘッダーと本文の先頭バイトの両方で HTML 文書かどうかを見ます。ホストがそのまま配信する静的ディレクトリにファイルを置くか、テキストを返すルートを足し、curl でレスポンスが # の見出しで始まることを確かめてください。
Content-Type は本当に重要ですか？
仕様は何も定めておらず、本文が Markdown なら text/html で配信されていても読む側の多くは解析できます。ただし誤った型はたいてい症状です。text/html はフォールバックページ、application/octet-stream はホストがそのファイルを知らない印です。text/markdown か text/plain を charset=utf-8 つきで配信すれば、原因ごと症状が消えます。
相対 URL は使えますか？
仕様の例は絶対 URL で、各項目を「さらに詳しい情報がある場所へのハイパーリンク」と説明しています。プロキシ経由で取得したり別の場所に保存したりした読み手には相対パスの基準がなく、このサイトのバリデータは http(s) でないリンクを失敗にします。スキームとホストを含めた完全な URL を書いてください。
どのくらいの大きさから「大きすぎ」ですか？
仕様に上限はありません。このバリデータは 100 KiB を超えると警告し、512 KiB で読むのをやめます。数千トークンの予算しかないモデルにはそれ以上使えないからです。よくできたファイルの多くは 15 KB 未満です。それより大きいなら、たいていサイトマップの書き出しかドキュメント全ページの列挙です。索引は短く保ち、全文は llms-full.txt に置きます。
バリデータは注釈の中身も見ますか？
見ません。各箇条書きがリンクの書式に合っているか、URL が http(s) かを見るだけで、コロンの後の注釈は自由記述です。注釈がリンク文にない情報を言っているかは人が見るしかなく、検証を通り抜ける間違いとして最も多いものです。
警告も直すべきですか、それとも失敗だけですか？
失敗は、読み手が使えるファイルを得られないことを意味します。到達不能、HTML、H1 なし、リンクなし、UTF-8 でない。警告は、ファイルは動くが仕様の推奨やパーサの期待から外れていることを意味します。引用がない、セクションがない、箇条書きが別の書式、サイズが大きい、末尾の改行がない。まず失敗を直してください。警告の多くは 1 つ 1 分で済みます。
次に読む
- → llms.txt の書き方：30 分で自分で書く手順 （12 個すべてを避けるファイルを 30 分で）
- → llms.txt の仕様を 1 行ずつ読む （何が必須で何が慣習か）
- → llms.txt の実例 8 選
- → 解説記事の一覧へ戻る