ClaudeにHTMLでコンテキストを渡す方法と理由【実例コード付き】
ClaudeにコンテキストやレポートをMarkdown形式で渡してた人、ちょっと聞いてください！
HTML形式に切り替えると情報の伝わり方がめちゃくちゃ変わる可能性があって、2026年5月8日にAnthropicエンジニアのThariq ShihiparがHTMLをコンテキストに使う利点をまとめた記事「The Unreasonable Effectiveness of HTML」を公開したら、エンジニアコミュニティでほんまに大きな議論が起きたんですよ。
本記事では、その背景・理由・具体的な実装方法をまとめていくので、一緒に確認してみてください。
きっかけは1人のAnthropicエンジニアの投稿
2026年5月8日、AnthropicのエンジニアThariq ShihiparがAnthropic公式ブログに「The Unreasonable Effectiveness of HTML」を公開したんですよね（原文リンク）。
この記事に連動したX（旧Twitter）の投稿は440万ビュー・8,200いいね・15,700ブックマークを記録したんですよ。
数多くのエンジニアが「自分もMarkdownをやめた」「ずっとそうすべきだった」と反応して、SNS上でめちゃくちゃ広く拡散されました。
著名な開発者Simon Willisonも同日、自身のブログ（simonwillison.net）でこの記事を取り上げて、長年のMarkdownデフォルト使用を見直して試した結果かなり良好だったという姿勢を示してるんですよね。
単なる追従ではなく検証を経た上での評価なんやからこれは信頼性も高いじゃないかなと思います。
なぜこれほど反響を呼んだのか
MarkdownはAIへのコンテキスト渡しにおいてぶっちゃけ長年のデファクトスタンダードだったんですよ。
それを根拠とともに否定する投稿が、Anthropic公式ブログから発信されたことが反響の大きさにつながったんですよね。
「公式が言うなら試してみよう」という動機も相まって実際に検証したユーザーからの報告が次々と上がる展開になりました。
そもそもなぜMarkdownが「AI向けデフォルト」になったのか
じゃあ、まずはMarkdownがデフォルトになった理由から整理するんですけど、これは技術的な制約にあるんですよ。
2022年頃のGPT-4時代、コンテキストウィンドウの上限は8,192トークンで限られたトークン数でできる限り多くの情報を詰め込むには、HTMLタグのオーバーヘッドを排除したMarkdownが合理的な選択だったんです。
「トークンを節約するためにMarkdownを使う」って慣習はこの制約から生まれて、そのまま惰性的に引き継がれていったんですよね。
で、2026年現在、主要LLMのコンテキストウィンドウはマジで大幅に拡張されて、Claude Sonnet 4.6・Opus 4.6以降では100万トークン規模に達してるんですよ。
「トークンが足りない」という制約はほとんど消えてるから、トークン節約を理由にMarkdownを選ぶ根拠は、現在の技術環境ではもう成立しなくなってるんです。
前提が変わった以上、フォーマット選択の判断軸も更新してみる余地がじゅうぶんあるんじゃないかな。
HTMLがMarkdownより適している5つの理由
1. 情報密度
まず1つ目は情報密度なんですけど、MarkdownはプレーンテキストとHTMLタグの限定的なサブセットしか扱えないんです。
HTMLであれば、CSS・SVG・テーブル・インラインスクリプトを組み合わせることで、色分け・グラフ・バッジなど視覚的な構造を1ファイルに収められるんですよね。
同じ情報量をMarkdownで表現しようとすると複数ファイルや外部画像に頼ることになってコンテキストが分散しちゃう。
2. 可読性
次2つ目は可読性で、エンジニアコミュニティでは「長大なMarkdownは実際には読まれない」って指摘がよく共有されてます。HTMLの<details>タグと<summary>タグを使えば、長いレポートをデフォルトで折りたたんだ状態で提供できるんです。目次や内部リンクも実装できるから、人間が参照するドキュメントとして、ほんまにちゃんと機能するんですよね。
3. 共有性
3つ目は共有性なんやけど、HTMLファイルはブラウザで直接表示できるんですよ。チームメンバーへの共有はURLまたはファイル送付のみで完結して、Markdownレンダラーやツールへの依存がないから、ローカルで開いても同じ見た目になって再現性が高いんです。
4. 双方向性
4つ目は双方向性で、HTMLであれば、スライダーやボタンを使ったインタラクティブなパラメータ調整をページ内に組み込めるんですよね。「このパラメータを変えたらどうなるか」をその場で試せるレポートって、Markdownでは実現できないんですよ。これマジでえぐいと思いません？
5. コンテキストの豊富さ
最後5つ目はコンテキストの豊富さで、SlackやLinear、gitログといったMCPツールからの情報をHTMLに整形してClaudeに渡すと、情報の構造がそのまま保持されるんですよ。Markdownに変換する過程で失われる階層や色分けの情報を維持できるやから、モデルが参照できるコンテキストの質がめちゃくちゃ上がるんです。
実例コード：同じ内容をMarkdownとHTMLで比較
じゃあ、同じ週次ステータスレポートをMarkdownとHTMLそれぞれで書いた場合の差を確認してみましょう。
Markdown版：
## 週次ステータスレポート
### 完了タスク
- ユーザー認証の実装
- APIエンドポイントのテスト
### 課題
- パフォーマンス改善が未完了HTML版：
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<style>
body { font-family: system-ui, sans-serif; max-width: 800px; margin: 2rem auto; }
details { border: 1px solid #ddd; border-radius: 4px; margin: 0.5rem 0; padding: 0.5rem; }
summary { font-weight: bold; cursor: pointer; }
.done { color: #16a34a; }
.issue { color: #dc2626; }
</style>
</head>
<body>
<h1>週次ステータスレポート</h1>
<details open>
<summary>✅ 完了タスク</summary>
<ul class="done">
<li>ユーザー認証の実装</li>
<li>APIエンドポイントのテスト</li>
</ul>
</details>
<details>
<summary>⚠️ 課題</summary>
<ul class="issue">
<li>パフォーマンス改善が未完了</li>
</ul>
</details>
</body>
</html>HTML版では、完了タスクと課題がそれぞれ色分けされて折りたたみ可能なセクションに分かれてるんですよね。情報量はMarkdown版と同じなんやけど、状態（完了・課題）が視覚的にばっちり区別されてるから、Claudeがコンテキストとして読んだ場合にも構造が明確に伝わるんです。ブラウザで開けばそのまま確認できる点も、共有コストをめちゃくちゃ下げてくれますよ。
実例20件はThariqのGitHubページ（thariqs.github.io/html-effectiveness）で公開されてるんで、様々なユースケースでの活用パターンをぜひ確認してみてください。
トークンコストの現実：HTMLは高くつくのか
HTMLはMarkdownよりトークン数が多くなるのは事実なんですよ。pasqualepillitteri.it（2026年5月）が実施した検証データによると、同じ内容での比較はこんな感じです。
| フォーマット | トークン数（目安） | コスト概算 |
|---|---|---|
| Plain Markdown | 約1,140 | $0.017 |
| Lean HTML | 約2,760 | $0.041 |
| Full HTML（CSS・バッジ等込み） | 約5,480 | $0.082 |
出典：pasqualepillitteri.it（2026年5月）
数字だけ見るとFull HTMLはMarkdownの約5倍のコストになるんですよね。でも、100万トークンのコンテキストウィンドウを基準に考えると、Full HTMLのコンテキスト使用率は0.55%にすぎないんですよ。コンテキスト全体から見たら残り99.45%は依然として使用可能な状態にあるんやから、「HTMLは高い」ってびびる必要はないじゃないかな。
「HTMLは高い」って印象は、ぶっちゃけトークン制限が厳しかった時代の感覚が残ってるだけのケースが多いんですよ。
絶対値じゃなくて使用率で考えたとき、情報の構造品質を優先した選択のほうが最終的なアウトプットの質に直結する場面って、ほんまにたくさんあるんです。
HTMLが向かないケース（使い分けの基準）
じゃあ、HTMLに全部切り替えればいいかというとそうでもなくて、使い分けの基準を一旦整理しておくのが大事なんですよね。
最も有効な判断軸は「その情報は人間が読むのか、AIが読むのか」ってこと。
Markdownが依然として有利なケース
- Gitで管理・チームが編集するドキュメント：HTMLタグはdiffが汚染されるんですよ。
</div>や<style>の変更がコードレビューのノイズになって、共同編集コストが上がっちゃう。 - 短い指示・簡単なメモ：数百字の指示であれば、HTMLのオーバーヘッドはコスト対効果の面で合わないんです。Lean HTMLでも2倍以上のトークンを消費するからね。
- エージェントループ内部でAIのみが読む中間出力：AIが次のステップで処理する中間データは、構造よりも機械可読性が優先されます。HTMLの視覚的構造はこの用途では不要なんです。
HTMLが力を発揮するのは「人間が確認し、Claudeが参照して作業する」っていう構成のとき、あるいは「Claude自身が成果物としてHTMLを生成する」ときなんですよ。コンテキストのフォーマットを変えることは、出力品質に直接影響するんですよね。
「md原本＋html共有用」のCompanion Fileパターンも、現実的な運用として機能するんですよ。
Gitで管理するMarkdownファイルと、チームや外部共有用のHTMLファイルを並存させることで、両方の利点を目的別に使い分けられるから、めちゃくちゃ柔軟な運用ができるんです。
CLAUDE.mdへの追加プロンプト例（今日から使える）
そしたら、実際に試してみる方法も紹介しますね。HTMLでの出力をClaudeに指示する場合、CLAUDE.mdへの追記が最もシンプルな方法なんですよ。beginnersinai.orgが公開しているプロンプト例をベースにした記述はこんな感じです。
# CLAUDE.mdに追記する場合
Output format: HTML
Use semantic HTML tags. Include color callouts for warnings and tips.
Prefer real <table> elements over Markdown pipe tables.記述する際の注意点として、シングルファイルルールを守ることが大事なんですよ。外部CDNへの参照（BootstrapやTailwindなど）を使うと、ファイルが単体で機能しなくなってしまうやから、インラインCSSとインラインJSで完結させることで、どの環境でも同じ表示になる再現性が担保されるんです。
コンテキストとして渡すHTMLを自分で作成する場合も、同じシングルファイルの原則が適用されるんですよね。CSSは<style>タグ内に、JavaScriptは<script>タグ内に記述して一つのファイルにまとめてみてください。
まとめ
Markdownがデフォルトになったのはトークン制限っていう技術的制約があったからで100万トークン時代にその前提が消えた今、フォーマット選択の判断軸を更新してみる余地がめちゃくちゃあるんです。
HTMLへの切り替えが有効なのは、人間がレビューしてClaudeが参照するコンテキストを扱うとき、
そしてClaudeが成果物として読みやすいドキュメントを生成するときなんですよね。
Gitで管理するドキュメントや短い指示では、Markdownのシンプルさが引き続き有効に機能するから、そこは使い分けでオッケーです。
とりあえず、すぐ試せる出発点として3つ挙げておきますね。
- CLAUDE.mdに
Output format: HTMLを追記してClaudeの出力フォーマットを変えてみてください - 週次レポートや調査サマリーなど、定期的に参照するコンテキストをHTMLに移行してみて
- 必要に応じてCompanion Fileパターン（md原本＋html共有用）で運用を設計してみてください
FAQ
Q. ClaudeへのコンテキストにHTMLを渡すとは何ですか？
ClaudeにコンテキストとしてHTMLファイルを入力することで、CSS・SVG・テーブル・折りたたみセクションなどを含む構造化された情報を渡す手法です。2026年5月にAnthropicエンジニアThariq Shihiparが「The Unreasonable Effectiveness of HTML」として提唱して、エンジニアコミュニティでほんまに広く注目されたんですよね。Markdownに比べて情報の構造と視覚的な区別が保たれるから、モデルが参照しやすいコンテキストを構築できるんです。
Q. HTMLとMarkdownどちらをClaudeに渡すべきですか？
「その情報を人間が確認してからClaudeが参照するか」を判断軸にするといいです。人間が読む共有レポートやステータスドキュメントにはHTMLが有効で、Gitで管理するチーム編集ドキュメントや短い指示にはMarkdownが合理的なんですよね。エージェントループ内でAIのみが読む中間出力はMarkdownが向いてるんで、用途に合わせて使い分けてみてください。
Q. CLAUDE.mdでHTMLを指定するにはどうすればいいですか？
CLAUDE.mdに以下の3行を追記するだけでオッケーです。Output format: HTML、Use semantic HTML tags. Include color callouts for warnings and tips.、Prefer real <table> elements over Markdown pipe tables.。
外部CSSライブラリへの参照は避けて、インラインCSSとインラインJSで完結させるシングルファイル形式を守ってみてください。
Q. HTMLはMarkdownよりトークンを多く消費しますか？
消費するのは本当ですね。pasqualepillitteri.it（2026年5月）の検証によると、Plain MarkdownはClaude APIで約1,140トークン（コスト概算$0.017）で、Full HTMLはCSS・バッジ込みで約5,480トークン（$0.082）になるんです。でも、100万トークンのコンテキストウィンドウを持つモデルにおけるFull HTMLのコンテキスト使用率は0.55%にとどまるんですよね。絶対コストじゃなくて、コンテキスト全体に占める比率で判断するほうが現実的じゃないかなと思います。
参考情報
- Anthropic公式ブログ「The Unreasonable Effectiveness of HTML」（https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html）
- Simon Willison’s Weblog（https://simonwillison.net）
- pasqualepillitteri.it トークンコスト検証記事（https://pasqualepillitteri.it）
- Thariq Shihipar GitHubページ（https://thariqs.github.io/html-effectiveness）
- beginnersinai.org プロンプト例（https://beginnersinai.org）
