3 行サマリ
・何を: Claude Code（Anthropic の CLI 型 AI エージェント）に書かせる仕様書・計画書・PR 説明などのドキュメント出力フォーマットを、Markdown から HTML に寄せていく運用ノウハウ。
・誰向け: Claude Code に長尺の計画書や仕様書を吐き出させているが、「結局その .md は誰も読まない」と感じている小規模事業者・士業・営業職・コンサル・個人開発者。
・何が新しいか: Claude Code 創設者発の「Markdown は 100 行を超えると読まれない／HTML へ寄せている」という主張に対して、6 つの理由・生成コスト 2.44 倍／読み込みは 1.33 倍という実測値・5 つのユースケース別プロンプト例・CSS 外部化で 44% トークン削減、という運用に落ちる粒度の知見が一気に出た。
そもそも何の話か
Claude Code は Anthropic 製の CLI 型 AI エージェント。「このリポジトリをどうリファクタすべきか計画して」「このオンボーディング画面の方向性を 6 つ並べて」と頼むと、平気で数百〜数千行のドキュメントを 1 ショットで書き出してくる。
これまでは出力先として PLAN.md のような Markdown ファイルが定番だった。しかし Claude Code チームでは、そのデフォルト出力先を Markdown ではなく HTML 1 ファイルへ寄せる方向に舵を切っている、という運用論が出てきた。本記事はその要点を、非エンジニア読者向けに翻訳したものだ。
なぜ HTML へ寄せるのか — 6 つの利点
① 情報密度（1 ファイルに「色・表・図・操作」を全部入れられる）
HTML 1 ファイルには、テーブル、CSS デザイン、SVG 図解、コード例、JavaScript／CSS による操作、SVG ベースのワークフロー図、canvas を使った空間データ、画像など、Claude が扱えるほぼすべての情報を同居させられる。Markdown では色を表現することすらほぼ不可能。
② 視覚的な明瞭さ（100 行超えても読まれる）
Claude Code が複雑な作業をこなせるようになるほど、出てくる仕様書も計画書も長大化していく。100 行を超える Markdown ファイルは、書き手も含めて誰にも読まれずに終わる傾向がある。HTML ならタブ・図解・リンク・モバイル対応で、長尺でも目的の場所まで素早くたどり着ける。
③ 共有のしやすさ（URL 一本でブラウザ完結）
Markdown は GitHub に上げるか専用ビューワで開くか、相手にエディタを開いてもらう必要がある。HTML は静的ホスティング（S3／Firebase Hosting／Vercel／Netlify など）にアップロードするだけで URL になり、相手がブラウザでクリックした瞬間にリッチに読める。「Slack に URL を貼るだけで全員が読める状態」になるのが大きい。
④ 双方向インタラクション
HTML は読むだけでなく操作させられる。スライダーでアニメーションパラメータを調整したり、複数のアルゴリズムをビジュアルで切り替えたり、調整した内容を Claude Code に貼り戻すボタンを置いたりできる。「テキストでどう伝えればいいか分からない」を、UI が肩代わりしてくれる。
⑤ 取り込めるコンテキストの豊かさ（Claude Code 特有の強み）
なぜ Web 版の Claude や Claude Design ではなく、わざわざ Claude Code で HTML を書かせるのか。最大の理由は、Claude Code がファイルシステム上のコード・MCP（Slack／Linear など）・Web ブラウザ・git の履歴まで参照したうえでドキュメントを生成できる点にある。
設計書を書かせると、ただの机上のプランではなく「実際のコード／チケット／会話を踏まえたプラン」が出てくる。
⑥ 触っていて単純に楽しい
Claude Code に HTML ドキュメントを作らせる体験は、Markdown を作らせる体験よりもずっと「自分が関与している」感が強い。書き手のモチベーションが続くこと自体、HTML を選ぶ十分な理由になる、というのが提唱者の主張。
生成コストを実測した
「HTML は重いのでは？」という直感に対して、同じコンテンツ（Claude Code のコマンド・スキル一覧）を Markdown と HTML の両方で生成させて比較した実測値が出ている。
・生成時間: HTML は Markdown の 2.44 倍
・ファイルサイズ: HTML は Markdown の 3.56 倍
・トークン数: HTML は Markdown の 1.56 倍にとどまる（<div> <span> class= などの繰り返しパターンが LLM 内で効率よく圧縮されるため、サイズ比ほどには増えない）
さらに、生成した両ファイルを Claude に渡して「内容を説明してください」と依頼したときの読み込みコストも測られている。
・読み込み処理時間: HTML は Markdown の 1.33 倍（差は 8.7 秒）
・読み込みトークン: HTML 側でも 23,730 トークン（100 万トークンウィンドウのわずか 2.4%）
ファイルサイズ 3.56 倍に対して読み込み時間が 1.33 倍にしかならないのは、現実には扱いやすい比率と言える。
5 つの具体的なユースケース（プロンプト例つき）
ポイントは「特別なスキルや設定は要らない」こと。「HTML ファイルを作って」「HTML アーティファクトを作って」と一言伝えれば始められる。
① 仕様・計画・探索
Markdown の計画書ではなく、複数の方向性をビジュアルで横並び比較する HTML を出発点にする。
「オンボーディング画面の方向性を決めかねています。レイアウト、トーン、情報密度を変えた 6 つの異なるアプローチを生成し、1 つの HTML ファイルにグリッド表示して比較できるようにしてください」
「詳細な実装計画を HTML ファイルで作成してください。モックアップ、データフロー図、重要なコード例を含め、読みやすくしてください」
② コードレビューと理解
PR の説明を HTML で書かせると、GitHub のデフォルト diff 表示よりも追いやすくなる。
「この PR を説明する HTML アーティファクトを作成してください。ストリーミング／バックプレッシャーのロジックに馴染みがないので、そこを重点的に説明し、実際の Diff をインラインアノテーションで表示してください」
③ デザインとプロトタイプ
React や Swift で本実装に入る前に、HTML でインタラクションだけ先にプロトタイプする。
「新しいチェックアウトボタンをプロトタイプしたいです。クリック時のアニメーションをスライダーで調整できる HTML ファイルを作成し、気に入ったパラメータをコピーできるボタンも追加してください」
④ レポート・リサーチ・学習
Slack、社内コードベース、git の履歴を読み込ませて、インサイトをインタラクティブな 1 枚ものに落とす。
「レートリミッターの仕組みが分かりません。関連するコードを読んで、トークンバケットのフロー図、3〜4 つの重要なコード例の解説、注意点セクションを含む 1 ページの HTML 解説を作成してください」
⑤ カスタム編集インターフェース
「使い終わったら捨てていい」前提のワンショットエディタを作る。
「30 件の Linear チケットを優先順位付けしたいです。各チケットを Now／Next／Later／Cut の列間でドラッグできる HTML ファイルを作り、最終的な並びを Markdown でエクスポートする『コピー』ボタンを追加してください」
CSS 外部化で 44% のトークン削減
「HTML はトークン数が増える」懸念に対して、実用的な対策が出ている。CSS を <link rel="stylesheet" href="/styles.css"> で外部ファイルに切り出すと、LLM が毎回 CSS を出力しなくて済むため、12,115 トークンの HTML 記事が 6,723 トークン（44% 減） まで縮んだという実測がある。
つまり、最初に「自社用デザインシステム HTML」を 1 つ作ってしまえば、以降の HTML 生成はずっと軽くなる。
実用シナリオ：計画書を URL 1 本で共有する
「6 つの理由」「実測コスト」「プロンプト例」と並ぶ現場での落としどころが、 計画書を .md ではなく単一 HTML ファイルで出して、Firebase Hosting 等に置いて URL で渡す という共有ワークフローです。@SuguruKun_ai が提案していた運用論を、ここに統合しておきます。
なぜ Markdown を「捨てる」発想になるのか
最近のエージェント系 AI は、依頼すると 平気で 1,000 行を超える PLAN.md を返してきます。Claude Code に「このリポジトリをどうリファクタすべきか計画して」と頼むと、リポジトリ全体・git 履歴・MCP 連携先まで読み込んだ上で長尺プランを 1 ショットで吐く。
人間の側はその分量を前提に読み方を組まないと、最初の 200 行でスクロールを諦めます。
Markdown は構造化しやすい代わりに、読み手にとっては 延々と続く文章のかたまり になりがち。見出しを増やしても折りたたみは効かないし、図はリンクで飛ばすしかなく、操作要素もない。結果、書き出された 1,000 行プランは「気合いで縦スクロール」する以外に読み方がない、という状況になる。
URL 1 本で渡す効果
HTML 1 ファイルなら、Firebase Hosting / Vercel / Netlify に そのままデプロイして URL にできます。Slack に https://... を貼れば、相手はクリックした瞬間にリッチに読める。
・Markdown の場合: GitHub に上げて URL を渡すか、.md ファイルを添付して相手にエディタで開いてもらう必要がある。社内 Wiki に転記する運用にすると、転記の手間が二度発生する。
・HTML の場合: 静的ホスティングに上げるだけで「会話の流れ + どこをどう判断したか」までスクロール 1 つで追える。レビュー会議の冒頭に URL を貼れば、それだけで全員のコンテキストが揃う。
静的ホスティングまでを Claude Code に伴走させる
「Firebase Hosting なんて触ったことがない」という非エンジニアでも、 Claude Code に 「Firebase Hosting にデプロイする手順を教えて、必要なコマンドも全部生成して」 と頼めば、CLI コマンドの実行までセットで伴走してくれます。エンジニアが横にいない 1 人会社・士業・コンサルでも、 URL 共有まで一気に到達できる。
このシナリオに乗せやすいプロンプト例
このリポジトリのリファクタ計画を、単一 HTML ファイル `plan.html`
として書き出してください。
・目次（左サイドバー）と進捗チェックボックスを入れる
・構成図は SVG で本文に直接埋め込む
・スマホで開いても読める幅にする
・完了したら、Firebase Hosting へのデプロイ手順を別紙で出す
このプロンプトを「PLAN.md を作って」の代わりに使うだけで、計画書の出力先と共有手段が一気にアップグレードされます。
誰にどう効くか
・小規模事業者・1 人会社: 外注エンジニアやデザイナーに「今期どう作り直すか」を渡すとき、Notion を構築するほどでもないが Markdown だと読まれない、という中間ゾーンに刺さる。「この計画を 1 枚 HTML で書き出して、目次と進捗チェックボックスを入れて」と依頼するだけ。
・士業・コンサル・PM: クライアント納品の戦略ドキュメント・要件定義の一次ドラフトを HTML で出させ、URL を共有すれば、PDF を送るより「議事の続き」感が出る。
・個人開発者: 「次に何をやるかリスト」を PLAN.md ではなく plan.html で出させ、ローカルで開きながら作業すれば、長尺プランの中で迷子になりにくい。
・営業・経営企画: 比較資料・競合分析・提案書のドラフトを HTML で出させ、社内 URL で共有することで、Excel や PowerPoint の往復を省ける。
触ってみるには
1. いつもの「PLAN.md を作って」を、「単一 HTML ファイル plan.html として書き出してほしい。目次・折りたたみ・進捗チェックボックスを入れて」 に置き換える。
2. 出てきた plan.html をブラウザで直接開いて確認する（ローカルで完結）。
3. 共有したい場合は、Claude Code 自身に「Firebase Hosting にデプロイする手順を生成して、必要なコマンドも全部書いて」と頼めば伴走してもらえる。
4. 図が必要な箇所は「ここに SVG で構成図を埋めて」と追記すれば、HTML に直接 SVG が埋め込まれる。
5. 同じ HTML を繰り返し作る用途では、最初に「自社デザインシステム HTML（共通 CSS）」を 1 つ作って外部参照させ、以降の生成トークンを 4〜5 割削減する運用を組み込む。
注意点・限界
・Markdown のほうが向いている用途も残る: 1 行直したいときにテキストエディタで書き換えられる手軽さは Markdown が上。バージョン管理（git diff）も Markdown のほうがノイズが少なくレビューしやすい。
・「修正も Claude に頼む」前提なら HTML の編集コストは消える: ただし手元で素早くいじりたい資料は Markdown のほうが速い、という二刀流が現実的。
・公開範囲の管理: Firebase Hosting / Vercel に素のままデプロイすると公開 URL になる。社外秘の計画書を置く場合は Basic 認証・閲覧制限・サブドメイン分離を最初から仕込む。
・「Markdown は AI を駆動する中間言語」という見方もある: AI への指示・CLAUDE.md のような設定ファイルは Markdown のままにし、人間に見せるドキュメントだけ HTML に「コンパイル」する、という役割分担で運用するのが落としどころ。
・読まれない問題はフォーマットだけでは解決しない: HTML 化は読み手の入り口を低くする工夫であって、内容が冗長なら結局スクロールされる。「最上段に 1 画面で全体像が掴めるサマリを置いて」と最初に指示すると体感が変わる。
関連リンク
・Claude Code が HTML 出力に寄せ始めた背景・6 つの理由・実測値・プロンプト例（X 解説記事）
・元投稿（X / @claudecode_lab）
・計画書を Markdown ではなく HTML で出させる運用（X / @SuguruKun_ai）
ARTICLE_ID: 2026-05-10-claude-code-html-format-measured