Claude Codeで資料を作るならHTMLが最適な理由
Claude Codeに資料を作らせるなら、MarkdownよりHTMLが圧倒的に良い
Claude Codeの開発チームメンバーがXに投稿した「Using Claude Code: The Unreasonable Effectiveness of HTML」という記事がここ最近かなりバズっています。要点をひと言で言えば、Claude Codeで資料・ドキュメントを生成するときはMarkdownではなく最初からHTMLで出力させた方が圧倒的に良い、というものです。本記事ではその主張を整理しつつ、実際のスライド資料生成ではどう運用しているかまで踏み込んで解説します。
そもそもなぜMarkdownでは不足なのか
Markdownは CLAUDE.md や SKILL.md など、Claude Code周辺の設定ファイルでも標準的に使われているフォーマットで、エージェントと人間が情報をやり取りする際のデファクトになっています。一方で、「100行を超えるMarkdownは読むのが辛い」という素朴な現実があり、視覚的な構造化が必要なドキュメントには明確に弱い面があります。例えばプロジェクトのアーキテクチャ説明やCSのQA集のように情報量が多くグルーピングが鍵になるドキュメントは、テキストの羅列のままでは脳に入ってきません。
HTMLが優位な理由
1. 情報密度がそもそも違う
HTMLは見出しや書式に加えて、表・コードスニペット・画像・CSSによるデザイン・JavaScriptによるアニメーションや絶対位置キャンバスまで、1ファイル内で表現できる情報の種類がMarkdownと桁違いです。例えばプロジェクトのカラーパレットを「テキスト=この色、アクセント=この色、背景=この色」と説明したい場面では、HTMLなら実物の色でそのまま表示できますが、Markdownでは色コードの文字列を眺めるしかありません。
2. 視認性・読みやすさ
同じ内容でも、適切に組まれたHTMLページはMarkdownのテキスト羅列より「ひと目で構造を掴める」状態を作れます。サイドカラム・カード・タイポグラフィといった要素を使えるかどうかで、長尺ドキュメントの理解コストは大きく変わります。
3. 共有のしやすさ
Markdownはほとんどのブラウザでそのまま開けず、相手の環境で適切にレンダリングしてもらう必要があります。HTMLならS3などにそのまま放り込んでURLを共有するだけで参照可能になるので、社内外への共有コストが大きく下がります。
4. 双方向のやり取りができる
スライダー・トグル・ラジオボタンなどのUIを差し込んで、ドキュメント自体をインタラクティブに操作できる、というのもHTMLならではの強みです。アルゴリズムの挙動確認やデザイン微調整など、「触りながら理解する」体験を1ファイルに収められます。
5. Claude Codeとの相性が良い
HTMLは「Claude AI」や「Claude」のWeb版ではなくClaude Codeで生成すべき、というのもポイントです。理由はシンプルで、Claude Codeはローカルファイルシステム・MCP・ブラウザ・Git履歴など取り込めるコンテキストの幅が圧倒的に広いからです。プロジェクト内の生成物をまとめて読み込み、構造を分類した上でHTMLレポートとして出力する、といった処理が現実的に回ります。
どんなドキュメントでHTMLが効くか
- 仕様書・調査ドキュメント: 既存仕様の把握、調査結果のサマリーを読み手に届けたいとき。
- レポート・学習資料: 膨大なテキストをそのまま渡しても読まれない。HTMLにして構造化することで読了率を上げられる。
- デザイン・試作: カラー・タイポグラフィ・コンポーネントの「実物」を見せられるので、テキスト記述より絶対に伝わる。
- カスタム編集インターフェース: チェックボックス・ラジオボタン等を組み込んで、AI生成物を人間がその場で編集できるようにする。
逆にコードレビューを毎回HTML化するのは過剰で、コードを直接読んだほうが速い場面が多い、というのが個人的な感覚です。すべてをHTMLにする必要はなく、「視覚的構造化が効くドキュメントか？」で切り分けるのが現実的です。
気になるトレードオフ
トークン使用量は確実に増える
HTMLはタグ・CSS・場合によってはJSも必要になるため、Markdownよりトークンを消費します。ただし、Claude系モデルが100万トークンのコンテキストウィンドウに対応している今、デザイン重視の極端な生成をしない限りはほぼ誤差の範囲、というのが記事の主張であり、実運用でもおおむね同じ感覚です。
Git管理での差分は重くなりがち
これは正直一番現実的なネックです。HTMLはタグ構造やCSSのちょっとした変更まで全部差分に出るので、レビューがしんどくなります。個人の作業や試作・配布物としてのHTMLなら問題ありませんが、チームでGit管理する成果物としては運用ルールが必要です。
デザイン品質をどう担保するか
生成物がダサくならないように、フロントエンドデザイン系のプラグインや社内デザインシステムをClaude Codeに読み込ませる構成が推奨されています。ここを抑えるだけで、生成HTMLの仕上がりが一段安定します。
実例：スライド資料をすべてHTMLで作らせている運用
自分の場合も、半年以上前からスライド資料はHTMLで作らせる運用に切り替えています。きっかけはMarpを使ったMarkdown運用ではデザイン要求に届かなかったことで、PowerPoint形式ではなく「1つのWebページとしてスライドを構成する」発想に変えました。実際のエージェント設定では次のような流れにしています。
- 要件確認: 資料タイプ・対象者・参考にする既存資料の有無を先に聞く。
- コンテキスト取り込み:
docs/配下に集約しているドキュメントをClaude Codeに読み込ませて素材を吸い上げる。 - 構成の提案: 章立てを先にClaude Codeから提示してもらい、OKを出してから生成へ。
- HTMLスライド作成: 自作のpresentationスキルを使い、テンプレを複製→カード／レイアウトヘルパーで構築。スライド固有の調整は直接 style で書く。
- 仕上げ: Apple風デザインのスキル、オーバーフロー検査スクリプト、PDF出力スキルなどを組み合わせて整える。
結果として、「PowerPointっぽい」ではなく「Webページとしてのスライド」を高い品質で量産できるようになりました。営業資料・社内資料どちらにも使えます。
まとめ
Claude Codeでドキュメントを生成するなら、原則HTMLを第一選択にして、Markdownは「設定ファイル」「軽い議事録」など本当にテキスト羅列で十分な場面に限定するのが今のベストプラクティスです。トークン量とGit差分という現実的なコストはありますが、視認性・共有性・コンテキスト活用の上振れが圧倒的に大きいので、まだMarkdown縛りで運用している人は一度HTMLで同じ資料を作らせてみるところから試してみる価値があります。