【ITニュース解説】How to serve Markdown to AI agents: Making your docs more AI-friendly

最近、AIを使った開発支援ツールが急速に進化している。例えば、Claude CodeのようなAIコーディングアシスタントは、開発者が書いたコードをレビューしたり、新しいコードを提案したり、ドキュメントから情報を取得して質問に答えたりするなど、多岐にわたるサポートを提供している。このようなAIエージェントに、開発ドキュメントなどの情報を効率良く提供する方法が今、注目を集めている。これは、システムエンジニアを目指す皆さんにとって、今後の開発現場で非常に重要になる考え方である。

これまでの多くのウェブサイトやドキュメントは、ウェブブラウザで表示するためにHTML形式で作成されている。HTMLは、ウェブページのデザインやレイアウト、画像や動画の埋め込みなど、見た目を豊かにするための様々な要素を持つ。しかし、AIエージェントがこれらのウェブページから情報を取り込む際、このHTML形式が課題となる場合がある。AIエージェントは、ウェブページの内容を読み込むためにHTTPリクエストという通信方法を使う。その際、サーバーからHTMLデータを受け取るのが一般的だ。

問題は、HTMLが情報の内容だけでなく、その情報を「どのように表示するか」という指示（マークアップ）を大量に含んでいる点にある。例えば、「これは見出しです」「この部分は太字です」「この画像を表示してください」といった多くのタグや属性が含まれる。AIエージェントが情報を処理する際、これらのタグも「トークン」と呼ばれる単位で数えられ、処理の対象となる。トークンとは、AIが情報を理解・生成する際の最小単位のようなもので、日本語でいえば単語や記号、句読点などがこれに当たる。AIが一度に処理できるトークンの数には限りがあり、これを「コンテキストウィンドウ」と呼ぶ。つまり、HTMLの余計なマークアップが多いと、本当に伝えたい情報以外の部分でトークンが消費され、AIが一度に処理できる情報量が減ってしまうのだ。これは、AIのパフォーマンスを低下させ、回答の精度が落ちたり、処理に時間がかかったりする原因となる。

この問題を解決するのが「コンテンツネゴシエーション」という仕組みだ。これは、ウェブの基本的な通信規約であるHTTPが元々持っている標準機能の一つである。簡単に言えば、情報を要求する側（クライアント、今回の場合はAIエージェント）が「私はこの形式のデータが欲しいです」とサーバーに伝え、サーバーがそれに応じて最適な形式のデータを提供する、というやり取りである。

具体的には、クライアントはHTTPリクエストを送る際に「Acceptヘッダー」という情報を含める。Acceptヘッダーは「どんな形式のデータを受け入れられますか？」というリストのようなもので、「text/markdown（Markdown形式のテキスト）」「text/plain（プレーンなテキスト）」「text/html（HTML形式）」といった値を指定できる。もしAIエージェントが「私はMarkdown形式のデータが欲しい」とAcceptヘッダーに含めてリクエストした場合、サーバーはそのリクエストを検知し、HTMLを返す代わりに、マークアップが少ないMarkdown形式のドキュメントを返すように設定できるのだ。

Markdown形式でドキュメントをAIエージェントに提供することには、いくつかの大きなメリットがある。まず、HTMLに比べてマークアップが非常にシンプルであるため、同じ内容の情報でも消費するトークン数が大幅に少なくなる。これにより、AIはより多くの実質的な情報を一度に処理できるようになり、コンテキストウィンドウを効率的に活用できる。結果として、AIはドキュメントの内容をより深く理解し、質問に対してより正確で詳細な回答を生成できるようになる。また、Markdownは構造が明確で人間にとっても読みやすいため、AIにとっても解析が容易になるという利点もある。

この仕組みをウェブサーバーに実装する基本的な考え方は、ほとんどのプログラミング言語やフレームワークで共通している。ウェブサーバーがクライアントからのリクエストを受け取ったとき、まずそのリクエストに含まれるAcceptヘッダーの内容を確認する処理を行う。

例えば、ウェブサイトのドキュメントページへのリクエストが来た場合、サーバーは以下のように動作する。

1. リクエストのAcceptヘッダーを読み取り、「text/markdown」が含まれているかを確認する。
2. もし「text/markdown」が含まれていれば、そのページに対応する生のMarkdownファイルの内容を読み込む。
3. 読み込んだMarkdownコンテンツを、レスポンスの「Content-Type」ヘッダーを「text/markdown」に設定してクライアントに返す。このとき、HTMLのタグなどは一切含まれない、純粋なMarkdownのテキストデータだけが返される。
4. もしAcceptヘッダーに「text/markdown」や「text/plain」が含まれていなければ、つまり通常のウェブブラウザからのリクエストであると判断される場合は、従来通りHTML形式でページをレンダリングし、クライアントに返す。

このように、サーバーはリクエストに応じて返すデータの形式を動的に切り替えることで、通常のブラウザ利用者の利便性を損なうことなく、AIエージェントに対して最適な形式で情報を提供できるのである。

実装が完了したら、それが正しく機能するかどうかを確認する必要がある。これには「curl」というコマンドラインツールが便利である。curlを使って、異なるAcceptヘッダーを付けてウェブサーバーにリクエストを送ってみる。 例えば、「Accept: text/markdown」というヘッダーを付けてリクエストを送信した場合、サーバーからの応答のContent-Typeヘッダーが「text/markdown」となっており、レスポンスボディにはHTMLタグを含まない生のMarkdownコンテンツが返ってくれば成功である。同様に、「Accept: text/html」を付けてリクエストした場合には、通常のHTMLページが返ってくることを確認する。

このように、AIエージェントとの連携を考慮したドキュメント提供は、今後のシステム開発において効率的かつ高品質なAI活用を実現するための重要なステップとなるだろう。システムエンジニアを目指す皆さんは、こうした最新の技術トレンドと、その背景にあるウェブの基本的な仕組みを理解しておくことが、これからのキャリアにおいて非常に役立つはずである。