Claude Code の活用：HTML が持つ驚異的な有効性

Markdown は、エージェントが私たちとコミュニケーションを取るための主要なファイル形式になりました。シンプルで、ポータブルで、ある程度のリッチテキスト機能があり、編集も簡単です。Claude は、Markdown ファイル内で ASCII を使って図を作成することにも驚くほど熟達しています。

しかし、エージェントがますます強力になるにつれて、Markdown は制限の多い形式だと感じるようになりました。100 行を超える Markdown ファイルを読むのは難しいと感じます。もっとリッチなビジュアライゼーション、色、図が欲しいし、それらを簡単に共有できるようにしたいのです。

また、自分でこれらのファイルを編集するのではなく、仕様書やリファレンスファイル、ブレインストーミングの出力などとして使うことが増えています。編集する場合も、通常は Claude にプロンプトで編集を依頼しており、これにより Markdown の最大の利点の一つが失われています。

私は Markdown の代わりに HTML を出力形式として好むようになり、Claude Code チームの他のメンバーもこれをますます使っているのを目にしています。その理由は以下の通りです。

(いくつかの例から始めたい場合は、こちらで多数ご覧いただけます：https://thariqs.github.io/html-effectiveness。必ず戻ってきて、その理由についてもっと読んでください。)

なぜ HTML なのか？

情報密度

HTML は Markdown と比較して、はるかにリッチな情報を伝えることができます。もちろん、見出しや書式設定などの単純な文書構造も扱えますが、以下のようなあらゆる種類の情報も表現できます。

• 表を使ったテーブルデータ
• CSS を使ったデザインデータ
• SVG を使ったイラスト
• スクリプトタグを使ったコードスニペット
• JavaScript + CSS を使った HTML 要素によるインタラクション
• SVG と HTML を使ったワークフロー
• 絶対位置とキャンバスを使った空間データ
• 画像タグを使った画像

私は、Claude が読み取れる情報で、HTML でかなり効率的に表現できないものはほとんどないとさえ言えます。これにより、モデルが詳細な情報をあなたに伝え、あなたがそれをレビューするための非常に効率的な方法となります。

これができない場合、モデルは Markdown で ASCII 図のような非効率的なことをしたり、私のお気に入りである、Claude Code のスクリーンショットのような Unicode 文字で色を推定したりすることがあるとわかりました。

Markdown で色を表示しようとする Claude Code

視覚的な明瞭さと読みやすさ

Claude がより複雑な作業をこなせるようになるにつれて、仕様書や計画もどんどん大きくなっています。実際、私は 100 行を超える Markdown ファイルを実際に読むことはほとんどなく、組織内の他の誰かに読んでもらうこともできていません。

しかし、HTML 文書ははるかに読みやすく、Claude はタブ、イラスト、リンクなどを使って視覚的に理想的なナビゲーション構造を整理できます。モバイル対応にもできるので、デバイスに応じて異なる読み方ができます。

共有のしやすさ

Markdown ファイルは、ほとんどのブラウザがネイティブでうまくレンダリングしないため、共有がかなり難しいです。メールやメッセージに添付ファイルとして追加する必要がよくあります。

HTML なら、ファイルをアップロード（例えば S3 に）すれば、簡単にリンクを共有できます。同僚は好きな場所で開いて、簡単に参照できます。

仕様書、レポート、PR の書き込みを実際に誰かが読む可能性は、HTML であればはるかに高くなります。

双方向のインタラクション

HTML を使えば、ドキュメントと対話できます。例えば、デザインを調整するためのスライダーやノブを追加したり、アルゴリズムのさまざまなオプションを微調整して結果を確認したりできます。また、これらの変更をプロンプトにコピーして Claude Code に貼り付けるように依頼することもできます。

この双方向のインタラクションの例については、私の playgrounds に関する投稿をご覧ください：https://x.com/trq212/status/2017024445244924382

データ取り込み

なぜ ClaudeAI や Claude Design ではなく Claude Code を使って HTML ファイルを作成するのか？最大の理由の一つは、Claude Code が取り込めるコンテキストの多さです。

例えば、この記事を書いているとき、Claude Code に私のコードフォルダを読み込ませ、生成したすべての HTML ファイルを見つけてグループ化・分類し、各タイプを表す図を含む HTML ファイルを作成するよう依頼しました。この記事で見られる図はその直接の結果です。

ファイルシステム以外にも、Claude Code は MCP（Slack、Linear など）、Web ブラウザ（Chrome の Claude）、git 履歴などを使用して追加のコンテキストを見つけることができます。

楽しい

Claude を使って HTML 文書を作成するのは単純に楽しく、制作により関与し、投資している気分にさせてくれます。それだけで十分です。

始め方

この記事を読んだ人々がこれを /html スキルなどにしてしまうのではないかと少し心配しています。それにも価値はあるかもしれませんが、Claude にこれをさせるために特別なことをする必要はないと強調したいです。「HTML ファイルを作って」とか「HTML アーティファクトを作って」と頼むだけで大丈夫です。

コツは、アーティファクトに何をさせたいか、どのように使うかを知ることです。時間が経てばスキルを作るかもしれませんが、今のところは、さまざまなケースでの使い方を習得するために、ゼロからプロンプトすることをお勧めします。

ユースケース

これをより具体的にするために、さまざまなユースケース向けに多くの HTML ファイルを作成しました。すべてのファイルはこちらでご覧いただけます：https://thariqs.github.io/html-effectiveness/。以下は概要です。

仕様、計画、探索

HTML は、Claude が問題に深く取り組むためのリッチなキャンバスです。問題に取り組み始めるとき、単純な Markdown 計画の代わりに、HTML ファイルのウェブを作成することを期待します。例えば、まず Claude Code にブレインストーミングを依頼し、さまざまなオプションの探索を作成します。次に、そのうちの一つにさらに展開するよう依頼し、モックアップやコードスニペットを作成するかもしれません。最後に、良い感触が得られたら、実装計画を書くよう依頼します。計画に満足したら、新しいセッションを作成し、これらのファイルすべてを渡して実装させます。

検証時には、検証エージェントにファイルを読み込むよう依頼し、必要なものについてより広いコンテキストを持たせます。

プロンプト例:

• オンボーディング画面の方向性が決まりません。6 つの明確に異なるアプローチを生成してください — レイアウト、トーン、密度を変えて — それらを 1 つの HTML ファイルのグリッドに配置し、横並びで比較できるようにしてください。それぞれに、そのトレードオフをラベル付けしてください。
• HTML ファイルに詳細な実装計画を作成してください。モックアップを作成し、データフローを示し、レビューしたい重要なコードスニペットを追加してください。読みやすく、理解しやすいものにしてください。

ユースケース:

• コード内で何かを実装する他の方法を探索する
• 複数のビジュアルデザインを探索する

コードレビューと理解

コードは Markdown ファイルでは読みにくいことがあります。しかし、HTML を使えば、差分、注釈、フローチャート、モジュールなどをレンダリングできます。これを使って、エージェントが書いたコードを理解したり、コードレビューを受けたり、コードをレビューする人に PR を説明したりできます。これはデフォルトの GitHub 差分ビューよりも効果的であることが多く、今ではすべての PR に HTML コード説明書を添付しています。

プロンプト例:

この PR をレビューするのを手伝ってください。それを説明する HTML アーティファクトを作成してください。ストリーミング/バックプレッシャーロジックにあまり詳しくないので、そこに焦点を当ててください。実際の差分をインラインマージン注釈付きでレンダリングし、重要度に応じて発見事項を色分けし、概念をうまく伝えるために必要なその他の要素を追加してください。

ユースケース:

• PR の作成
• PR のレビュー
• コード内のトピックの理解

デザインとプロトタイプ

Claude Design は HTML に基づいています。なぜなら、HTML はデザインにおいて非常に表現力豊かだからです。最終的な表面が HTML でなくても同様です。Claude は HTML でデザインをスケッチし、その後、React、Swift など、任意の言語で記述できます。

アニメーションやアクションなどのインタラクションもプロトタイプできます。Claude にスライダーやノブなどを作成してもらい、探しているものを正確に調整することを検討してください。

プロンプト例:

新しいチェックアウトボタンをプロトタイプしたいです。クリックすると再生アニメーションが実行され、すぐに紫色に変わります。このアニメーションのさまざまなオプションを試すためのスライダーとオプションを備えた HTML ファイルを作成し、うまくいったパラメータをコピーするためのコピーボタンを追加してください。

これを使用するケース:

• デザインシステムのアーティファクトの作成
• コンポーネントの調整
• コンポーネントライブラリの可視化
• 楽しいアニメーションのプロトタイプ

レポート、調査、学習

Claude Code は、複数のデータソースにわたる情報を統合し、読みやすいレポートに変換するのが非常に得意です。Claude に Slack、コードベース、git 履歴、インターネットなどを検索するようプロンプトし、自分自身、リーダーシップ、チームなど向けに非常に読みやすいレポートを生成できます。

これは、長い HTML 文書、インタラクティブな説明、あるいはスライドショー/デッキの形式でまとめることができます。Claude に図には SVG を使用するよう依頼して、視覚化を助けてもらいましょう。

例えば、プロンプトキャッシングに関する私の投稿では、Claude に git 履歴を読んだ後、プロンプトキャッシングへのすべての変更について読むための詳細な調査ファイルを HTML で準備するよう依頼しました。

プロンプト例:

レートリミッターが実際にどのように動作するのか理解できません。関連するコードを読み、1 つの HTML 説明ページを作成してください：トークンバケットフローの図、注釈付きの 3〜4 の主要なコードスニペット、そして下部に「注意点」セクションを設けてください。一度読んだだけで理解できるように最適化してください。

これを使用するケース:

• 機能の仕組みを要約する
• コンセプトを説明する
• 上司への週次ステータスレポート
• リーダーシップへのインシデントレポート
• SVG イラスト、フローチャート、技術図など

カスタム編集インターフェース

テキストボックスだけで自分の望みを説明するのが難しい場合があります。そのような場合、私は Claude に、今取り組んでいるものに特化した使い捨てのエディターを作ってもらいます。製品や再利用可能なツールではなく、この 1 つのデータのために特別に作られた単一の HTML ファイルです。

コツは、常にエクスポートで終わることです。「JSON としてコピー」または「プロンプトとしてコピー」ボタンで、UI で行ったことを Claude Code に貼り付けられるものに変換します。

プロンプト例:

• 30 個の Linear チケットの優先順位を再設定する必要があります。各チケットを Now / Next / Later / Cut の列にドラッグ可能なカードとして配置した HTML ファイルを作成してください。あなたの最善の推測で事前に並べ替えてください。最終的な順序をバケットごとに 1 行の根拠とともにエクスポートする「Markdown としてコピー」ボタンを追加してください。
• これが私たちのフィーチャーフラグ設定です。フォームベースのエディターを作成し、フラグをエリアごとにグループ化し、それらの間の依存関係を表示し、前提条件がオフのフラグを有効にしようとしたら警告してください。変更されたキーだけを提供する「差分をコピー」ボタンを追加してください。
• このシステムプロンプトを調整しています。左右に並んだエディターを作成してください：左側に変数スロットが強調表示された編集可能なプロンプト、右側にテンプレートを埋めた状態をライブで再レンダリングする 3 つのサンプル入力を配置してください。文字数/トークンカウンターとコピーボタンを追加してください。

これを使用するケース:

• あらゆるものの並べ替え、トリアージ、バケット化（チケット、テストケース、フィードバック）
• 構造化設定の編集（フィーチャーフラグ、環境変数、制約付き JSON/YAML）
• ライブプレビュー付きのプロンプト、テンプレート、コピーの調整
• データセットのキュレーション、行の承認/却下、例のタグ付け、選択範囲のエクスポート
• ドキュメント、トランスクリプト、差分への注釈付けと注釈のエクスポート
• テキストで表現するのが難しい値の選択：色、イージングカーブ、クロップ領域、cron スケジュール、正規表現

よくある質問

HTML に切り替えたことを多くの人に話してきましたが、いくつか繰り返し聞かれる質問があります。

トークン効率が悪くないですか？

Markdown の方がトークン数が少ないことが多いですが、HTML の表現力の向上と、私がそれを読む可能性がはるかに高いことから、全体的により良い出力が得られると感じています。Opus 4.7 の 100 万トークンのコンテキストウィンドウでは、トークン使用量の増加はコンテキストウィンドウ内でほとんど気になりません。

今は Markdown をいつ使いますか？

正直なところ、ほとんどすべてのことで Markdown を使うのをやめましたが、私はおそらく HTML マキシマリスト側にかなり偏っています。

HTML ファイルはどうやって表示しますか？

私はローカルでブラウザで開くことが多いです（Claude に開くよう依頼できます）。共有可能なリンクが必要な場合は S3 にアップロードします。

Markdown よりも生成に時間がかかりませんか？

確かに時間がかかります！HTML は Markdown の 2〜4 倍の時間がかかることがありますが、結果には価値があると感じています。

バージョン管理はどうですか？

これは正直なところ HTML の最大の欠点の一つです。HTML の差分はノイズが多く、Markdown と比較してレビューが難しいです。

Claude に自分の好みに合わせてもらうには／見苦しくならないようにするには？

フロントエンドデザインプラグインは、Claude が良い HTML ファイルを作成するのに役立ちます。しかし、自社のスタイルに合わせるには、Claude にコードベースを指定して、単一のデザインシステム HTML ファイルを作成できます。その後、そのデザインシステムファイルを他の HTML ファイルのリファレンスとして使用できます。

最新情報を入手

以上すべてをまとめると、私が HTML を使う本当の理由は、Claude との連携をより強く感じられるからだと思います。計画を深く読むのをやめたことで、単に Claude に選択を任せるしかなくなるのではないかと恐れ始めていました。

しかし、HTML を使うことで、これまで以上に連携を感じられていると嬉しく思います。皆さんもそうなることを願っています。