7月24日、Prisma社が「How to Make Your Docs Agent-Ready: llms.txt, Parity, MCP」と題した記事を公開した。この記事では、AIコーディングエージェントが自律的にドキュメントを取得・解析できるようにするための具体的な実装方法について詳しく紹介されている。

AIエージェントがコードを書く時代になり、ドキュメントの「読者」が人間だけではなくなった。エージェントはタスクの途中でドキュメントページをフェッチし、その内容を元に回答を生成する。人間なら壊れたリンクをスキップしたり、バージョン切り替えに気づいたりできるが、エージェントはそうではない。リクエストを投げ、返ってきたものをそのまま使って先に進む。

こうした背景には、AIエージェントによるドキュメント消費が急速に一般化しつつある業界動向がある。GitHub CopilotやCursorのようなコーディングエージェントは、回答生成の過程でリアルタイムに外部ドキュメントをフェッチする機能を持つ。エージェントが「読む」前提でドキュメントを整備する動きは、llms.txt仕様の策定（Answer.AIのJeremy Howardらが主導）や、Mintlifyなどのドキュメンテーションプラットフォームによる監査ツールの提供へと波及している。llms.txtは2024年後半から急速に普及し、主要なOSSプロジェクトや開発者向けSaaSが対応を進めている。

この問題意識から、Prisma社はMintlifyが提供する公開監査ツール「Agent Readiness Score」（30項目のチェックで構成）を使って自社ドキュメントを診断し、発見した問題を修正した。開始時のスコアは85点/100点。修正後は100点を記録した（2025年7月24日時点）。ただし後述するように、2つの修正項目については1回目の適用ではチェックをパスしなかったため、再計測と追加対応を経て100点に到達している。

本記事では、その5つの問題と対処法を解説する。

最重要の修正：llms.txtの肥大化

llms.txtはエージェントが最初に取得するインデックスファイルだ。固定URLに置かれたプレーンテキストで、サイトに何が含まれるかをエージェントに伝える。

Prismaのllms.txtはすべてのドキュメントページをインラインで列挙しており、約116,000文字あった。Mintlifyの監査は50,000文字超を失敗扱いにするが、この制限には実際の失敗モードが対応している。クライアントはフィードをどこかで読み切り、その上限は様々で、ほとんどドキュメント化されていない。ファイルが途中で切れても、エージェントには確かめる術がない。

対処法は分割だ。各プロダクト領域が/docs/llms/<area>.txtに独自のインデックスを持ち、ルートファイルはそれらへの目次になった。

## Product Area Indexes
- [`Prisma ORM`](https://www.prisma.io/docs/llms/orm.txt): Current Prisma ORM docs: setup, schema modeling, Prisma Client, migrations, and references (excludes legacy v6 and Prisma Next).
- [`Prisma ORM v6 (legacy)`](https://www.prisma.io/docs/llms/orm-v6.txt): Legacy Prisma ORM v6 documentation, maintained for backwards compatibility only. Prefer the current Prisma ORM section for new work.
…
- [`Prisma Postgres`](https://www.prisma.io/docs/llms/postgres.txt): Prisma Postgres setup, connection strings, local development, operations, and guides.

ルートファイルは現在約7,000文字。CIでルートと各エリアインデックスに50,000バイトの予算を設け、最大のインデックスorm-v6.txtでも37KBに収まっている。

4つの修正領域

1. すべてのページにインデックスへの経路を追加

エージェントが検索結果や貼り付けられたリンクから単一ページに着地した場合、以前はそこから他のドキュメントに辿る手段がなかった。

現在はMarkdownの先頭とHTMLの隠し要素の両方に、llms.txtへのポインタを追加している。例えばwww.prisma.io/docs/postgres.mdの冒頭は以下のようになった：

# Prisma Postgres (/docs/postgres)
> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

2文で、1ページを持つエージェントが全体に到達できる。なお、HTMLコピーのページ内配置については、ページの折り返し地点より後に描画されており、この点に関する警告は残ったままである。

2. MarkdownとHTMLのパリティ（内容一致）

すべてのPrismaドキュメントページはURLに.mdを付加することでMarkdownとして取得できる。しかしビルドプロセスでページのdescriptionがHTMLには表示されるのにMarkdown出力に含まれていなかった。人間が見るサマリーをエージェントは読めなかったわけだ。

修正はdescriptionをMarkdown出力にも通すことだった。また、コピーボタンや「GitHubで編集」フッターなどHTMLのみのUI要素にはdata-markdown-ignore属性を付与した。パリティチェッカーが「コピーボタンの欠落はコンテンツの欠落ではなくUIだ」と判断できるようにするためだ。

なお、この修正ではMintlifyのMarkdown Content Parityチェックを完全にはパスしなかった。15サンプルページのうち1ページがまだフラグを立てられており、再計測と追加対応が必要だった。

3. llms-full.txtのリンク修正と縮小

llms-full.txtはドキュメント全体を1ファイルに連結したフィードだ。問題が2つあった。

リンクの問題が本質的に厄介だった。 フィードには/orm/prisma-client/queriesのようなルート相対パスのリンクが約2,500件含まれていた。レンダリングされたサイトではフレームワークが/docsベースパスを付与するが、生のフィードではその処理が入らない。クライアントがリンクを辿るとprisma.io/orm/...という存在しないページに着地していた。

対処はインボディリンクを絶対URLに書き直すこと。フィードとページごとの.mdの両方で対応した。

サイズについては、約7MBあったフィードからレガシーのPrisma ORM v6ページと廃止済みプロダクトページを除外し、4.5MBまで縮小した。除外したページはフィードから外れただけで、個別URLに.mdを付加すれば引き続き取得できる。

4. エージェントスキルとMCP探索ドキュメントの公開

2つの監査チェックはそもそも対象ファイルが存在しなかったためゼロ点だった。

エージェントスキルは、エージェントが散文から推測する代わりにロードして従えるワークフローファイルだ。Prismaのセットアップを説明するものをprisma.io/skill.mdとprisma.io/docs/skill.mdに公開し、/.well-known/agent-skillsにリストを置いた。name、description、license、compatibility、metadata、allowed-toolsの6つのフロントマターフィールドを持ち、CIでこれらの存在を検証している。

**Prisma MCPサーバー**はすでにmcp.prisma.io/mcpで稼働していたが、prisma.io上のエージェントがそれを見つける手段がなかった。/.well-known/mcp（/.well-known/mcp.jsonでも同一ドキュメントを返す）に以下のJSONを公開した：

{
  "version": "1.0.0",
  "transport": "http",
  "url": "https://mcp.prisma.io/mcp",
  "servers": [
    {
      "name": "prisma",
      "url": "https://mcp.prisma.io/mcp",
      "transport": "http",
      "authentication": "oauth"
    }
  ]
}

ただしこれも監査のMCP Server Discoverableチェックをパスしなかった。チェックはサイト自身の/mcpパスにMCP initializeリクエストを送るため、別サーバーを指すドキュメントだけでは不十分だった。現在、prisma.io上に同サーバーにプロキシする/mcpエンドポイントを別途対応中だ。

最も持続する変更はCIチェック

個別の修正よりも重要なのが、変更を維持するCIチェックlint-agent-ready.tsだ。pnpm --filter docs lint:agent-readyとしてmainへのすべてのPRで実行され、以下を検証する：

• 各インデックスファイルのサイズ予算
• インデックスからすべてのページへの到達性
• すべてのページにおけるllms.txtポインタの存在
• タスク形式リンクの解決確認
• 除外ページがフルフィードに含まれないこと
• スキルとMCPドキュメントの必須フィールドの存在

監査はクロールした日のスコアを示すだけで、リポジトリを監視しない。 PRごとにこれらの不変条件を強制するものがなければ、次の数百ページのコンテンツ追加によってこの作業が静かに無効化される。

自分のドキュメントに適用する手順は、まずAgent Readiness Scoreで診断し、チェックではなく原因でグループ化してから修正することだ。Prismaの場合、数十のチェックが5つの原因に集約された。また、修正後は必ず再計測すること。Prismaでは2つの修正が1回目のパスでチェックをパスせず、再実行して初めてそれがわかった。タイトルに掲げた「100点」はこの再計測と追加対応を経て達成したスコアであり、一部チェックの1回目の適用では不十分だった点は本文で述べた通りだ。

詳細はHow to Make Your Docs Agent-Ready: llms.txt, Parity, MCPを参照していただきたい。