Claude Code を使用して HTML に驚異的な効果をもたらす方法

Claude Code を使用：HTML が信じられないほど効果的である理由

Markdown は、AI エージェント (AI Agent) と私たちがコミュニケーションを取る際に最も頻繁に使用されるファイル形式となっています。それはシンプルで携帯性が高く、一定の富テキスト (Rich text) 機能を備えており、何より人間が容易に編集できる点にあります。あなたはまた、Claude が Markdown ファイル内で ASCII (米国情報交換標準コード、ここでは純粋なテキスト記号を組み合わせて図を描くこと) を用いて図を描くことに極めて長けていることに気づくでしょう。

しかし、AI エージェントがますます強力になるにつれ、Markdown が一種の束縛になっていると感じるようになりました。数百行に及ぶ Markdown ファイルを前にすると、読む気力すら湧きません。私はより豊かな視覚表現、鮮やかな色彩、直感的なチャートを求めており、それらをチームと簡単に共有できることを望んでいます。

また、現在ではこれらのファイルを自分で直接編集する機会がますます減っています。むしろ、これらを手順書 (Specs)、参考資料、あるいはブレインストーミングの出力結果として扱うことが多くなりました。修正が必要な場合でも、通常は Claude に対してプロンプト (Prompt) を記述して直接修正させるようにしています。これにより、Markdown の最も核心的な利点である「人間による編集の容易さ」が完全に失われてしまいました。

そこで、Markdown に代わり、出力形式として HTML をより好むようになりました。また、Claude Code チームの他のメンバーも HTML を使用する頻度を高めていることに気づいています。以下では、その背景にある理由についてお話しします。

（まずは直感的な例をご覧になりたい場合は、こちらをクリックして多数のサンプルをご覧ください：https://thariqs.github.io/html-effectiveness/ 。ただし、ご覧になった後は必ず戻ってきて、なぜそうすべきなのかを私が続ける話を聞いてください。）

なぜ HTML を選ぶのか？

情報密度 (Information Density)

HTML は Markdown よりもはるかに多くの情報を伝えることができます。もちろん、見出しやシンプルなレイアウトといった基本的なドキュメント構造を処理することもできますが、その威力はそれだけにとどまりません。複雑な情報を完璧に表現できるのです。具体的には以下のようなものです：

• テーブル (Tables) を用いてデータ列を表示する

• CSS (カスケードスタイルシート、ウェブページの見た目やレイアウトを制御するために使用される) を用いてデザインの細部を表現する

• SVG (スケーラブルベクターグラフィック、コードベースのクリアな画像フォーマット) を用いて美しいイラストを描画する

• script タグを用いてコードスニペット (Code snippets) を埋め込む

• HTML 要素、JavaScript、CSS を組み合わせて動的なインタラクションを実現する

• SVG と HTML を組み合わせて明確なワークフローチャート (Workflows) を描画する

• 絶対配置とキャンバス (Canvases) を用いて空間分布データを視覚化する

• image タグを用いて画像を直接挿入する

私は敢えて言います。Claude が読み取れる情報であれば、HTML で効率的に表現できないものはほとんどないでしょう。この特性により、HTML は極めて効率的な媒体となり、モデルが深い情報をあなたに伝えたり、あなたがそれらを読み込んで審査したりする際にも、非常にスムーズになります。

もし HTML を使用できない場合、モデルは Markdown 内で極めて非効率な「奇策」を講じることが多いことに気づきました。例えば、ASCII 記号を無理やり使ってチャートを描いたり——私が最も呆れ返るケースですが——Claude Code のスクリーンショットのように、Unicode (ユニコード) 文字を用いて色ブロックを強引に模倣したりすることです。

视觉清晰度与易读性 (Visual Clarity & Ease of Reading)

Claude が扱うタスクが複雑化するにつれ、その出力する要件仕様書や実装計画も膨大なものになっています。実際の業務では、100 行を超える Markdown ファイルを自分で読むことさえほとんどなく、ましてやチームの他のメンバーに読んでもらうなどという期待は抱いていません。

しかし HTML ドキュメントであれば読みやすさが段違いです。Claude はタブ (Tabs)、挿絵、リンクといった視覚要素を活用してドキュメント構造を整然と整理し、極めてナビゲーションしやすいものにできます。さらにモバイル対応も可能で、スマートフォンなど異なるサイズのデバイスでも最適な閲覧体験を提供できます。

易于分享 (Ease of Sharing)

Markdown ファイルを共有するのは実は結構な手間がかかります。なぜなら、多くのブラウザ自体が Markdown を適切にレンダリングできないからです。通常は添付ファイルとして扱い、メールやチャットメッセージに無理やり貼り付けて送るしかありません。

しかし HTML なら話は別です。ファイルをクラウド（例えば S3 というクラウドストレージサービス）にアップロードするだけで、リンクを簡単に共有できます。同僚はいつでもどこでも、あらゆるデバイスでそのリンクを開き、手軽に参照することができます。

要件定義書や分析レポート、コードレビューの解説などが HTML で作成されていれば、他人がそれらを真剣に読み通す確率は間違いなく大幅に向上します。

双向交互 (Two-way Interaction)

HTML を使えば、ドキュメントとの真の双方向インタラクションが可能になります。例えば、Claude にページ上にスライダー (Sliders) やノブを追加させ、デザイン効果を直感的に調整できるようにしたり、いくつかのオプションを提供してアルゴリズムのパラメータを微調整し、結果がどう変わるかを確認できるようにしたりできます。さらに、微調整した完璧なパラメータを「ワンクリックでコピー」するボタンを追加させ、それをそのまま Claude Code へ貼り付けて戻すことも可能です。

この双方向インタラクションの具体例についてもっと知りたい場合は、私が以前投稿した「プレイグラウンド (Playgrounds)」に関する記事をご覧ください：https://x.com/trq212/status/2017024445244924382

数据摄取与理解 (Data Ingestion)

なぜターミナルツールである Claude Code を使って HTML ファイルを生成するのか、ウェブ版の Claude AI や Claude Design ではダメなのか。その最大の理由の一つは、Claude Code が極めて膨大なコンテキスト (Context) 情報を取り込める点にあります。

この記事を書く際も、私は Claude Code に私のコンピュータ内のコードフォルダを自動で走査させ、それらの中から Claude が生成した HTML ファイルをすべて見つけ出し、グループ化して分類し、さらに新しい HTML ページを生成させて各カテゴリのファイルを特徴ごとにチャート表示させるよう指示しました。この記事で見られる画像は、まさにこのワークフローの直接的な産物です。

ローカルファイルシステムに加え、Claude Code は MCP（モデル・コンテキスト・プロトコル：AI モデルが外部ツールやプライベートデータにアクセスすることを可能にする標準規格）を通じて、Slack（チームコミュニケーションソフトウェア）のチャット履歴や Linear（プロジェクト追跡ツール）のタスクボードなど、極めて多様なコンテキスト情報にも接続できます。さらに、ブラウザや Git のバージョン管理履歴など、さまざまなソースから背景知識を取得することも可能です。

非常に楽しい (It's Joyful)

Claude を使って HTML ドキュメントを作成すること自体が、非常に楽しい体験です。これにより、創造プロセスに自分自身をより深く関与させている感覚を得られ、この参加感だけでも十分に魅力的です。

始め方 (How to Get Started)

実は少し心配しているのですが、この記事を読んだ皆さんが、これを専用の「/html」複雑スキル指令やそれに類するものにしてしまうのではないかということです。そのような使い方も価値があるかもしれませんが、特に強調したいのは、Claude に HTML を生成させるために、面倒な設定を一切行う必要がないという点です。普段通りチャットをするように、「HTML ファイルを作って」とか「HTML アーティファクト（Artifact）を生成して」と伝えるだけで十分です。

真の秘訣は、このアーティファクトが何を行い、どのように使用されるべきかを明確に理解することにあります。時間が経てば、自分なりのスキルテンプレートが蓄積されることもあるでしょうが、現時点では、最もシンプルなプロンプトから始めて、さまざまなシナリオでのその驚くべき使い方を徐々に探求することを強くお勧めします。

使用例 (Use Cases)

より直感的に理解していただくために、さまざまな使用シーン向けに多数の HTML ファイルを作成しました。すべてのサンプルはこちらで確認できます：https://thariqs.github.io/html-effectiveness/。以下に、いくつかの中核的なシナリオの概要を記載します。

要件、計画と探索 (Specs, Planning & Exploration)

Claude にとって HTML は、問題を深く掘り下げて議論できる広大なキャンバスです。新しい課題に取り組む際、私はもはや単なる Markdown の計画書を受け取ることを期待するのではなく、複数の HTML ファイルが織りなす思考のネットワークを生成することを望みます。

具体的には、まず Claude Code にブレインストーミングを行わせ、いくつかの実装案を探求させます。次に、その中から一つの案を選んで詳細に展開させ、場合によっては UI のスケッチを描かせたり、コアとなるコードスニペットを書かせたりします。最後に、方向性が定まったと感じたら、初めて詳細な実施計画を作成させます。計画に完全に満足したら、新しいセッションを開始し、蓄積されたすべての HTML ファイルを AI に読み込ませて、いよいよコーディングを開始させます。

検証の段階でも、チェックを担当する AI インテリジェンス・セッションにこれらの HTML ファイルを読み込ませることで、より広範な全体像を持ち、私たちが実際に何を達成しようとしているのかを明確に把握できるようにしています。

プロンプトの例：

• 初心者向けガイド画面 (Onboarding screen) のデザインスタイルが決まっていません。レイアウト、トーン、情報密度に違いを持たせた 6 つの全く異なる案を生成し、それらを同じ HTML ファイル内のグリッドレイアウトに配置して並列比較できるようにしてください。各案には、その選択がもたらすトレードオフ（取舍）を明確に記載してください。

• 1 つの HTML ファイル内に、詳細な実施計画を作成してください。データフローを示すビジュアルスケッチを描き、重点的にレビューが必要なコードスニペットを追加することを忘れないでください。レイアウトは明瞭にし、読み手が理解しやすいものにしてください。

適用シーン：

• コードの他の実装方法を探索する
• 並行して複数のビジュアルデザイン案を探索する

コードレビューと理解 (Code Review & Understanding)

Markdown ファイルの中でコードを直接読み解くのは絶対に苦痛な作業です。しかし HTML を用いれば、コードの違いを比較した差分表示 (Diffs)、詳細なページ余白の注釈 (Annotations)、フローチャート (Flowcharts)、そしてモジュール構造図などをエレガントにレンダリングすることができます。

これを使って、AI エージェントが作成した複雑なコードを理解したり、コードレビューの提案を取得したり、PR (Pull Request，プログラマーがコードをマージする際に提出する説明) を提出する際に関係者に自分の考え方を説明したりできます。この方法は GitHub 標準の差分表示ビューよりも一万倍使いやすいと感じています。現在では PR を提出するたびに、必ず HTML 形式のコード解説ページを添付しています。

プロンプトの例：

• この PR をレビューして、そのロジックを私に説明する HTML 製品を作成してください。データフローとバックプレッシャー論理 (Backpressure，受信側が処理しきれない場合に送信側に送信速度を遅くするようフィードバックするメカニズム) にはあまり詳しくないので、この部分を重点的に分析してください。実際のコード差分をレンダリングし、その横に行ごとの注釈をつけてください。問題の深刻度に応じて色分けを行い、概念を伝えるのに役立つ視覚的な図表も追加してください。

適用シーン：

• PR の説明ドキュメントを作成する
• 同僚や AI が提出した PR をレビューする
• コードベース内の特定の複雑なトピックを素早く理解する

デザインとプロトタイプ制作 (Design & Prototypes)

Claude Design の根底にあるロジックは HTML です。最終製品のレンダリング端末がウェブページでなくても、HTML はデザインコンセプトを表現する点において比類なき優位性を持っています。Claude はまず HTML で素早くデザインのスケッチを描き、それを必要なプログラミング言語（React、Swift、あるいは他の言語）に変換することができます。

また、滑らかなインタラクションプロトタイプの作成にも利用できます。例えばアニメーション効果やユーザーの操作フローなどです。Claude にスライダーやノブを追加させてもらえば、実際に手を動かして細部を自分心目中的な完璧な状態まで微調整できるようになります。

プロンプトの例：

• 新しいチェックアウトボタン用のインタラクションプロタイプを作りたいです。クリックするとアニメーションが再生され、すぐに紫色に変わるものです。いくつかのスライダーとオプションを備えた HTML ファイルを生成し、このアニメーションの異なるパラメータ設定を繰り返しテストできるようにしてください。「コピー」ボタンも忘れずに用意して、試行錯誤の結果として完璧だと感じたパラメータをワンクリックでコピーできるようにしてください。

適用シーン：

• デザインシステム (Design system) に関連するコンポーネント資産を作成する
• UI コンポーネントの細部を直感的に微調整する
• つまらないコンポーネントライブラリを視覚的に表現する
• おもしろいアニメーションインタラクションプロトタイプを作る

レポート、調査、学習 (Reports, Research & Learning)

Claude Code は膨大な量の多様なソースデータを統合し、それらを非常に読みやすいレポートに要約することに極めて長けています。Slack のチャット履歴、コードベース、Git のコミット履歴、さらにはインターネット全体を Claude に検索させ、あなた自身や上司、チームのために一目でわかる美しいレポートを作成させることができます。

これを長編の HTML ドキュメント、インタラクティブな解説ページ、あるいはスライド/プレゼンテーション (Deck) としてレイアウトすることも可能です。Claude に SVG 形式で図表を描画させるよう促すのを忘れないでください。これにより、レポートの視覚的表現力が劇的に向上します。

例えば、プロンプトキャッシュ (Prompt Caching) に関する深掘り記事を書く際、私は Claude に関連モジュールの Git ヒストリーを読み込ませ、その期間にキャッシュロジックに対して行ったすべての変更を体系的に整理した、詳細な HTML レポートを生成させました。

プロンプト例：

• 当社のレートリミッター (Rate limiter) がどのように動作しているのか、ずっと理解できませんでした。関連コードを読み込み、トークンバケットフロー (Token-bucket flow) のデータフロー図と、詳細な注釈付きの核心となるコードスニペットを 3〜4 セクション含んだ単一ページの HTML 解説ドキュメントを作成してください。また、ページ下部には「よくある落とし穴 (Gotchas)」セクションを単独で配置してください。レイアウトを最適化し、他者が一度読むだけで完全に理解できるよう配慮してください。

適用シーン：

• 複雑な機能の動作原理の要約
• 難解な概念を平易に解説
• 上司向けに素早く美しい週次業務報告書を作成
• 経営層向けに直感的な障害/インシデントの事後分析レポートを提供
• SVG イラスト、フローチャート、技術アーキテクチャ図の自動描画

カスタム編集インターフェース (Custom Editing Interfaces)

時として、単なるテキスト入力ボックスでは複雑なニーズを正確に記述することが困難です。そのような場合、私は Claude に手元の作業に合わせて、「使い捨て」の簡易な可視化エディターを素早く構築させます。これは完成された製品でも、再利用可能な汎用ツールでもなく、特定のデータセットのために特別に設計された単一の HTML ファイルに過ぎません。

ここで重要なコツは、インターフェースにエクスポート機能を必ず設けることです。「JSON としてコピー」または「プロンプトとしてコピー」といったボタンを用意し、この美しい UI 内で行った操作の結果をそのまま Claude Code に貼り付けて、次のステップに進めるようにします。

プロンプト例：

• Linear のタスク 30 件の優先順位を再整理したいです。HTML ファイルを作成し、各タスクをドラッグ可能なカードとして配置してください。カラムは「現在 (Now) / 次期 (Next) / 後回し (Later) / 削除 (Cut)」の 4 つに跨って設けてください。あなたの判断で事前にソートしておいて構いません。最後に「Markdown としてコピー」ボタンを追加し、最終的な分類と順序付けをワンクリックでエクスポートできるようにしてください。また、各分類に対して簡潔な判断理由も付記してください。

• これが当社の機能フラグ (Feature flag) の設定ファイルです。フォームベースのエディターを生成し、機能モジュールごとにフラグを適切にグループ化して表示してください。相互の依存関係も示してください。もしあるフラグを有効にした際に、その前提となる依存フラグがまだ無効な状態であれば、ポップアップで警告を表示してください。最後に「差分のみコピー」ボタンを追加し、変更したキーと値のペアだけをエクスポートできるようにしてください。

• 私はこのシステムプロンプトの調整を行っています。左右に分割されたエディターを作成してください：左側には編集可能なプロンプトテンプレート、右側には 3 つのサンプル入力ソースを配置します。左側のテンプレートを修正すると、右側では変数を埋め込んだ最終結果がリアルタイムでレンダリングされるようにします。また、画面には文字数とトークン（大規模言語モデルがテキストを処理する基本単位）のカウンター、そしてワンクリックコピーボタンも実装してください。

適用シーン：

• 何らかのものを再順序付け、分類・選別、またはグループ化すること（タスクリスト、テストケース、ユーザーフィードバックなど）

• 構造化された設定情報の編集（機能フラグ、環境変数、複雑な制約条件を持つ JSON/YAML など）

• リアルタイムプレビュー機能を活用してプロンプト、テンプレート、またはコピーライティングを最適化すること

• データセットの整理、特定データ行の承認/拒否、サンプルへのラベル付け、および選択結果のエクスポート

• 長文ドキュメント、音声書き起こし、またはコード差分に対して詳細な注釈を追加し、その注釈内容をエクスポートすること

• 純粋なテキストでは記述するのが極めて困難なパラメータの選定：カラーコード、アニメーションイージングカーブ（Easing curves）、クロップ領域、Cron 定期タスク式（サーバーで定期的にタスクを実行する時間を設定するための形式）、正規表現（Regexes）など。

よくある質問 (Frequently Asked Questions)

私はこれまで多くの人々に、私がどのようにして完全に HTML チームに鞍替えしたかを推奨してきましたが、その過程で以下の頻出質問を何度も受けています。

これでトークン効率の無駄遣いにならないのでしょうか？

確かに、Markdown は通常、より少ないトークンを消費します。しかし、HTML の圧倒的な表現力と、人間による可読性の高さが相まって、全体的な出力結果がはるかに良くなることを発見しました。Opus 4.7 モデルの膨大なコンテキストウィンドウである 100 万（1MM）トークンの中で、このわずかな追加のトークン消費はほぼ無視できるレベルです。

では、現在 Markdown を使うのはいつですか？

正直に申し上げますと、私は今やほとんど何でも Markdown を使わなくなりました。ただし、私がすでに「HTML 極端主義者」の道を進みすぎている可能性を認めます。

生成された HTML ファイルはどうやって確認すればよいのでしょうか？

通常はローカル環境でブラウザ直接開きます（Claude に直接開かせることも可能です）。リンクを他人と共有したい場合は、そのままクラウド上の S3 にアップロードするだけです。

これでは Markdown よりも生成が遅くならないのですか？

確かに遅いです！HTML の生成には、Markdown の 2 倍から 4 倍の時間がかかる可能性があります。しかし、私が実際にテストした結果、生成される結果は間違いなくその価値があり、待つだけの甲斐があります。

バージョン管理はどうすればよいのでしょうか？

正直に申し上げますと、これが HTML の最大の痛点の一つです。すっきりとした Markdown に比べて、HTML ファイルはバージョン管理ツールにおける差分比較（Diffs）が非常に雑多になり、コードレビューを行う際に頭を悩ませることになります。

Claude が生成するページを私の審美観に合わせて、あまり醜くならないようにするにはどうすればよいのでしょうか？

Claude には組み込みのフロントエンドデザインプラグインがあり、これによって相当に優れた HTML ページを生成できます。しかし、もしページを貴社のブランドスタイルに完全に一致させたい場合は、Claude にコードベースをスキャンさせて、専用の「デザインシステム用 HTML ファイル」を作成させることができます。その後、このファイルを Claude への参照資料として提供し、他の HTML ページを生成する際に「模倣」させて、スタイルの高度な一貫性を保たせるのです。

人間と機械の協働を維持する (Stay in the Loop)

結局のところ、私がこれほどまでに HTML を愛する根本的な理由は、これが私に、自分がこの循環の中にあり、Claude と共に戦っていることを確かに感じさせてくれるからです。

私は以前、数百行の Markdown プラン書さえも丁寧に読む気が起きないほどだったため、今後はいったん目を閉じて盲目に任せるしかないのかと恐れていました。しかし今は、HTML があるおかげで、これまで以上に自分自身がこの人間と機械が協働する創作の旅に深く関与できていると感じており、とても嬉しく思っています。

あなたもぜひ、早くこの楽しさに気づいていただければ幸いです。