AI に HTML を直接生成させるのはなぜ効くのか—Markdown との比較と Zenn ワークフローへの適用

はじめに

あなたは、AI エージェントが吐き出した 200 行の Markdown レポートを、本当に最後まで読み切ったことがありますか？

Anthropic で Claude Code のエンジニアリングリードを務める Thariq Shihipar は、こう書いています。

I tend to not actually read more than a 100-line markdown file, and I certainly am not able to get anyone else in my organization to read it.

（100 行を超える Markdown を私自身が読み切ることはほとんどないし、組織の誰かに読ませることはもっと難しい）

マルチエージェントで生成したレポートが、誰にも読まれないまま

tmp/

/editorial

/analytics

AI エージェントが吐き出す Markdown レポートは、長くなるほど誰にも読まれません。本記事では Claude Code で AI に HTML を直接生成させる「不当な有効性」を、Thariq Shihipar・Karpathy らの資料と Markdown との比較で検証し、Zenn 編集ワークフローへの統合案を提示します。

本記事は、Claude Code でマルチエージェントワークフローをすでに組んでいて、AI 出力レポートの表現力に限界を感じている方を対象にしています。

なぜ今、AI に HTML を直接生成させるのか？

結論から: Markdown はテキストの「狭いキャンバス」であり、AI エージェントの思考密度に対して表現力が足りません。一方で HTML+CSS+JS+SVG は単一ファイルで成立する「広いキャンバス」であり、現代の LLM はそれを高品質に書ける学習量を持っています。

Markdown の「狭いキャンバス」問題

Markdown が苦手なものを並べてみます。

• タブ式の比較: 5 つの選択肢を切り替えながら見比べる
• 空間レイアウト: 並列の概念を縦並びでしか表現できない
• インタラクション: スライダー・トグル・フィルタが置けない
• 精密な図解: Mermaid の構文制約を超える SVG 表現
• 実行可能なミニアプリ: その場で値を変えて挙動を試す

Thariq は元記事で 20 の出力例を比較し、HTML が「Markdown より consumable（消費しやすい）」だった例を 17 件挙げています（注: この具体数は二次まとめ記事による要約で、Thariq 元記事には個別比較が掲載されるのみ。出典: Anthropic's Thariq stopped writing Markdown — Chew Loong Nian）。これは「AI を賢くするための形式」ではなく、「AI のアウトプットを人間に届けるための形式」の話です。

Thariq 自身の言葉が核心を突いています。

HTML does not make AI agents smarter. It makes their output consumable.

— Thariq Shihipar（出典:

AgentUpdate.ai 要約）

Karpathy の「視覚は脳への 10 車線高速道路」論

Andrej Karpathy も 2025 年 5 月、X で同じ方向の提案をしています。「LLM への入力としては音声が便利だが、出力としては視覚が圧倒的に効率がいい」「raw text → Markdown → HTML → interactive neural video の順に情報帯域が広がる」というものです（出典: Quasa による Karpathy 解説、dsebastien.net 2026-05-12）。

Markdown は raw text に CSS が少しだけ生えたものに過ぎません。AI の応答末尾に "Format your entire response as a complete HTML document" を付けて

response.html

Markdown ファースト vs HTML ファーストで思考が変わる

結論: Markdown → HTML 変換では、AI の思考プロセスに「インタラクション」「SVG」「空間レイアウト」が最初から織り込まれません。後から見た目だけ装飾しても、表現の天井は Markdown のままです。

たとえば、AI に「3 つの設計案を比較したい」と頼んだとき。

• Markdown ファーストの場合: 表が出てくる。各案の長所短所が列挙される。読み手は表を上から下に走査する。
• HTML ファーストの場合: タブ切り替えの比較ボードが出てくる。各タブ内に「適用すべきケース」「リスク」「実装サンプル」がアコーディオンで畳まれている。ユーザーの関心軸（コスト優先か、保守性優先か）でフィルタできる。

後者を Markdown から自動変換で作るのは無理です。「インタラクションを許す」と AI に伝えた瞬間に、思考の解像度が変わる——これが Thariq の言う effectiveness の正体です。

「比較ボード」「タイムライン」「決定マトリックス」「ステップガイド」など、用途別の出力パターンを「思考フレームのプリセット」として AI に与えると効きます。AI に「どんな視点で整理するか」のメタ構造を最初から渡すことで、思考の解像度が変わるのです。

実装上は、こうしたパターンを Claude Code の

.claude/agents/<role>.md

.claude/skills/<name>/SKILL.md

Markdown と HTML の比較マトリックス

結論: 入力フォーマットとしては Markdown が依然として優位、出力フォーマットとしては HTML が優位、というのがコミュニティで支持を集めつつある見方です。

役割分担の図: LLM の出力先を「次に誰が読むか」で選ぶ

ここまでの議論を 1 枚にまとめると、Markdown と HTML は対立するフォーマットでも、片方からもう片方への変換経路でもありません。LLM が直接ネイティブ生成できる、並列の出力選択肢です。AI に「まず Markdown を書かせて、それを HTML に変換する」のではなく、最初から「次に誰が読むか」に合わせてどちらかを生成させる——これが本記事の中核主張です。

• 次に機械（LLM・RAG・Git）が読むなら Markdown: トークン効率と差分可読性に優れる。連鎖プロンプト・コンテキスト投入・diff レビュー・RAG インデックスに向く
• 次に人間が読むなら HTML+CSS+JS+SVG: タブ・スライダー・SVG 図解・空間レイアウトで情報帯域を広げる。視覚・対話・空間認知に最適化された層

LLM の出力は、用途に応じて Markdown か HTML を直接書かせる形になります。レビューサマリやプロンプト断片のように「次の LLM・Git・RAG が読む」ものは Markdown、企画書・ダッシュボード・仕様書のように「人間が読む」ものは HTML です。Markdown を経由して HTML に変換する必要はなく、後者が必要なら最初から HTML を書かせます。

なお LLM に入力するコンテキスト側（原本・RAG・参照ドキュメント）も、トークン効率と意味抽出のしやすさから Markdown が依然として有利です。RAG（検索拡張生成、Retrieval-Augmented Generation）のインデックス対象として Markdown が選ばれる理由はここにあります。

この「機械が読む用途は Markdown / 人間が読む用途は HTML、どちらも LLM がネイティブ生成」という二段構えは、Thariq 元記事と Hacker News 議論 item 48071940 の上位コメント群でも繰り返し言及されている結論です。

AI に HTML を書かせる 4 つのユースケース（仕様書・シミュレータ・SVG 図解・ダッシュボード）

結論: 単一ファイル HTML として生成させ、静的ファイルホスティング（Netlify / Cloudflare R2 等）で共有 URL 化するパターンが現実的です。依存ゼロまたは Tailwind CDN + Alpine.js（軽量フロントエンドフレームワーク、Tailwind と組み合わせて HTML 1 枚に収めやすい）の組合せが定番です。Zenn 記事内では生 HTML をレンダリングできないため、コード片とスクリーンショット・外部リンクで成果物を見せます。

ユースケース 1: インタラクティブな仕様書

仕様書を HTML で書かせると、「タブで章を切り替える」「サイドバーで該当箇所にジャンプ」「該当部分にだけアコーディオンで根拠ドキュメントを畳む」といった構造が一発で出ます。Markdown 仕様書では章間ジャンプが「目次まで戻る → 目的の節を探す」という 2 ステップになるのに対し、HTML 仕様書はタブ・サイドバー・アンカーで 1 クリックに圧縮できる体験差が生まれます。

プロンプト雛形は以下のように、単一ファイル・無依存を明示するのがコツです（HN 上位コメント item 48071940 で広く共有されている定型）。

In `spec.html`, no runtime build dependencies (Tailwind CDN is allowed),
create an interactive specification document for [機能名]. Use tabs to switch
between sections. Each section should have collapsible "rationale" details.
Output a complete, self-contained HTML document.

no external dependencies ではなく no runtime build dependencies (Tailwind CDN is allowed) とすることで、ビルド不要のまま Tailwind の組版を借ります。本番運用には Tailwind CLI ビルドが Tailwind 公式推奨です。

ユースケース 2: パラメータシミュレータ

「料金プランを 5 パラメータで計算するページ」「リトライ戦略を指数バックオフのパラメータでシミュレートするページ」など。スライダーと電卓を JS で書かせると、ステークホルダーが自分の手で値を動かして納得できます。

Markdown 表で全パターンを書き出す方法と比べ、「読まれる確率」が有意に改善する例が複数報告されています（Simon Willison の解説 は、長年 Markdown 推しだった氏が「PR レビューの差分表示や CVE 解析を対話的 HTML にすることで使われるようになった」と転向理由を述べています）。

ユースケース 3: SVG での精密図解

Mermaid は Zenn ネイティブサポートで便利な反面、ノード・矢印・サブグラフといった「決まった部品」を組み合わせる宣言型 DSL のため、自由度に上限があります。たとえば下の図は、ウェブ アプリの「キャッシュヒット時 5ms / 原本フェッチ時 150ms」という分岐を Mermaid で書いたものです。

このような 「四角・ひし形・矢印」だけで完結する単純な分岐や処理フロー であれば、Mermaid で十分です。一方で、Mermaid が苦手なのは以下のような構造です。

• 斜め線・自由曲線・任意角度の配線: たとえば AWS VPC のサブネット間トラフィックを「東西方向のフロー」「南北方向のフロー」と斜め配線で描き分けたい場合
• 要素同士の重なり・透過レイヤ:「責任境界（外側の枠）」と「コンポーネント（内側の枠）」を半透明で重ねたい場合
• 数値ラベル付きの確率遷移図: ステートマシンの各遷移に「0.83 / 0.17」のような確率を付けて視覚化したい場合
• 非対称な座標配置: タイムライン上の不等間隔配置、地理的な相対位置を反映した配置など

こうした「Mermaid の語彙の外」にある図を AI に描かせるとき、SVG コードを直接生成させて

images/<slug>/foo.svg

![](/images/ai-agent-html-output-design/diagram.svg)

sanitize-html

<script>

<animate>

なお、もう少し凝った図をマウス操作で組みたい場合は、draw.io MCP 経由でスクリーンショットを取る方式が便利です。詳しい使い分けは別記事に整理しています。

ユースケース 4: ミニダッシュボード（GA・PR レビュー指標）

/analytics

/review

ローカル単一 HTML 版（再現性重視）と Anthropic がホストする発展形 Live Artifacts（外部データソース連携）の 2 段構えがあります。Anthropic は 2025 年 10 月に Live Artifacts（Claude Artifacts の拡張機能。データソース連携で再オープン時に自動更新）を出しており、再オープン時に自動更新されるダッシュボードも作れるようになりました（出典: Use Live Artifacts in Claude Cowork）。

HTML 出力のデメリットと Markdown との使い分け方針

結論: HTML 出力は万能ではありません。

tmp

主なデメリットを整理します。

• 編集摩擦: HTML を人が手で直すのは大変で、修正のたびに LLM に再プロンプトを投げることになりがちです。
• トークンコスト: ある実測例では同じレポートで Markdown 3,150 トークン vs HTML 16,180 トークン（約 5 倍）という報告があります（出典:DIGIDAY: HTML は AI に不向き？）。一方で「確認漏れによる再生成回数」を含めればトータルで HTML が安いケースもあるという反論もあります（きしだのHatena 2026-05-09）。
• diff レビューの劣化: 属性順や空白の差分で Git レビューが荒れます。
• セキュリティ: AI 生成 HTML を社内共有する際は、以下のチェックリストで最低限の隔離を確保します。
  • 別 Origin にホスト: 社内ツールと同じ Origin に置かない（Cookie/localStorage 経由の漏洩防止）
  • iframe:

    sandbox

    属性

    sandbox="allow-scripts"

    （

    allow-same-origin

    は外す）でスクリプト実行をユニーク Origin に隔離（HTML Living Standard）
  • CSP（Content Security Policy）の付与: 外部 fetch を allowlist で制限
  • 外部 fetch の監査: 生成 HTML の

    <script>

    <img>

    fetch

    先を目検またはツールで確認
    2026 年 3 月には Claude Chrome 拡張で間接プロンプトインジェクション（外部 ウェブ ページ経由で AI に意図しない指示を流し込む攻撃）の事例も報告されています（出典:The Hacker News 2026-03）。
• ターミナル/CI ログ環境では恩恵ゼロ: CLI 出力・CI ログには HTML は不向きです。

laiso 氏の「耐久性層別化」フレームは実践的な指針になります（出典: AI 時代のリッチテキスト形式。laiso 氏のフレームを本記事の Zenn ワークフローに当てはめて再整理しました）。

「Markdown は死んだ」は誤読です。入力・原本・RAG・差分管理では Markdown が依然優位で、出力・共有・体験では HTML が優位、という役割分担が現実解です。

Zenn 編集ワークフロー（/editorial・/analytics・/review）への統合案

前提: AI エージェントで Zenn 編集ワークフローを回すとは

本セクションは、筆者が運用している「Zenn 記事の企画 → 執筆 → レビュー → 公開」を Claude Code のマルチエージェントで自動化したワークフローを前提に話を進めます。読み進めるうえで、最低限以下のイメージを共有しておきます。

• （編集会議）: 下書きスクラップを元に、編集長・SEO レビュアー・読者ペルソナなど複数の AI エージェントが議論し、ターゲット読者・構成案・絵文字・slug を決めて Issue と Draft PR を起票するスラッシュコマンド

  /editorial

• （執筆）: Researcher・Writer・Reviewer などのエージェントが協調して記事本文・図表・レビューを生成するスラッシュコマンド

  /draft

• （追加レビュー）: 構成レビュー → SEO + 技術レビュー → 読者視点 → 批判的レビュー → 編集長統合判断、の 5 ステージ逐次パイプラインで再レビューするスラッシュコマンド

  /review

• （GA 分析）: Google Analytics のデータをエージェントが読み込み、人気記事・流入キーワード・低パフォーマンス記事を要約するスラッシュコマンド

  /analytics

これら 4 つは Claude Code のカスタムスラッシュコマンドとして実装されており、最終成果物（企画書・記事ドラフト・レビューサマリ・GA レポート）はすべて Markdown ファイルとして

tmp/

このワークフローを使っていると、Markdown レポートが量産されすぎて、誰も読まない問題が直撃します。

/editorial

/analytics

/review

統合方針: 最終出力レイヤだけ HTML 化する

結論: 既存の

/editorial

/analytics

/review

統合ポイント 1:

/editorial

の企画ドラフトを HTML 化

編集会議の企画案を「3 つの構成案を比較するタブ式 HTML」として生成させ、

tmp/editorial/<slug>/proposal.html

統合ポイント 2:

/analytics

のレポート HTML 化

GA データの分析結果を、フィルタ可能な単一 HTML ダッシュボードとして書かせます。エージェント定義（

.claude/agents/data-analyst.md

- 結果は Markdown 表形式で提示してください。
+ 結果は単一ファイル HTML として `tmp/analytics/<slug>.html` に書き出してください。
+ Tailwind CDN を許容、Chart.js で PV 推移を可視化、フィルタ可能なテーブルを含めてください。

/analytics seo-check <slug>

統合ポイント 3: Claude Code hook で自動 HTML 化

Claude Code の hook 機能を使うと、

/review

設定例（

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs scripts/maybe-html-render.sh"
          }
        ]
      }
    ]
  }
}

PostToolUse

jq

tool_input.file_path

maybe-html-render.sh

tmp/reports/**/*.md

--output-format text

tmp/reports/**/*.html

sandbox

Zenn 記事本文に組み込むときの制約

ここまで述べた HTML 成果物を Zenn の記事本文に直接埋め込むことはできません。Zenn 公式 Markdown ガイドと zenn-editor リポジトリ の挙動から推察すると、Markdown パイプラインは

markdown-it → prism.js → sanitize-html

<br>

<details>

<table>

<iframe>

Zenn が許す擬似リッチ機能の一覧

• :::message

  /

  :::message alert

  メッセージボックス

• :::details タイトル

  アコーディオン

• @[card](url)

  リンクカード（URL 単独行で展開）
• Mermaid 図（公式サポート）
• KaTeX 数式
• Markdown 画像記法

  ![](images/<slug>/foo.svg)

  （SVG 画像も表示可）

詳細は Zenn Markdown ガイド を参照してください。

そのため Zenn 記事内では、HTML 成果物を次の 4 通りで「見せる」ことになります。

• コードブロック:

  ```html

  で実コード片を提示する
• スクリーンショット: 外部 URL で公開した HTML を画像化して掲載する
• Mermaid 図: ワークフローや構造の概要図を Mermaid で代替する
• 外部リンクカード: Netlify / Cloudflare R2 にデプロイした成果物を

  @[card]

  で誘導する

この制約は一見ネガティブですが、「Zenn 記事は永続層、HTML は即時共有層」という耐久性層別化フレームに合致しています。Zenn が許す Markdown 表現の範囲で記事 = 原本を維持し、AI 生成 HTML は動的成果物として別ホストに置く——これが現実的な落としどころです。

まとめ: AI HTML 出力をいつ使い、いつ Markdown に戻すか

本記事では、AI に HTML を直接生成させることの「不当な有効性」を、Thariq Shihipar・Karpathy・Simon Willison らの一次資料・二次資料・コミュニティ事例を突き合わせて整理しました。

• 狭いキャンバス問題: Markdown はテキスト密度に対して表現力が足りない
• 役割分担: 入力・原本は Markdown、出力・共有は HTML
• ネイティブ生成が核心: 変換ではなく、最初から HTML として思考させる
• 4 つのユースケース: 仕様書 / シミュレータ / SVG 図解 / ミニダッシュボード
• デメリット: 編集摩擦・トークンコスト・diff・セキュリティを意識する
• Zenn ワークフロー統合: 既存スラッシュコマンドの最終出力レイヤだけ HTML 化する

冒頭の問いに戻ります。AI が吐き出した 200 行の Markdown レポートは、誰にも読まれずに

tmp/

Zenn 記事という「永続層」は Markdown のままで構いません。揺らがない原本は Markdown で書き、揺れて構わないアウトプットは AI に HTML を書かせて Netlify や Cloudflare R2 に置く——この役割分担に切り替えてから、筆者の運用では「tmp/ に積まれて読まれない問題」がかなり緩和できました。少なくとも試す価値はあるはずです。

最後までお読みいただきありがとうございます。本記事が、あなたの編集チームの「読まれないレポート問題」を少しでも軽くする一助になれば幸いです。

主要参考資料

• Using Claude Code: The Unreasonable Effectiveness of HTML — Thariq Shihipar
• Simon Willison: The unreasonable effectiveness of HTML
• Anthropic: Introducing Artifacts
• OpenAI: Introducing canvas
• Google Workspace Updates: Canvas for the Gemini app
• Zenn Markdown ガイド
• Anthropic Token counting API
• 反論: The Unreasonable Ineffectiveness of HTML — Kurtis Redux
• Hacker News 議論

• HTML → Markdown 変換でトークン数が約 68％（クリーンなコンテンツ）〜約 87.5％（複雑な実 ウェブ ページ）削減されるという報告。換算式は「削減率 = 1 − 1/倍率」で、削減率 68％ は約 3.1 倍、削減率 87.5％ は約 8 倍に相当します。出典:

  Web2MD: Markdown vs HTML for LLM、beam.ai: HTML vs Markdown↩︎↩︎

• 反論記事

  The Unreasonable Ineffectiveness of HTML — Kurtis Redux↩︎
• Hacker News 議論 item 48071940で複数の上位コメントが指摘↩︎

• 表セルからの値抽出精度。タスク条件は二次引用元の記述に依拠。出典:

  Markdown vs HTML for LLM Agents: The 2026 Format Showdown — Tarik Davis（一次論文は未確認のため二次引用）↩︎