AI Agentの出力形式：HTMLとMarkdownの選び方
この記事で学べること
- Claude CodeチームがHTMLを使う目的と、AIの入力精度に関する議論との違い
- HTMLとMarkdownがそれぞれ適するレビュー・共有・編集の場面
- AI Agentの成果物をHTML、Markdown、XML、JSONから選ぶ判断基準
出力形式は、読んだあとに何をするかで選ぶ
長い調査結果を受け取ったあと、Webページのような画面で比較して意思決定したいならHTMLが役立ちます。見出しや箇条書きを簡単な記号で書き、変更前後の違いを確認しながら残したいならMarkdownが扱いやすいでしょう。どちらが常に優れているという話ではなく、AIの成果物を人がどう確認し、その後どう編集するかで選択が変わります。
この記事では、「人の次の作業に合わせてHTMLとMarkdownをどう選ぶか」という問いに焦点を当て、選択を分ける比較軸、向いている条件、選択後の確認事項を扱います。
最後まで読むと、「人の次の作業に合わせてHTMLとMarkdownをどう選ぶか」という問いを、自分の状況に照らして判断するための材料を持ち帰れます。
HTMLの提案は「AIの精度」より「人の確認」の話
この議論の一次出典は、AnthropicのClaude公式ブログに掲載されたThariq Shihipar氏の記事です。記事は2026年5月20日に公開され、Shihipar氏はClaude CodeチームのMember of Technical Staffとして紹介されています。[1]
公式ブログの主張は、単に「HTMLはMarkdownよりAIに理解されやすい」という話ではありません。より正確には、Claude Codeが作る計画、仕様、分析、レビュー用資料を、人間が読み、共有し、操作しやすくするためにHTMLを使うという実務上の提案です。
Shihipar氏は、100行を超えるMarkdownファイルを自分でも読まなくなり、組織内の他者にも読んでもらいにくいと説明しています。そのうえで、HTMLなら視覚的な構成、図、リンク、タブ、操作機能を使えるため、AIの判断に人間が関与し続けやすくなると述べています。[1]
HTMLが向いているのは複雑な成果物を確認する場面
HTMLとは、Webページの構造を表す形式です。AI Agentの出力として使う場合、文章だけでなく、表、図、コード注釈、操作UIを1つのファイルにまとめられます。
Claude公式ブログでは、HTMLが有効な理由として、情報密度、視覚的な読みやすさ、共有しやすさ、双方向の操作、Claude Codeが取り込める文脈の活用が挙げられています。[1]
実務で特に意味があるのは、次のような成果物です。
| 成果物 | HTMLで得られる利点 |
|---|---|
| 実装計画 | 全体像、データフロー、リスク、コード例を同じ画面で確認できる |
| 変更提案の説明 | 変更前後の違い、注釈、重要度、ほかの機能との関係を視覚的に並べられる |
| 調査レポート | 要約、詳細、出典、比較表を段階的に読める |
| デザイン比較 | 複数案を横並びにして、条件やトレードオフを比較できる |
| 一時的な編集画面 | 仕事の分類、AIへの指示調整、決まった形式のデータ出力などを操作できる |
ここでいう「情報密度」は、トークン（AIが処理する文字列の単位）を少なくするという意味ではありません。人間が一画面で把握できる関係性を増やす、という意味です。
AIへの入力形式としてのHTMLは条件付きで有効
AIへの入力としてHTMLが常に優れているとは言えません。ただし、質問に関係する情報を検索してAIへ渡すRAGでは、Webページの見出しや表の構造を残すことが有効になる場合があります。
HtmlRAGの研究は、検索したWebページを装飾のない文章だけへ変換すると、見出し、表、リンクなどの構造情報が失われる点に注目しています。この研究では、不要部分の削除、短縮、関係の薄い部分の除外によってHTMLを短くし、6種類の質問回答用データで結果を評価しています。[2]
HTMLが入力形式として有利になり得るのは、次のような構造をAIに渡したい場合です。
- 見出し階層
- 複雑な表
- リンクとアンカーテキストの関係
- コード、引用、ナビゲーションの区別
- ページ全体を見出しや項目の親子関係として表した構造
一方で、同研究は生のHTMLをそのまま渡すことを推奨しているわけではありません。元のHTMLは長く、CSS、JavaScript、コメントなどの不要情報を含むため、まず不要部分を削除し、関連する構造を残す必要があります。[2]
形式差はあるが万能の形式は確認されていない
プロンプト形式とは、同じ内容を装飾のない文章、Markdown、項目名と値を組にしたデータ形式などの、どの構造でAIに渡すかという設計です。研究上は形式によって性能差が出ることがありますが、すべてのAIモデルと仕事に共通する最適形式は確認されていません。
MicrosoftとMITの研究では、同じ内容をPlain text、Markdown、JSON、YAMLで表現し、複数のGPT系モデルで評価しています。結果として、形式によって性能が変わる一方、モデルやタスクをまたいで常に最良になる単一形式は見つかっていません。[3]
AnthropicのClaude向けプロンプトベストプラクティスでも、複雑なプロンプトを構造化する方法として、HTMLではなくXMLタグが紹介されています。たとえば、指示、文脈、入力、例を明確に分けたい場合、<instructions> や <context> のようなタグが使われます。[4]
そのため、HTML、Markdown、XML、JSONを競合する1つの序列として扱うより、用途別に分ける方が実務的です。
Markdownが適している場面も多い
Markdownとは、見出し、箇条書き、表、コードブロックなどを簡潔に書ける軽量な文書形式です。短い技術文書やGit管理の仕様では、今でも扱いやすい形式です。
Markdownが適しているのは、次のような場面です。
- READMEや短い設計メモ
- 変更履歴の管理画面で、人が変更前後を直接確認する仕様
- 頻繁に人が手で編集する文書
- AIに大量テキストを低コストで渡したい場合
- 静的なナレッジベース
- JavaScript実行を避けたい共有資料
HTMLは表現力が高い一方、タグ、CSS、JavaScriptでファイルが長くなりやすく、差分レビューもしにくくなります。特にAIが生成したHTMLを公開・共有する場合は、外部通信、未検証のJavaScript、XSS（意図しないスクリプト実行）への注意が必要です。MDNでは、CSP（Content Security Policy、読み込めるスクリプトや画像などを制限する仕組み）や iframe のサンドボックス（埋め込みページの実行権限を制限する仕組み）属性が、Webコンテンツの実行範囲を制御する手段として説明されています。[5][6]
確認・編集・再利用の次作業に合わせてHTMLとMarkdownを選ぶ
実務では、「MarkdownをHTMLに置き換える」ではなく、読む人、編集方法、検証方法に合わせて形式を選びます。
| 目的 | 向いている形式 |
|---|---|
| 短い指示、案内文、変更履歴を残すメモ | Markdown |
| 複雑なAIへの指示を区切る | 開始と終了をタグで示すXML |
| Webページから検索した情報をAIへ渡す | 不要部分を除いたHTML |
| 長い計画書、調査レポート、変更提案の説明 | HTML |
| 比較、調整、承認が必要な作業 | インタラクティブHTML |
| サービス間で決められた項目を正確に渡す | JSONなど、項目と形式のルールが決まったデータ |
私は、AI Agentの出力をレビューするときは「あとでGitで読む文書か」「その場で判断する画面か」を最初に分けるのがよいと考えています。前者はMarkdown、後者はHTMLが候補になります。
Claude Codeで試すプロンプト例
HTMLを使う場合は、見た目だけでなく、レビューや修正に必要な操作を明示します。外部ライブラリや外部通信を不要にしておくと、共有時のリスクも抑えやすくなります。
このプロジェクトの実装計画を、単一のHTMLファイルとして作成してください。
次の要素を含めてください。
- 全体像を理解できる図
- 主要なデータフロー
- 重要なコード例
- リスクと未確定事項
- 実装ステップ
- 詳細を折りたためる構成
長い文章を並べるのではなく、人間がレビューし、
判断・修正しやすいインターフェースとして設計してください。
外部ライブラリや外部通信は使用しないでください。このプロンプトの要点は、出力形式だけでなく「人間が何を判断するための画面か」を指定していることです。HTMLは文書形式であると同時に、一時的なレビューUIとしても使えます。
まとめ：HTMLとMarkdownは成果物の次の作業で選ぶ
Claude CodeチームのHTML活用論は、Markdownの全面的な置き換えではなく、AI Agentの複雑な成果物を人間が理解し、検証し、修正し続けるための提案です。
- 人間が読む長い計画書や調査レポートではHTMLが有効です
- AIへの入力としてのHTMLは、構造を残したいRAGで条件付きに有効です
- 生のHTMLをそのまま渡すより、クリーニングしたHTMLが重要です
- 短い文書、Git差分、頻繁な手編集ではMarkdownが適しています
- 複雑なプロンプトの区分にはXMLタグ、厳密なデータ交換にはJSONが向いています
HTMLが注目されている理由は、AIがMarkdownを理解できないからではありません。AIの成果物が大きくなるほど、人間がレビューのループに残るための形式が必要になるからです。
最初の行動は、成果物を受け取る人が次に「読む」「比較する」「編集する」「差分を残す」のどれを行うか決めることです。厳密なデータ交換や複雑な指示境界が主目的なら、HTMLとMarkdownの二択にせずJSONやXMLタグも検討します。
本記事は一般的な情報整理であり、法的助言ではありません。実務判断は専門家に確認してください。
参考文献
- 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
最新のリリースやアップデートの詳細は、公式サイト・公式ドキュメントを確認してください。