「Markdownで十分でしょ？」——そう思っていた時期が、自分にもあった。
Claude Codeチームのエンジニア・Thariq氏が投稿した「The Unreasonable Effectiveness of HTML（HTMLの異常な効果）」が155万表示を記録し、開発者コミュニティに衝撃を与えている。要旨はシンプルだ。Claude Codeの出力形式をMarkdownからHTMLに変えるだけで、生産性が劇的に上がる。
これはコードを書く人だけの話ではない。レポート、仕様書、プレゼン、ダッシュボード——Claude Codeが生成するあらゆるドキュメントに適用できるテクニックだ。
Using Claude Code: The Unreasonable Effectiveness of HTML
— thariq (@trq212) May 9, 2026
なぜHTMLなのか？Markdownの5つの限界
①情報密度の壁
Markdownで表現できるのは、見出し・太字・リスト・テーブル・コードブロックくらいだ。100行を超えるMarkdownファイルを最後まで読み切る人はほとんどいない。
HTMLなら、テーブル・CSS・SVG図解・JavaScriptによるインタラクション・絶対配置による空間表現・画像——あらゆる情報を1つのファイルに詰め込める。Thariq氏の言葉を借りれば「Claudeが読める情報で、HTMLで表現できないものはほぼない」。
②視覚的な読みやすさの壁
Markdownファイルはテキストエディタで開いても見た目はプレーンテキストだ。HTMLならClaude自身がタブ・ナビゲーション・リンク・イラストを使って構造を最適化できる。レスポンシブ対応にすれば、スマホでも読みやすくなる。
③共有の壁
Markdownファイルを同僚に共有するには、メールに添付するかSlackに貼り付ける必要がある。ブラウザでは綺麗にレンダリングされない。
HTMLならS3やGitHub Pagesにアップロードしてリンクを共有するだけでいい。相手がどのデバイスで開いても読める。仕様書やレポートを実際に読んでもらえる確率が格段に上がる。
④双方向性の壁
Markdownは読むだけのフォーマットだ。HTMLなら、スライダー・ボタン・入力フォームを埋め込んで、デザインのパラメータを調整したり、アルゴリズムのオプションを切り替えたりできる。変更結果を「Copy as prompt」ボタンでコピーし、Claude Codeに貼り戻す——という双方向のワークフローが成立する。
⑤Markdownの利点が薄れている
Markdownの最大の利点は「人間が直接編集しやすい」ことだった。しかし、Claude Codeの時代では、ファイルを自分で編集する場面が減っている。仕様書も、レポートも、ブレインストーミングの結果も、Claudeに生成・編集させることが多い。編集しやすさが最大の武器だったMarkdownから、表現力が最大の武器のHTMLに乗り換える合理性が出てきた。
6つのユースケースと実践プロンプト
①仕様書・計画・探索
Markdown の箇条書きではなく、HTMLで「探索マップ」を作る。複数の選択肢をグリッド表示し、それぞれのトレードオフをラベル付きで比較する。
プロンプト例：
オンボーディング画面の方向性に迷っている。レイアウト・トーン・情報密度を変えた6つの全く異なるアプローチを生成して、1つのHTMLファイルにグリッド表示で並べて比較できるようにして。それぞれのトレードオフをラベルで示して。
②コードレビュー・PR解説
GitHubのdiff表示よりも読みやすいPR解説をHTMLで作る。差分をインラインで表示し、重要度別に色分けし、注釈をマージン部分に配置する。
プロンプト例：
このPRをレビューするためのHTMLファイルを作って。ストリーミング／バックプレッシャーのロジックに詳しくないので、そこに焦点を当てて。実際のdiffをインライン表示して、重要度別に色分けした注釈をマージンに配置して。
Thariq氏は「今では自分が作るすべてのPRにHTML解説ファイルを添付している」と述べている。
③デザイン・プロトタイプ
アニメーション、インタラクション、カラーパレットをHTMLで試作し、スライダーで微調整する。良い設定が見つかったら「パラメータをコピー」ボタンで数値を取り出す。
プロンプト例：
新しいチェックアウトボタンのプロトタイプを作りたい。クリックするとアニメーションして素早く紫になる。HTMLファイルにスライダーとオプションを用意して、アニメーションの各種設定を試せるようにして。うまくいったパラメータをコピーするボタンも付けて。
④レポート・リサーチ・学習
Slack、コードベース、Git履歴、インターネットなど複数のデータソースから情報を集約し、読みやすいHTMLレポートとして出力する。SVG図解付き。
プロンプト例：
レートリミッターの仕組みを理解したい。関連するコードを読んで、1つのHTML解説ページを作って。トークンバケットのフロー図、重要なコードスニペット3〜4個の注釈、そして「落とし穴」セクションを入れて。一度読むだけで理解できるように最適化して。
⑤カスタム編集インターフェース
テキストだけでは表現しにくい作業のために、使い捨ての専用エディタをHTMLで作る。必ず「JSONとしてコピー」「プロンプトとしてコピー」ボタンを付けて、結果をClaude Codeに戻せるようにする。
プロンプト例：
30件のLinearチケットの優先度を整理したい。各チケットをドラッグ可能なカードにして、Now / Next / Later / Cut の4列に配置するHTMLファイルを作って。AIの推測で事前ソートして。最終結果をMarkdownでコピーするボタンも付けて。
⑥データの可視化・ダッシュボード
プロジェクトの進捗、パフォーマンスメトリクス、テスト結果などを、インタラクティブなダッシュボードとして出力する。
プロンプト例：
今月のプロジェクト進捗をHTMLダッシュボードにまとめて。タスク完了率、残りのブロッカー、チームメンバーの稼働状況をグラフとテーブルで表示。フィルタリングとソート機能も付けて。
よくある質問（FAQ）
「トークン効率が悪くなるのでは？」
確かにHTMLはMarkdownよりトークンを多く消費する。しかし、表現力の向上と「実際に読まれる確率」の向上を考えれば、全体としてのアウトプット品質は上がる。Opus 4.7の100万トークンのコンテキストウィンドウがあれば、増加分は気にならないレベルだ。
「生成に時間がかかるのでは？」
HTMLはMarkdownの2〜4倍の生成時間がかかる。だが結果の質を考えれば十分ペイする、というのがThariq氏の見解だ。
「バージョン管理が面倒では？」
これはHTMLの最大の弱点。HTMLのdiffはノイズが多く、レビューしにくい。Markdownのバージョン管理の容易さは依然として利点だ。
「デザインがダサくなるのでは？」
Claude Codeのフロントエンドデザインプラグインを使えば、それなりに見栄えのよいHTMLが出る。自社のスタイルに合わせたい場合は、コードベースからデザインシステムHTMLを1ファイル生成し、以降の出力でそれを参照させるのが推奨されている。
Markdownを捨てるべきか？現実的な使い分け
HTMLにすべきもの
- 100行を超える仕様書・計画書
- 他人に読んでもらう必要があるレポート
- PRの解説・コードレビュー資料
- デザインプロトタイプ・モックアップ
- インタラクティブな設定・調整ツール
- 経営層への報告資料
Markdownのままでいいもの
- 短いメモ・TODO
- READMEファイル
- Git管理が重要なドキュメント
- 頻繁に手動編集するファイル
まとめ：次にやるべき3つのこと
Claude Codeの出力をHTMLに変えるだけで、「読まれない仕様書」が「読まれるドキュメント」に変わる。
① 今日やること：Claude Codeで次に計画書や仕様書を作るとき、「HTMLファイルで作って」と一言加える。特別なスキルファイルや設定は不要——この一言だけで出力形式が変わる。
② 今週中にやること：次のPRを出すとき、「このPRをレビューするためのHTML解説ファイルを作って」と指示し、PRにHTMLファイルを添付する。レビュアーの理解速度が格段に上がるはずだ。
③ ワークフローに組み込む：「Claudeに何かを生成させる → HTMLで出力 → ブラウザで確認 → 修正をプロンプトで依頼」のサイクルを定着させる。MarkdownよりもHTMLの方が、AIとの協業に適したフォーマットだ。
