← claude.dev 日本語訳

· Playbooks

『Claude Code』の活用：HTMLの信じられないほどの有効性

Using Claude Code: The unreasonable effectiveness of HTML

Thariq Shihipar

この記事は 原文 を DeepL で機械翻訳したものである。正確な内容は原文を参照のこと。

Markdownは、エージェントが人間とコミュニケーションをとる際に使用される主要なファイル形式となっています。シンプルで移植性が高く、リッチテキスト機能も備えており、編集も容易です。Claudeは、ASCII文字を使ってMarkdownファイル内に図を作成する機能も、驚くほど洗練されてきました。

しかし、エージェントの機能がますます強力になるにつれて、Markdownというフォーマットには制限が多いと感じるようになりました。具体的には、100行を超えるMarkdownファイルは読みづらいと感じます。また、Claudeを使って、より豊かな視覚化や色付け、図表を作成したいですし、こうした成果物をより簡単に共有できるようにしたいと考えています。

私も、これらのファイルを自分で編集することはますます少なくなり、仕様書や参照ファイルとして活用するようになってきました。編集を行う場合でも、たいていはClaudeに編集を依頼しているため、Markdownの最大の利点の一つが失われてしまっています。

その代わりに、私はMarkdownの代わりにHTMLを出力形式として好むようになり、Claude Codeチームの他のメンバーもこの手法を取り入れるケースが増えてきているのを感じています。この記事では、私たちのチームがなぜ、そしてどのようにHTMLを活用して、より豊かで読みやすいClaude Codeの出力を生成しているのかについてご紹介します。もし実践してみたいという方は、一般的なユースケース向けに用意されたこれらのHTMLファイルテンプレートをぜひ活用してみてください。

なぜHTMLを使うのか？

私が現在Claude Codeを使って行っているような作業において、HTMLがMarkdownよりも適している理由はいくつかあります。具体的には、以下のような要件や要素を伴うタスクが含まれます：

情報密度

HTMLは、Markdownに比べてはるかに豊富な情報を表現することができます。もちろん、見出しや書式設定といった単純な文書構造を表現できるだけでなく、次のようなさまざまな情報も表現可能です：

  • 表を使用した表形式のデータ
  • CSS を使ったデザインのデータ
  • SVGを使用したイラスト
  • scriptタグを含むコードスニペット
  • JavaScript および CSS を用いた HTML 要素の操作
  • SVG および HTML を使用したワークフロー
  • 絶対位置とキャンバスを使用した空間データ
  • imageタグを使用した画像

私の考えでは、Claudeが読み取れる情報のうち、HTMLで効率的に表現できないものはほとんどないと思います。このため、モデルが詳細な情報をユーザーに伝え、ユーザーがそれを確認するための非常に効率的な手段となります。

これをできない場合、モデルはMarkdown内で、ASCII図や、私のお気に入りのユニコード文字を使った色の近似など、より非効率的な処理を行う可能性があることがわかりました。

図A：Markdownしか選択肢がない場合のカラーパレットの例。
図A：Markdownしか選択肢がない場合のカラーパレットの例。

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

Claudeはより複雑な作業にも対応できるようになったため、仕様書や計画書もますます分厚くなってきています。私自身、100行を超えるMarkdownファイルは実際には読まない傾向にあることに気づきましたし、組織内の他の誰かにそれを読ませることも到底できません。

しかし、HTMLドキュメントは読みやすさが格段に優れています。Claudeは、タブや図解、リンクなどを活用して、ナビゲーションに最適な構造を視覚的に整理できるからです。さらに、モバイル対応も可能なため、端末の画面サイズに応じて異なる表示方法で閲覧することもできます。

共有のしやすさ

Markdownファイルは、ほとんどのブラウザが標準ではうまく表示できないため、共有するのがかなり難しいです。多くの場合、メールやメッセージの添付ファイルとして送信する必要があります。

HTMLファイルをアップロードすれば、リンクを簡単に共有できます。同僚は好きな場所でそのリンクを開き、手軽に参照することができます。

仕様書、報告書、あるいはPRの解説文をHTML形式で作成しておけば、実際に誰かがそれを読んでくれる可能性ははるかに高くなります。

双方向の相互作用

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

必要に応じて、これにより、取り組んでいる特定の問題に合わせて個別の編集環境を作成することができます。

データの取り込み

Claude.ai や Claude ではなく、Claude Code を使って HTML ファイルを作成する最大の理由の一つは、Claude Code が取り込むことができる豊富なコンテキストにあります。 例えば、この記事を執筆する際、私はClaude Codeに、自分のコードフォルダをスキャンして生成したすべてのHTMLファイルを見つけ出し、それらをグループ化・分類した上で、各タイプを表す図解を含むHTMLファイルを作成するよう依頼しました。この記事に掲載されている図解は、まさにその成果です。

ファイルシステムに加え、Claude Codeは、MCP（Slack、Linearなど）、ウェブブラウザ（ChromeのClaudeなど）、およびGitの履歴から、追加のコンテキスト情報を取得することができます。

はじめに

注目すべき点が1つあります。ClaudeにこのようなHTMLを生成させるのに、特別な手間はかかりません。「HTMLファイルを作成する」や「HTMLアーティファクトを作成する」と指示するだけで済みます。 重要なのは、その成果物にどのような機能を持たせたいか、そしてそれをどのように活用したいかを明確にすることです。時間が経つにつれて、繰り返し現れるパターンに基づいてスキルを構築するのが理にかなってくるかもしれませんが、まずは一からプロンプトを入力することから始めるのが、さまざまなユースケースにおいてどのように機能するかを把握するための良い方法です。

活用事例

このアプローチをより具体的に説明するために、以下に、MarkdownよりもHTMLファイルを使用したほうが理にかなっていると思われるユースケースの例をいくつか挙げます。また、これらのユースケースに関するGitHubのギャラリーもこちらからご覧いただけます。

仕様、計画、および調査

HTMLは、Claudeが問題に深く掘り下げるための豊かなキャンバスです。問題に取り組み始める際、単純なMarkdownの計画書ではなく、HTMLファイルのネットワークを作成することを想定しています。例えば、まずClaude Codeにアイデア出しを依頼し、さまざまな選択肢について検討を進めてもらうことから始めるかもしれません。 次に、そのうちの1つをさらに掘り下げ、インターフェースのモックアップやサンプルを作成するよう依頼します。最後に、納得がいく状態になったら、実装計画の作成を依頼します。その計画に満足したら、新しいセッションを作成し、これらのファイルをすべて渡して実装してもらいます。

確認の際には、確認担当者にファイルの内容を読み上げてもらうように依頼します。そうすることで、何が必要なのかについて、より広範な文脈を把握できるようになります。

図B 検討：複数のアプローチを並べて比較し、それぞれのトレードオフを1ページにまとめたもの。
図B 検討：複数のアプローチを並べて比較し、それぞれのトレードオフを1ページにまとめたもの。

プロンプトの例：

  • オンボーディング画面をどの方向にすべきか迷っています。レイアウト、トーン、情報密度を変化させた、6つのまったく異なるアプローチを作成し、それらを1つのHTMLファイル内にグリッド形式で並べて、並べて比較できるようにしてください。それぞれに、そのアプローチがもたらすトレードオフを明記してください。
  • HTMLファイルに詳細な実装計画を作成してください。必ずモックアップを作成し、データフローを示し、私が確認したいと思われる重要なコードスニペットを追加してください。読みやすく、理解しやすいものにしてください。

次のような場合に使用してください：

  • コードで何かを実装するための他の方法を模索する
  • 複数のビジュアルデザインを同時に試す

コードレビューと理解

Markdownファイルではコードが読みづらい場合がありますが、HTMLを使えば、差分表示、注釈、フローチャート、モジュールなどを表示できます。HTMLを活用して、エージェントが書いたコードを理解したり、コードをレビューしたり、コードをレビューしてくれる相手にプルリクエストの内容を説明したりしましょう。

図 C コードレビュー：重大度タグ付きの余白注釈付きで表示された差分。
図 C コードレビュー：重大度タグ付きの余白注釈付きで表示された差分。

プロンプトの例：

このPRのレビューを手伝ってほしいので、その内容を説明するHTMLドキュメントを作成してください。私はストリーミングやバックプレッシャーのロジックにあまり詳しくないので、その点に重点を置いてください。実際の差分にはインラインの余白注釈を付け、発見事項は重大度に応じて色分けし、概念をわかりやすく伝えるために必要なその他の要素も盛り込んでください。

次のような場合に使用してください：

  • プルリクエストの作成
  • PRのレビュー
  • コードを通じてトピックを理解する

設計と試作品

Claude デザインはHTMLを基盤としています。なぜなら、たとえ最終的な表示形式がHTMLでなかったとしても、HTMLはデザインにおいて非常に表現力に富んでいるからです。Claudeを使えば、HTMLでデザインのスケッチを作成し、その後、ReactやSwiftなど、お好みの言語で実装することができます。

また、アニメーションやアクションなどのインタラクションのプロトタイプを作成することも可能です。Claudeに依頼して、スライダーやノブなどを作成してもらい、思い通りの動作に微調整することを検討してみてください。

図D デザイン：トークンとコンポーネントが、実際の表示通りに描画されています。
図D デザイン：トークンとコンポーネントが、実際の表示通りに描画されています。

プロンプトの例：

新しいチェックアウトボタンのプロトタイプを作成したいのですが、クリックすると再生アニメーションが再生され、その後すぐに紫色に変わるようにしたいです。このアニメーションのさまざまな設定を試せるよう、複数のスライダーとオプションを備えたHTMLファイルを作成してください。また、うまくいったパラメータをコピーできる「コピー」ボタンも用意してください。

次のような場合に使用してください：

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

レポート、調査、学習

Claude Code 複数のデータソースにわたる情報を効果的に統合し、読みやすいレポートに変換するのに非常に優れています。Claudeに指示を与えることで、Slack、コードベース、Gitの履歴、あるいはインターネットを検索させ、読みやすいレポートを生成することができます。

これを、長いHTMLドキュメント、インタラクティブな解説資料、あるいはスライドショーやプレゼンテーション資料の形式で作成することも可能です。視覚化を容易にするため、図表にはSVGを使用するよう、Claudeに依頼してください。

FIG E レポート：ナビゲーション、折りたたみ可能な手順、タブ付きスニペットを備えた解説記事。
FIG E レポート：ナビゲーション、折りたたみ可能な手順、タブ付きスニペットを備えた解説記事。

プロンプトの例：

当社のレートリミッターが実際にどのように機能しているのか、よく理解できていません。関連するコードを読み、説明用のHTMLページを1つ作成してください。そのページには、トークンバケットのフロー図、注釈付きの重要なコードスニペット3～4箇所、そして下部に「注意点」のセクションを掲載してください。一度だけ読むユーザー向けに最適化してください。

次のような場合に使用してください：

  • 記事の要約の作成
  • 解説文の生成
  • 週次進捗報告書の作成
  • インシデント報告書の作成
  • SVGイラスト、フローチャート、技術図表の作成

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

テキストボックスだけで自分の要望を正確に伝えるのは、時に難しいものです。そんな場合、私はよくClaudeに、現在取り組んでいる作業にぴったり合った使い捨てのエディタを作成してもらうように依頼します。それは製品でも、再利用可能なツールでもなく、その1つのデータのために特別に作られた単一のHTMLファイルなのです。

重要なのは、常にエクスポートで締めくくることです。つまり、「JSONとしてコピー」や「プロンプトとしてコピー」といったボタンを用意し、UI上で行った操作の結果を、Claude Codeに貼り付けたり、ファイルに保存したりできる形式に変換するのです。作業の流れを維持しつつ、その流れをよりスムーズにするのです。

プロンプトの例：

  • これら30件のLinearチケットの優先順位を見直す必要があります。各チケットを「今」「次」「後」「削除」の各列間でドラッグ可能なカードとして表示したHTMLファイルを作成してください。あなたの判断で最適な順序に事前に並べ替えておいてください。また、「Markdownとしてコピー」ボタンを追加し、最終的な順序と、各カテゴリごとの1行の理由をエクスポートできるようにしてください。
  • こちらが当社のフィーチャーフラグの設定です。これ用のフォームベースのエディタを作成し、フラグをエリアごとにグループ分けし、フラグ間の依存関係を表示してください。また、前提条件がオフになっているフラグを有効にしようとした場合は警告を表示するようにしてください。さらに、変更されたキーのみを表示する「差分をコピー」ボタンを追加してください。
  • 現在、このシステムのプロンプトを調整しています。左右並列のエディタを作成してください。左側には変数スロットがハイライト表示された編集可能なプロンプトを、右側には入力された内容に応じてテンプレートをリアルタイムで再描画する3つの入力例を表示します。文字数／トークン数カウンターとコピーボタンも追加してください。

次のような場合に使用してください：

  • （チケット、テストケース、フィードバックなど）の並べ替え、優先順位付け、または分類
  • 構造化された設定の編集（機能フラグ、環境変数、制約付きJSON/YAML）
  • ライブプレビュー機能を使って、プロンプト、テンプレート、またはコピーを調整する
  • データセットのキュレーション — 行の承認・却下、例へのタグ付け、選択したデータのエクスポート
  • 文書、トランスクリプト、または差分ファイルに注釈を付け、その注釈をエクスポートする
  • テキストで表現するのが難しい値の選択：色、イージングカーブ、切り抜き範囲、cronスケジュール、正規表現

よくある質問

Claude CodeでのHTMLの使用に関して、私が最もよく受ける質問と、私が実践している実用的な日常の習慣を以下にまとめました：

それだと効率が悪くなるんじゃないですか？

Markdownでは通常、使用されるトークンの数が少ないですが、HTMLの方が表現力に富んでいるうえ、私がそれを読む可能性がはるかに高いため、結果として全体的な出力が向上すると実感しています。Opus 4.7の1MMコンテキストウィンドウを使用すれば、トークンの使用量が増加しても、コンテキストウィンドウ上ではほとんど気になりません。

今のところ、いつMarkdownを使っていますか？

正直なところ、ほとんどすべての場面でMarkdownを使うのをやめてしまったのですが、おそらく私はHTMLの「マキシマリスト」寄りの立場にあるのでしょう。

これが、あなたが計画に代えてきたものなのか？

私は、単一の計画を作成するのではなく、計画のさまざまな部分や段階ごとに、いくつかの異なるHTMLファイルを作成する傾向があることに気づきました。例えば、HTMLで実装計画を作成し、次にUIの検討用の別のファイルを作成し、最後にすべてのデザインを一覧表示するHTMLコンポーネントを作成することもあります。 これらのファイルは、将来の参考資料として、また検証用としても活用できるよう、手元に残しておくようにしています。

CLAUDEの最新情報をチェック

以上のことを踏まえると、私がMarkdownではなくHTMLを使っている本当の理由は、Claudeの動向をより身近に感じられるからなのです。Claudeの業務が増えるにつれ、私は計画を以前ほど注意深く読んでいないことに気づき、単に仕事を任せるだけでなく、その選択に関わり続けたいと思うようになりました。HTMLはまさにそのための手段だったのです。 今では、かつてないほどプロジェクトの進行状況を把握できていると感じています。

Claude Code を始めましょう。

この記事は、技術スタッフの一員であるタリク・シヒパル氏によって執筆されたものであり、Claude CodeでのHTMLファイルの使用に関する同氏の個人的な見解――およびその魅力――が述べられています。