AI Agentの出力形式：HTMLとMarkdownの選び方
この記事で学べること
- Claude CodeチームがHTMLを使う目的と、AIの入力精度に関する議論との違い
- HTMLとMarkdownがそれぞれ適するレビュー・共有・編集の場面
- AI Agentの成果物をHTML、Markdown、XML、JSONから選ぶ判断基準
HTMLとMarkdownの選択基準
AI Agent（指示に沿って調査や作業を進めるAI）の成果物は、受け取った人が何をするかに合わせて形式を選びます。長い調査結果を画面上で比較し、意思決定に使いたいならHTMLが候補になります。人が文章を直接編集し、変更前後の違いを残したいならMarkdownが扱いやすいでしょう。
HTMLは、<h1>見出し</h1>のようなタグで見出しや表などを指定し、Webページの構造を表す形式です。Markdownは、行頭の#で見出し、-で箇条書きを書くなど、簡単な記号で文章を整理できる形式です。
Claude Code（ファイルを読み書きし、開発作業などを進めるAnthropicのAIツール）のチームによるHTML活用例を手がかりに、それぞれに向く確認・共有・編集の場面を比べます。AIに情報を渡す形式と、人が成果物を読む形式を区別することで、自分の作業に合う形式を判断できます。
Claude CodeチームのHTML活用と人によるレビュー
この議論の一次出典は、AnthropicのClaude公式ブログに掲載されたThariq Shihipar氏の記事です。記事は2026年5月20日に公開され、Shihipar氏はClaude CodeチームのMember of Technical Staff（技術職のスタッフ）として紹介されています。[1]
この記事で提案されているのは、Claude Codeが作る計画、仕様、分析、レビュー用資料を、人が読み、共有し、操作しやすいHTMLで出力することです。「HTMLを入力すれば、MarkdownよりAIの理解や回答精度が上がる」という主張とは区別する必要があります。
Shihipar氏は、100行を超えるMarkdownファイルを自分でも読まなくなり、組織内の他者にも読んでもらいにくいと説明しています。そのうえで、HTMLなら視覚的な構成、図、リンク、タブ、操作機能を使えるため、AIの判断に人間が関与し続けやすくなると述べています。[1]
HTMLに向く計画書・調査レポート・比較画面
HTMLで成果物を作ると、文章、表、図、コードへの注釈に加え、ボタンや入力欄などの操作画面を1つのファイルにまとめられます。長い計画書でも、全体像と詳細を同じ画面で確認できます。
Claude公式ブログでは、HTMLの利点として、一画面に示せる情報の多さ、視覚的な読みやすさ、共有しやすさ、読む人が内容を操作できることを挙げています。また、Claude Codeが読み込めるコードや関連資料を、成果物の作成に活かせる点も説明しています。[1]
実務で特に意味があるのは、次のような成果物です。
| 成果物 | HTMLで得られる利点 |
|---|---|
| 実装計画 | 全体像、データの流れ、リスク、コード例を同じ画面で確認できる |
| 変更提案の説明 | 変更前後の違い、注釈、重要度、ほかの機能との関係を視覚的に並べられる |
| 調査レポート | 要約、詳細、出典、比較表を段階的に読める |
| デザイン比較 | 複数案を横並びにして、条件や、各案の利点と引き換えに生じる制約を比較できる |
| 一時的な編集画面 | 仕事の分類、AIへの指示調整、決まった形式のデータ出力などを操作できる |
ここでいう「情報密度」は、トークン（AIが処理する文字列の単位）を少なくするという意味ではありません。人間が一画面で把握できる関係性を増やす、という意味です。
AIへのHTML入力が有効になる条件
人が読みやすい出力と、AIが処理しやすい入力は、別の問題です。AIへの入力形式としてHTMLが常に優れているとは言えません。ただし、RAG（質問に関係する情報を検索し、その情報を使ってAIに回答させる方法）では、Webページの見出しや表の構造を残すことが有効になる場合があります。
HtmlRAGの研究は、検索したWebページを装飾のない文章だけへ変換すると、見出し、表、リンクなどの構造情報が失われる点に注目しています。この研究では、不要部分の削除、短縮、関係の薄い部分の除外によってHTMLを短くし、6種類の質問回答用データで結果を評価しています。[2]
HTMLが入力形式として有利になり得るのは、次のような構造をAIに渡したい場合です。
- 大見出しと小見出しの階層
- 複雑な表の行・列の関係
- リンク先とアンカーテキスト（リンクとして表示される文字）の関係
- コード、引用、ページ内の案内メニューの区別
- ページ全体の見出しや項目の親子関係
一方で、同研究は生のHTMLをそのまま渡すことを推奨しているわけではありません。元のHTMLは長く、CSS（文字や配置などの見た目を指定する記述）、JavaScript（画面の操作や処理を動かすプログラム）、コード内のコメントなど、回答に不要な情報を含みます。不要部分を削除したうえで、質問に関係する見出しや表などの構造を残す必要があります。[2]
入力形式による性能差と、AIの種類・作業による違い
AIへの指示や情報を、どの形で渡すかによって性能が変わる場合があります。同じ内容でも、装飾のない文章で渡すのか、Markdownの見出しや箇条書きを使うのか、項目名と値を組にするのかで、AIが受け取る構造は異なります。ただし、すべてのAIの種類と作業に共通する最適な形式は確認されていません。
MicrosoftとMITの研究では、同じ内容をPlain text（装飾のない文章）、Markdown、JSON、YAMLで表現し、複数のGPT系モデル（GPTシリーズのAI）で評価しています。JSONとYAMLは、項目名と値を組にして情報を表すデータ形式です。結果として、形式によって性能が変わる一方、AIの種類や作業を問わず常に最良になる単一の形式は見つかっていません。[3]
AnthropicのClaude向けプロンプトガイドでは、複雑な指示を整理する方法としてXMLタグが紹介されています。XMLタグは、<instructions>と</instructions>のように開始と終了を示す記号で、内容の範囲を区切ります。指示、背景情報、入力、例をそれぞれ別のタグで囲むと、AIに何を指示し、何を参考情報として渡したのかを明確にできます。これはHTMLによる成果物の表示とは用途が異なります。[4]
HTML、Markdown、XML、JSONは、使う目的に応じて選ぶ方が実務的です。
Markdownに向く文書の編集と変更履歴の管理
Markdownは、見出しや箇条書きに加え、表やコードを記号で簡潔に書けます。短い技術文書や、Git（ファイルの変更履歴を記録し、変更前後を比較できるツール）で管理する仕様書に向いています。
Markdownが適しているのは、次のような場面です。
- README（プロジェクトの概要や使い方を記した案内文）や短い設計メモ
- Gitで変更前後を直接比較したい仕様書
- 人が頻繁に手で編集する文書
- AIに大量のテキストを渡す際、入力のトークン数や費用を抑えたい場合
- 操作機能を持たず、情報を文書として蓄積するナレッジベース
- JavaScriptの実行を避けたい共有資料
HTMLは多様な見せ方ができる一方で、タグ、CSS、JavaScriptによってファイルが長くなりがちです。文章の修正だけを確認したい場合も、見た目や動作の変更が混ざると、差分を追いにくくなります。
AIが生成したHTMLを公開・共有する際は、外部との通信、動作を確認していないJavaScript、XSS（Webページ上で意図しないスクリプト（プログラム）が実行される攻撃）に注意が必要です。
MDNでは、実行範囲を制限する手段として、CSP（Content Security Policy、読み込めるスクリプトや画像などを制限する仕組み）と、iframe（別のWebページを画面内に埋め込む要素）のサンドボックス属性を説明しています。サンドボックス属性は、埋め込んだページが実行できる操作や権限を制限します。[5][6]
確認・編集・データ交換に応じた形式の使い分け
実務で形式を選ぶ際は、誰が読むのか、どう編集するのか、何を検証するのかを確認します。人が見る画面、AIへの指示、サービス間のデータ交換では、同じ内容でも適した形式が変わります。
| 目的 | 向いている形式 |
|---|---|
| 短い指示、案内文、変更履歴を残すメモ | Markdown |
| 複雑なAIへの指示を区切る | 開始と終了をタグで示すXML |
| Webページから検索した情報をAIへ渡す | 不要部分を除いたHTML |
| 長い計画書、調査レポート、変更提案の説明 | HTML |
| 比較、調整、承認が必要な作業 | インタラクティブHTML |
| サービス間で決められた項目を正確に渡す | JSONなど、項目と形式のルールが決まったデータ |
本文で比較した用途から、AI Agentの成果物は「あとで文章を編集し、Gitで変更履歴を残す文書か」「その場で情報を比較して判断する画面か」で整理できます。前者にはMarkdown、後者にはHTMLが候補になります。
Claude CodeへのHTML作成依頼の例
HTMLを使う場合は、見た目だけでなく、レビューや修正に必要な操作を明示します。外部ライブラリ（別途読み込む、再利用可能なプログラム）や外部との通信を使わない指定にすると、共有時のリスクも抑えやすくなります。
このプロジェクトの実装計画を、単一のHTMLファイルとして作成してください。
次の要素を含めてください。
- 全体像を理解できる図
- 主要なデータフロー
- 重要なコード例
- リスクと未確定事項
- 実装ステップ
- 詳細を折りたためる構成
長い文章を並べるのではなく、人間がレビューし、
判断・修正しやすいインターフェースとして設計してください。
外部ライブラリや外部通信は使用しないでください。このプロンプトの要点は、出力形式だけでなく「人間が何を判断するための画面か」を指定していることです。HTMLは文書形式であると同時に、レビューに使う一時的な操作画面としても使えます。
まとめ：受け手の作業と情報を渡す目的に合う形式
成果物を画面で読み、比較して判断する場面にはHTML、人が文章を編集し、変更履歴を残す場面にはMarkdownが候補になります。AIへの入力では、複雑な指示を区切るXMLタグや、項目と形式を決めてデータを渡すJSONなど、用途に合う形式を選びます。
人が読みやすいことと、AIの回答精度が高まることは別の判断です。HTMLをAIへ渡す場合も、不要部分を除いて必要な構造を残す条件を踏まえる必要があります。
本記事は一般的な情報整理であり、法的助言ではありません。実務判断は専門家に確認してください。
参考文献
- Anthropic, Using Claude Code: The unreasonable effectiveness of HTML, 2026年5月20日
- Jiejun Tan, Zhicheng Dou, Wen Wang, Mang Wang, Weipeng Chen, Ji-Rong Wen, HtmlRAG: HTML is Better Than Plain Text for Modeling Retrieved Knowledge in RAG Systems, 2024年11月
- Jia He, Mukund Rungta, David Koleczek, Arshdeep Sekhon, Franklin X Wang, Sadid Hasan, Does Prompt Formatting Have Any Impact on LLM Performance?, 2024年11月
- Anthropic, Prompting best practices, Claude Platform Docs
- MDN Web Docs, Content Security Policy (CSP), MDN Web Docs
- MDN Web Docs,
<iframe>: The Inline Frame element, MDN Web Docs
最新のリリースやアップデートの詳細は、公式サイト・公式ドキュメントを確認してください。