HTMLドキュメントのススメ——AIに書かせた設計書、Markdownのまま読んでいませんか？
記事日：2026-07-14時点の内容です。参照している公式ブログ・ツールの仕様は将来変更される可能性があります。
この記事で学べること
この記事は、AIに書かせたドキュメントを「人が読む」場面で、Markdownのまま読むのをやめてHTML化する——という私の運用と、その根拠をまとめたものです。次のことが分かります。
- AIが出力するMarkdownを、AI用と人間用で使い分ける判断基準
- Anthropic公式ブログが「HTMLで出力させること」を推奨している内容とその理由
- 私が普段やっているHTML化の指示の仕方と、レイアウトを安定させるスキル化の工夫
- HTMLのベースを作る手段の選択肢（自作スキル / frontend-design / Claude Design / OSS）
対象読者は、Claude CodeなどのAIコーディングツールでドキュメント（設計書・調査レポート・レビュー結果など）を日常的に生成している人です。「生成はできているが、正直あまり読めていない」という自覚がある人にこそ読んでほしい内容です。
AIにドキュメントを書かせると、だいたいMarkdownが出てくる
Claude Codeに「設計をまとめて」「調査結果をレポートにして」と頼むと、特に指定しなければ .md ファイルが生成されます。これはAI側の都合として合理的です。
- Markdownはプレーンテキストなので、AIが読み書きしやすい
- トークン効率が良い（同じ内容ならHTMLより消費が少ない）
- Gitでdiff管理しやすく、後続のセッションでAIが再読するのも簡単
だから、AIに読ませるためのドキュメントはMarkdownのままで何も問題ありません。CLAUDE.md のような指示ファイル、実装計画、作業メモ、次のセッションへの引き継ぎ——これらの読者はAIなので、Markdownが最適です。
問題は、その出力を人間が読む場面です。
それでも「人が読む」場面はまだ多い——特に設計
AIに作業を任せる範囲が広がっても、人が内容を理解しなければならない場面はまだ多く残っています。私の実感では、むしろAIの出力量が増えたぶん「読むべきもの」は増えました。
- 設計ドキュメント: AIが提案した設計を承認するのは人間。理解せずに承認すると、後で自分が困る
- 調査レポート: 技術選定やライブラリ比較の結果は、最終判断のために人が読み込む必要がある
- レビュー結果・障害分析: 指摘や原因分析を流し読みすると、同じ問題を繰り返す
そして正直に言うと、100行を超えるMarkdownは目が滑ります。見出しと箇条書きが延々と続くプレーンテキストを、エディタやターミナルでスクロールしながら読む——集中力が続かず、「読んだつもり」で先に進んでしまう。私は何度もこれをやりました。
AIの出力を読まずに受け入れることが品質・保守・セキュリティのリスクになる、というのは多くの人が感じ始めている問題だと思います。だからこそ「人が読むための形式」を真面目に考える価値があります。
Anthropic公式ブログも「HTMLで出させる」ことを勧めている
この「人が読むならHTML」という運用、実はAnthropicの公式ブログでも推奨されています。Claude Codeチームのエンジニア Thariq Shihipar 氏による2026年5月の記事です。
- Using Claude Code: The unreasonable effectiveness of HTML（claude.com公式ブログ・英語）
記事で挙げられているHTMLの利点は、要約すると次の4つです。
| 利点 | 内容 |
|---|---|
| 情報密度 | 表・SVG図・コードスニペット・インタラクティブ要素まで、1ファイルで表現できる |
| 読みやすさ | 100行超のMarkdownは読みにくいが、HTMLはタブ・リンク・視覚的な構造で整理できる |
| 共有しやすさ | ブラウザで開くだけ。リンクを渡せば済むので、Markdownより読まれる可能性が高い |
| 双方向性 | スライダーで調整する、カードをドラッグして並べ替えるなど、ドキュメント上で直接操作できる |
ユースケースとしても、仕様・計画の可視化、PRの説明、デザイン比較、データ分析レポートなど幅広く挙げられていて、著者自身は「ほぼすべての出力をHTML化した」とまで書いています。トークン消費はMarkdownより増えるものの、「読まれる可能性が上がることの価値のほうが大きい」という整理です。
私はこの記事が出る前からHTML化の運用をしていましたが、公式がここまで明確に後押ししてくれたことで、人にも勧めやすくなりました。
なぜHTMLなのか——私の理由
公式の整理と重なる部分もありますが、私自身がHTML化を続けている理由は次の3点です。
1. レイアウトとデザインの自由度
Markdownの表現力は見出し・箇条書き・表・コードブロックでほぼ打ち止めです。HTMLなら、重要な注意点をコールアウト（色付きの枠）で目立たせる、比較をカードで横に並べる、手順に番号付きのステップUIを使う、といった「読ませるための工夫」ができます。同じ内容でも、読み手の負荷がまったく違います。
2. 図解をインラインSVGで埋め込める
設計ドキュメントには構成図・シーケンス図・データフロー図が欠かせません。Markdownで図といえばMermaidが定番ですが、Mermaidはレンダラがある環境でしか描画されません。GitHubでは表示されても、エディタのプレビューや静的サイトでは生のコードブロックのまま——というのはよくある落とし穴です（実はこのブログもMermaid非対応なので、記事内の図はすべてインラインSVGで描いています）。HTMLならインラインSVGを直接埋め込めるので、どこで開いても確実に図が表示されます。
3. 単一ファイルで完結し、ブラウザで開くだけ
CSSをインラインにした自己完結HTMLなら、ファイルを1つ渡すだけで相手はブラウザで開けます。ツールのインストールも、Markdownレンダラの環境差も関係ありません。印刷やPDF化もブラウザの機能でそのままできます。
読み手でフォーマットを出し分ける、という整理を図にすると次のようになります。
実際の運用：自分で読むものはHTML化させている
私は普段から、自分がじっくり読む必要のある成果物はHTMLで出させています。設計の検討資料、ライブラリ選定の比較レポート、コードレビューの結果まとめなどです。Markdownやプレーンテキストで同じ内容を受け取ると、どうしても目が滑って頭に入らない——これが一番の動機です。
指示は難しくありません。依頼の最後にこう付け足すだけです。
結果は単一の自己完結HTMLファイルにまとめて。
- CSSはインライン、外部CDN・外部スクリプトは読み込まない
- 構成図・フロー図はインラインSVGで描く
- 印刷してもレイアウトが崩れないように
公式ブログでも「1行プロンプトを足すだけでいい」と紹介されていますが、実際その通りで、この一文だけで出力の読みやすさが別物になります。
ハマったポイント：毎回デザインがバラつく
ただし、都度プロンプトで指示するだけだと生成のたびに配色やレイアウトがバラつきます。今日はブルー基調のカード型、明日はグレー基調のシンプル型——内容は良くても、見た目が毎回違うと「どこに何が書いてあるか」のパターン認識が効かず、読む速度が上がりません。
そこで私は、HTMLレイアウトのルールをスキル化しました。配色・フォント・見出しスタイル・コールアウト・SVG図カードを定義したテンプレートHTMLを1枚用意し、「HTML資料を作るときはこのテンプレートをベースにする」というスキル（Claude Codeに読み込ませる手順書）にしています。これで毎回同じ見た目・同じ構造で出てくるので、資料を開いた瞬間に読み方が分かる状態になりました。
セキュリティ上の注意：外部CDNを読み込ませない
もう1つ、運用上こだわっているのが自己完結です。AIにHTMLを作らせると、Tailwind CDNやGoogle Fonts、チャートライブラリなどを外部から読み込むコードを平気で入れてきます。社内資料や顧客関連の資料でこれをやると、開くだけで外部サーバーへリクエストが飛ぶことになり、セキュリティポリシー的に問題になり得ます。プロンプトの「外部CDN・外部スクリプトは読み込まない」は飾りではなく、毎回明示すべき制約です。図もチャートライブラリではなくインラインSVGで描かせれば、この問題は起きません。
ベースの作り方は好みでいい
「HTMLのテンプレートやデザインをどう用意するか」は、正直好みの問題です。選択肢を挙げておきます。
- 自作テンプレート + スキル化 — 私の方法。一度作れば安定して使い回せる。初期コストはかかる
- frontend-design プラグイン — Claude Code公式マーケットプレイスのプラグインで、AIっぽくない洗練されたUIを出してくれる。おすすめプラグイン集の記事で紹介しています
- Claude Design でベースを作る — LPレベルの完成度のHTMLが出てくるので、それをテンプレートとして流用する手もあります。使用感はClaude Designのレビュー記事にまとめました
- Google Stitch や OSS のデザイン定義を使う — DESIGN.md のようなデザインシステム定義をAIに渡す方法。DESIGN.mdでデザインを安定させた記録で詳しく書いています
どれを選んでも「人が読む成果物の見た目を安定させる」というゴールは同じです。すでにこのブログで紹介してきた道具立てがそのまま使えます。
Obsidianとの棲み分け（これは後日改めて）
ナレッジ管理の文脈では最近Obsidianが流行っていて、私も使っています。ただ、私の位置づけではObsidianはAIに知見を蓄積させるためのデータベースであって、人がじっくり読むための媒体ではありません。Markdownのノートが数百枚リンクし合っている状態は、AIが検索・参照するには最高ですが、人間が「今日はこれを読み込んで理解しよう」と向き合う形式ではない、というのが私の実感です。
「AIの記憶はObsidian（Markdown）に、人が読む成果物はHTMLに」という棲み分けで運用していますが、Obsidian側の話は分量があるので、後日別の記事で書くつもりです。
Markdownを捨てるわけではない——使い分けの整理
誤解のないように書いておくと、これは「Markdownをやめよう」という話ではありません。読み手で使い分ける話です。
| 観点 | Markdown | HTML |
|---|---|---|
| 主な読み手 | AI（と、ちらっと見る人間） | 人間 |
| 向いている用途 | CLAUDE.md・実装計画・作業メモ・引き継ぎ | 設計書・調査レポート・レビュー結果・比較資料 |
| 図解 | Mermaid（環境依存で描画されないことがある） | インラインSVG（どこでも表示される） |
| 共有 | ツール・環境に依存 | ブラウザで開くだけ |
| トークン消費 | 少ない | 多い（レイアウト分のコード量が増える） |
| Git管理・diff | しやすい | しにくい（生成物として扱う） |
注意点も公平に書いておくと、HTML出力はMarkdownよりトークンを多く消費します。CSSやSVGのコード量がそのまま上乗せされるためで、なんでもかんでもHTML化すると使用枠を圧迫します。「人がしっかり読むべき成果物だけHTML化する」という絞り込みが、コスト面でも現実的です。
まとめ
- AIが出すドキュメントはMarkdownがデフォルトで、AIに読ませる分にはそれで正解
- ただし設計書・調査レポートなど人が理解すべきドキュメントはまだ多く、そこはHTML化する価値がある
- Anthropic公式ブログ（The unreasonable effectiveness of HTML）も同じ方向を推奨している
- 理由はレイアウトの自由度・インラインSVGでの図解・単一ファイルで共有できる手軽さ
- 都度指示だとデザインがバラつくので、テンプレート化・スキル化で安定させるのがおすすめ。ベースはfrontend-designでもClaude DesignでもOSSでも、好みでいい
- 外部CDNを読み込まない自己完結HTMLにするのはセキュリティ上も重要
特に業務でAIを使っていると、自分が人に説明しなければならない場面が必ず出てきます。設計の意図を聞かれて答えられるか、調査結果の根拠を示せるか——その前提になるのは「自分がちゃんと読んで理解していること」です。読むためのコストを下げるHTML化は、そのための地味ですが確実な投資だと思っています。目が滑るMarkdownを我慢して読んでいる人は、まず次の1回、依頼の最後に「結果は自己完結HTMLで」と足すところから試してみてください。