markdownはエージェントが私たちと対話するための支配的なファイル形式になった。シンプルで、ポータブルで、ある程度のリッチテキストもこなせ、人間が編集するのも簡単だ。Claudeは markdown ファイルの中で ASCII を使って図解する能力すら驚くほど高めてきた。
しかし、エージェントがますます強力になるにつれて、markdownはむしろ制約のあるフォーマットに感じるようになってきた。100行を超える markdown ファイルを読むのは難しい。私はもっと豊かなビジュアライゼーション、色、図解を欲しがっているし、それを簡単に共有できるようにしたい。
それに私は最近、これらのファイルを自分で編集することはあまりなくなってきた。仕様書・参照ファイル・ブレインストーミングのアウトプットとして使うことが増えた。編集するときも、Claudeにプロンプトで指示することがほとんどで、これは「人間が直接編集しやすい」という markdown の最大の利点のひとつを打ち消してしまう。
だから私は、markdown ではなく HTML を出力フォーマットとして好むようになった。Claude Code チームの他のメンバーも同じ方向に動いている。理由をここに書いておく。
先に実例を見たい人は thariqs.github.io/html-effectiveness へどうぞ。読み終わったらここに戻ってきてほしい。
なぜHTMLなのか
情報密度
HTMLは markdown と比べてはるかに豊富な情報を伝達できる。もちろん見出しや書式のような単純なドキュメント構造もこなせるが、それ以外にもありとあらゆる情報を表現できる:
- 表形式データを
<table>で - デザイン情報を CSS で
- イラストを SVG で
- コードスニペットを
<script>タグで - インタラクションを HTML要素 + JavaScript + CSS で
- ワークフローを SVG + HTMLで
- 空間データを絶対座標や
<canvas>で - 画像を
<img>タグで
あえて言い切るなら、Claudeが読める情報のなかで、HTMLで十分効率的に表現できないものはほぼ存在しない。 これによりHTMLは、モデルが深い情報をあなたに伝え、あなたがそれをレビューするための、極めて効率的なメディアになる。
逆に、これができないと、モデルは markdown 内で非効率なことをやり始める。ASCII図解だったり、私のお気に入りは「Claude Codeが unicode文字で色を推定して表現しようとしている」状況だ。
視覚的な明快さと読みやすさ
Claudeがより複雑な仕事をこなせるようになるにつれ、書く仕様書やプランも大きくなっていく。実際のところ、私は 100行を超える markdownファイルはほとんど読まない。組織の他のメンバーに読んでもらうのはなおさら無理だ。
しかしHTMLドキュメントははるかに読みやすい。Claudeが構造を視覚的に整理し、タブ・イラスト・リンクなどでナビゲートしやすくしてくれる。モバイル対応にすれば、デバイスごとに違う見せ方ができる。
共有しやすさ
markdownファイルは共有しにくい。ほとんどのブラウザはネイティブにレンダリングしてくれないので、メールや Slack に添付ファイルとして送るしかない。
HTMLなら、ファイルをどこか（たとえばS3）にアップロードするだけで、リンク1本で共有できる。同僚はどこからでも開いて参照できる。仕様書・レポート・PRの解説を実際に読んでもらえる可能性が、HTMLにするだけで段違いに上がる。
双方向インタラクション
HTMLはドキュメントとのインタラクションを可能にする。たとえばデザイン調整のためにスライダーやノブを追加するよう頼んだり、アルゴリズムのオプションをいじって結果を見たり。さらに、その変更を「プロンプト形式でコピー」できるボタンを追加して、Claude Codeに貼り戻すこともできる。
双方向インタラクションの実例は私のPlaygrounds投稿を参照: x.com/trq212/status/...
データ取り込み
なぜ Claude.ai や Claude Design ではなく、Claude Codeを使って HTML を作るのか？ 最大の理由のひとつは Claude Codeが取り込めるコンテキストの量だ。
たとえばこの記事を書く際、私はClaude Codeに「自分のcodeフォルダにある HTML ファイルを全部読み、グルーピング・カテゴライズして、それぞれの種類を示す図を含めた HTML を作って」と頼んだ。この記事に登場する図はすべて、その出力結果だ。
ファイルシステム以外にも、Claude Codeは MCP（Slack / Linear など）・ブラウザ（Claude in Chrome）・git履歴などからコンテキストを引き出せる。
楽しい
ClaudeでHTMLドキュメントを作るのは、単純に楽しい。創作に対して自分がより関与し、投資している感覚がある。これだけでも理由としては十分だ。
どう始めるか
正直、私はこの記事を読んだ人が /html スキルみたいなものを作って公開し始めるのを少し恐れている。それにも価値はあるかもしれないが、強調しておきたいのは、Claudeにこれをさせるためにそれほど多くは必要ないということだ。「HTMLファイルを作って」「HTMLアーティファクトを作って」と言うだけでいい。
コツは、そのアーティファクトに何をさせたいか、自分がそれをどう使うかを分かっておくこと。時間が経てばスキル化してもいいが、まずは素のプロンプトから始めて、ケースごとに使い方を体に入れることをお勧めする。
ユースケース
具体例を示すために、いくつかの用途で実際に HTML ファイルを作ってきた。全部は thariqs.github.io/html-effectiveness にあるが、ここで概観する。
① 仕様書・計画・探索
HTMLはClaudeが問題に深く入り込むためのリッチなキャンバスだ。問題に着手するとき、私は単純な markdown プランではなく、HTMLファイルの「網」を作るつもりで始める。
たとえばまずClaude Codeに「ブレインストーミングして異なる選択肢を探索して」と頼む。次にひとつに絞って深掘りし、モックアップやコードスニペットを足してもらう。最後に、納得したら実装プランをまとめてもらう。プランに満足したら、新しいセッションを立ち上げてこれらのファイルを全部渡して実装させる。
検証時にも、検証エージェントにこれらのファイルを読ませれば、はるかに広いコンテキストを持って評価してくれる。
使い道:
- コードの実装方法を複数探索する
- 複数のビジュアルデザインを探索する
② コードレビューと理解
コードはmarkdownファイル内では読みにくい。だがHTMLなら、diff・注釈・フローチャート・モジュールなどをレンダリングできる。エージェントが書いたコードを理解する、コードレビューを得る、レビュアーに自分のPRを説明する、といった用途に使える。GitHub標準のdiffビューより機能することも多いので、私は今ではすべてのPRにHTMLのコード解説を添付している。
使い道: PRの作成 / レビュー / コード内のトピック理解
③ デザインとプロトタイプ
Claude DesignがHTMLベースなのは、HTMLがデザイン表現において極めて表現豊かだからだ。最終形がHTMLでない場合も同じ。ClaudeはHTMLでスケッチして、その後にReactやSwiftなど好みの言語で書き直せる。
インタラクション（アニメーションやアクション等）のプロトタイピングにも使える。Claudeに スライダーやノブを作らせて、欲しい挙動をピンポイントで詰める、というやり方も試してみてほしい。
使い道:
- デザインシステムのアーティファクトを作る
- コンポーネントを調整する
- コンポーネントライブラリを可視化する
- 気持ちのいいアニメーションのプロトタイプ
④ レポート・リサーチ・学習
Claude Codeは複数データソースを横断して情報を統合し、読みやすいレポートに変換するのが非常に上手い。Slack・コードベース・git履歴・インターネットを検索させて、自分用・経営陣用・チーム用に極めて読みやすいレポートを生成できる。
長いHTML文書、インタラクティブな解説書、スライドショー／プレゼンといった形にもできる。可視化用に SVGで図解を作らせるのもおすすめ。
たとえば prompt caching についての記事を書く際、私はClaudeに git履歴 を読ませた上で、私たちのprompt cachingに対する変更すべてをまとめた詳細なリサーチHTMLを準備してもらった。
使い道:
- 機能の動作要約
- コンセプトの説明
- 週次の上司への進捗レポート
- 経営陣へのインシデントレポート
- SVGによるイラスト・フローチャート・技術図解
⑤ カスタム編集インターフェース
やりたいことを純粋なテキストで説明するのが難しいときがある。そういう時、私はClaudeに そのデータ専用の使い捨てエディタを作ってもらう。製品でもなく、再利用可能なツールでもなく、いま扱っているこの1つのデータのために作られた、たった1つのHTMLファイル。
コツは 必ずエクスポートで締めること: 「JSONとしてコピー」「プロンプトとしてコピー」のボタンを置き、UIでやったことをClaude Codeに貼り戻せる形に変換する。
使い道:
- 並び替え・トリアージ・バケット分け（チケット、テストケース、フィードバック等）
- 構造化設定の編集（フィーチャーフラグ、環境変数、制約付きJSON/YAML）
- プロンプト・テンプレート・コピーをライブプレビュー付きでチューニング
- データセットのキュレーション（行をapprove/reject、サンプルにタグ付け、選択分をエクスポート）
- 文書・トランスクリプト・diffへの注釈と、注釈のエクスポート
- テキスト表現が苦手な値の選択: 色、イージングカーブ、トリミング領域、cronスケジュール、正規表現
よくある質問
多くの人に「markdownからHTMLに切り替えた」と話してきて、繰り返し聞かれる質問がいくつかある。
トークン効率が悪いのでは？
確かにmarkdownの方がトークン数は少なくなりがち。だが、HTMLの表現力アップと「自分が実際に読む確率の高さ」を加味すると、トータルではより良い結果が得られている。Opus 4.7 の100万トークンコンテキストウィンドウなら、HTMLが消費する分は気にならないレベル。
markdownはいつ使う？
正直、ほぼ全てを markdown から HTML に切り替えてしまった。私はHTMLマキシマリスト寄りなので、人によってはやり過ぎかもしれない。
HTMLファイルはどう見る？
私はローカルでブラウザで開くか（Claudeに開いてもらえる）、共有用リンクが必要ならS3にアップロードする。
markdownより生成に時間がかかるのでは？
かかる。HTMLはmarkdownの2〜4倍かかるが、私はその価値があると感じている。
バージョン管理は？
これがHTMLの最大の欠点のひとつ。HTMLのdiffはノイジーで、markdownと比べてレビューしにくい。
Claudeに自分の好み・自社のテイストに合わせてもらうには？
frontend designプラグインがClaudeが良いHTMLを作るのに役立つ。自社のスタイルに合わせたいなら、Claudeを自社コードベースに向けて、デザインシステムHTMLを1ファイル作っておく。それを他のHTMLファイルの参照として渡せば、テイストが揃う。
ループの中にとどまる
ここまで全部を要約すると、私がHTMLを使う本当の理由は Claudeとのループの中にいる感覚が強くなるからだ。
プランを深く読まなくなったことで、Claudeに選択を任せきりにせざるを得なくなるのではないか——そう恐れていた時期があった。だが今は、HTMLを使うことで むしろ以前よりも深くループに入っていると言えるようになった。
あなたにもそうあってほしい。
原文: Using Claude Code: The Unreasonable Effectiveness of HTML
by Thariq Shihipara — Claude Code Team, Anthropic