Markdown、やめてみた。HTMLで出力させたら読まれ方が変わった話。

2026年5月11日 4 min read

「またMarkdownファイルが生成された。」

Claude CodeやCodexに何かまとめてもらうたびに、.mdファイルが出てくる。開いても、文字と記号の羅列。読みやすいとは言いがたい。非効率。

Xのタイムラインで見かけた一言が引っかかった。

「AIに頼むときは、MarkdownじゃなくてHTMLで出力してもらえ。読まれ方が全然違う。」

Simon Willison（Webエンジニアで有名な人）が書いた記事「Using Claude Code: The Unreasonable Effectiveness of HTML」が元ネタ。コードが得意ではない私でも、試せる話だと思った。やってみた。

Claude Codeに相談した

プロンプトはシンプルに変えた。

いつも：「〇〇についてまとめて」
変えた後：「〇〇についてHTMLで出力して」

一言追加しただけ。それだけで、返ってくるものが別物になった。

Markdownだと100行超えると見返す気が起きなかった。HTMLで来たものは、表があって、色があって、見出しで飛べる。ブラウザで開くだけでいい。URLで渡せる。

「あ、これ読んでもらえる形だ。」と思った。

Markdown vs HTML ── AIアウトプット比較

.md

共有方法ファイル添付が必要。URLで渡せない。

デザイン色・グラフ・タブなし。プレーンテキスト。

100行超え読む気が失せる。スクロールするだけ。

インタラクションコピーボタン・フィルターなし。

✅ 向いてる用途AIへの指示・CLAUDE.md・設定ファイル

↓

.html

共有方法ブラウザで開ける。URLで即共有。

デザイン表・色・グラフ・タブが1ファイルに。

長文でも読まれる視覚整理で最後まで見てもらえる。

インタラクションコピーボタン・フィルター・ライブ表示。

✅ 向いてる用途レポート・仕様書・診断ツール・成果物

⚠ 注意点　HTML生成はMarkdownの2〜4倍のトークンを消費。生成時間も伸びる。バージョン管理（Git diff）も複雑になる。用途を見極めて使い分けること。

原則：「MarkdownはAIへの入力。HTMLは人間へのアウトプット。」

そこだけは正直に書く。

HTMLはMarkdownの2〜4倍のトークンを消費する。生成に時間もかかる。Claude ProプランやCodexの利用上限に近い人は注意。「全部HTMLで」は逆に非効率になる。

バージョン管理（Git）も複雑になる。差分が見にくい。チームで管理するファイルには向かない。

結論は一行で言える。

「MarkdownはAIへの入力。HTMLは人間へのアウトプット。」

CLAUDE.mdやAGENTS.mdのようなAIへの指示ファイルはMarkdownでいい。むしろMarkdownが正解。AIが読むものにデザインは必要ない。

一方、人間が読む成果物——レポート、仕様書、提案書、診断ツール——はHTMLの方が読まれる。「読んでほしい」ならHTML。「AIに渡す」ならMarkdown。それだけ。

私のプロジェクトで具体的に変えたこと。

SNS投稿の分析レポートをClaude Codeに出してもらうとき、以前はMarkdownで受け取っていた。それをHTMLで出力させるようにした。ブラウザで開いてそのまま見返せる。チームに渡すときもURLひとつで済む。

診断コンテンツや商品ページの草案も、HTMLで出力させると最初からデザインが整っている。修正の手間が減った。

コストはかかる。でも「読まれない資料を安く作る」より「読まれる資料を少し高く作る」方が結果につながる。

次にClaude CodeやCodexに何かまとめてもらうとき、プロンプトの末尾に「HTMLで出力して」を足してみて。

たった一言。変わるかどうか、自分で確認した方が早い。

非効率は罪。読まれない資料も、罪。