これから「人に見せるなら Markdown より HTML」という話をゴリゴリのMarkdownで書きます、なかなかの皮肉です。
読みにくかったら本望です。
「AIに渡すものはMarkdown、人に見せるものは HTML。」これ、海外ではこの春からけっこう議論になっていて、自分はこっち派の意見です。
500行のMarkdown、読んでますか？
Claude CodeやCodexに設計メモや調査を頼むと、だいたい Markdownで返ってくると思います。200行を超えると正直つらい。途中から流し読みになって、「まあ、それでやって」と返したり、AIが書いたものをAIに要約させたことがある人は多いと思います。
自分が読んでいない資料を、チームの誰かが読んでくれるはずもありません。だったら、最初から読みやすい形で出させればいい。
Markdownはもともと人間のためのものだった
Markdownは2004年に John Gruber が公開した記法で、公式の説明には、何より読みやすさを重視したと書いてあります。面白いのは、同じ説明の中で Markdown は HTML の代わりではないと言い切っていること。書くための形式であって、読まれるときはHTMLになる前提だったわけです。
それが20年たった今、AIの食べ物になっています。CLAUDE.mdもAGENTS.mdもllms.txt もMarkdownで書かれています。理由は様々あるでしょうが、トークン効率が大きいな要因だとは思います。Cloudflareの Markdown for Agents の発表記事は、HTML だと 16,180 トークン、Markdown だと 3,150 トークンでした。だいたい 8割減。「AIに渡すなら、Markdown」これは理にかなっています。
人に見せるならHTMLのほうが読まれる
この流れのきっかけは、Claude Codeチームの Thariq Shihipar さんが2026年5月に書いた「Using Claude Code: The unreasonable effectiveness of HTML」です。100行を超えるMarkdownは実際には読まないし、他人にはもっと読ませられない。いちいち身に覚えがある話でした。
HTMLならSVGで図が描けるし、タブや折りたたみで長い内容も整理できます。（mermaidのように苦し紛れのビジュアライゼーションに悩まされてた方は多かったはず。。）リンクを送れば誰でもブラウザで開ける。スライダーで値を調整して、決まった値を Claude Code に戻すような、その場限りの編集ツールにもなります。これは Markdown では無理です。
Simon Willisonさんも自分のブログで、GPT-4 の 8,192 トークン時代から続けてきた Markdown の癖を考え直した、と書いていました。
直すのもAIなら、Markdownである理由がない
Markdownのもう一つのよさは、手で直しやすいことでした。でも最近、自分で直していますか。Thariq さんも、直すときは Claude に頼んでいると書いています。直すのが AI なら、人間が書きやすい形式である必要はありません。読みやすければいい。
ただ、AIのほうが速くて正確とまでは言えません。METR の 2025 年の試験では、慣れたリポジトリで作業するベテランが AI を使うと、かえって作業時間が 19% 延びました。2025 年前半のツールでの話ですが、結局は人間が確認することになる。だから読みやすいほうがいいんです。
で、トークン代は？
HTML がトークンを食うのは事実です。とはいえ、Claude の公式料金表だと Claude Sonnet 5.5の出力は100万トークンあたり 10 ドル。仮に 3,000トークンの Markdown が HTMLで 3倍になっても、差は1本6セントで、10円しません（1 ドル 150 円換算）。10倍でも30セントです。5人が10分ずつ読む資料なら、人件費のほうが桁違いに大きい。
節約したいなら、一番効くのは HTML を AI に読み戻さないことです。AI にはいつも Markdown の原本を渡す。文章中心の資料なら、Markdown を pandoc で HTML にすれば LLM のトークンはゼロです。
pandoc docs/report.md -s --embed-resources --css templates/report.css -o dist/report.html
ほかにも、見た目を整えるだけなら Haiku 4.5（Sonnet 5.5 の半額）、同じ指示を毎回渡すならプロンプトキャッシュ、急がないなら Batch API で半額と、手はいくらでもあります。
HTML の書かせ方
準備は要りません。「HTML ファイルを作って」と頼むだけです。Thariq さんの html-effectiveness のギャラリーを眺めると、どう頼めばいいか感じがつかめます。見た目が「いかにも AI」になるのが嫌なら、公式プラグインの frontend-design（anthropics/claude-code）を入れておくといいです。
この PR をレビューしたいので、内容を説明する HTML ファイルを作って。
実際の diff を表示して、行ごとに注釈を付け、指摘は重要度で色分けして。
リポジトリはこう分ける
ルールは単純で、Markdown を原本としてコミットし、HTML は生成物としてコミットしない。それだけです。HTML は diff が荒れるので、レビューに向きません。
もう一つ、HTML の上で決まったことは必ず Markdown に書き戻します。サボると、半年後に誰も覚えていない HTML ファイルを掘り返すことになります。
repo/
├── CLAUDE.md # AI 向けのルール
├── docs/ # 原本（Markdown）。PR の diff でレビューする
├── templates/
│ └── report.css # HTML の共通スタイル
├── dist/ # docs/ から生成した HTML（gitignore）
└── .agent-output/ # AI が直接書いた HTML（gitignore）
CLAUDE.md にはこう書いておきます。dist/ は CI で pandoc にかけて、GitHub Pages などに出せば十分です。
## ドキュメントの扱い
- 人に見せる成果物は HTMLで `.agent-output/` に出力する
- 決定事項や仕様は必ず `docs/` の Markdown に書き戻す
- 調べものをするときはHTMLではなく `docs/` を読む
リッチな投稿先、もうYouTubeがあるのでは
冒頭の皮肉に戻ると、QiitaはただのMarkdownではありません。公式の埋め込み一覧を見ると、Mermaid の図や CodePen、YouTube、Claude Artifactsまで埋め込めます。ただ、本体は Markdownのまま。xss等の脆弱性をうまくクリアできれば記事そのものをHTMLで投稿できるプラットフォームが出てきてもおかしくないと思っています。
というか、リッチな形式で技術を学ぶ場所なら、もうYouTubeがあるんじゃないか。これはもうすでにそうなりつつあると思います。Karpathy さんは 10 月 2 日の投稿で、文章、図、HTML、解説動画の順に並べて、一番期待しているのは解説動画だと書いていました。
ただ、彼が言っているのは質問ごとにその場で作る、自分一人のための動画です。それに動画は、流し読みもコードのコピーもできません。なので自分の予想は、動画が記事を置き換えるというより、HTML の記事に動画や触れる図が混ざる形です。
で、Markdownはもう要らないのか
要ります。書く形式としても、AI に渡す形式としても、今のところ Markdownよりいいものはないと思います。ただ、人に読ませる、表現する形式としての役目は終わりつつある。それが自分の考えです。
次に Claude Codeに計画やレビューを頼むとき、最後に「HTMLファイルにして」と付け足してみてください。200 行の Markdown を流し読みしていたころには、たぶん戻れません。
改めて、この記事はMarkdownです。
参考
- John Gruber「Markdown: Syntax」Daring Fireball
- Cloudflare「Markdown for Agents の導入」（2026 年 2 月 12 日）
- Thariq Shihipar「Using Claude Code: The unreasonable effectiveness of HTML」（2026 年 5 月 20 日）、html-effectiveness
- Simon Willison「Using Claude Code: The Unreasonable Effectiveness of HTML」（2026 年 5 月 8 日）
- METR「Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity」（2025 年 7 月 10 日）
- Anthropic「Pricing - Claude Platform Docs」（2026 年 10 月 5 日参照）
- Qiita「Qiitaで埋め込み可能なコンテンツ一覧」
- Andrej Karpathy の X 投稿（2026 年 10 月 2 日）