Claude CodeでHTMLがめちゃくちゃ効く理由

導入：Markdownは便利だけど、だんだん窮屈になってきた

Markdownは、エージェントが私たちに情報を渡すための標準的なファイル形式になっている。シンプルで、持ち運びやすく、ある程度のリッチテキストも表現できて、人間が編集しやすい。ClaudeはMarkdown内でASCII図を描くことすらかなり上手くなった。

でも、エージェントがより強力になるにつれて、Markdownは制約の強い形式だと感じるようになった。100行を超えるMarkdownファイルは読みづらい。もっとリッチな可視化、色、図が欲しいし、簡単に共有もしたい。

それに、私はもうこうしたファイルを自分で直接編集することが減っている。仕様書、参照資料、ブレスト結果として使うことが多い。編集するときも、たいていClaudeに編集を頼む。つまり、Markdown最大の利点だった「人間が編集しやすい」ことの価値が薄れてきている。

だから私は、MarkdownではなくHTMLを出力形式として好むようになった。Claude Codeチーム内でも同じ使い方をしている人が増えている。以下、その理由を書いていく。

なぜHTMLなのか：情報密度

HTMLはMarkdownよりもずっと豊かな情報を表現できる。見出しや装飾のような文書構造はもちろん、表、CSSによるデザイン、SVGイラスト、コードスニペット、JavaScriptとCSSを使ったインタラクション、ワークフロー図、絶対配置やcanvasによる空間情報、画像などを扱える。

かなり強く言えば、Claudeが読み取れる情報のほとんどは、HTMLでかなり効率よく表現できる。つまりHTMLは、モデルが深い情報を人間に伝え、人間がそれをレビューするための効率的な手段になる。

HTMLが使えないと、モデルはMarkdownで無理をしがちだ。ASCII図を書いたり、色をUnicode文字で表そうとしたりする。Claude CodeがMarkdownで色を表そうとしたスクリーンショットは、その典型例だ。

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

Claudeがより複雑な仕事をこなせるようになるほど、仕様書や計画書も長く複雑になっていく。実際のところ、私は100行を超えるMarkdownをちゃんと読むことがあまりないし、組織内の他の人に読ませるのも難しい。

一方、HTML文書は読みやすい。Claudeはタブ、図、リンクなどを使って、ナビゲーションしやすい構造を作れる。モバイル対応もできるので、読むデバイスに合わせて表示を変えられる。

共有しやすい

Markdownファイルは共有しにくい。ブラウザが標準で綺麗にレンダリングしてくれるわけではないので、メールやメッセージに添付することになりがちだ。

HTMLなら、S3などにアップロードすればリンクとして共有できる。同僚は好きな場所で開いて参照できる。仕様書、レポート、PR説明を実際に読んでもらえる確率は、HTMLのほうがずっと高い。

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

HTMLでは、文書と対話できる。たとえばデザインを調整するためのスライダーやノブを入れたり、アルゴリズムの選択肢を変えて結果を見るUIを作ったりできる。さらに、その変更内容をClaude Codeに貼り戻すためのプロンプトとしてコピーできるようにもできる。

この「読むだけではなく、触って結果を返す」使い方ができるのはHTMLの強みだ。

データ取り込み：Claude CodeでHTMLを作る理由

なぜClaudeAIやClaude Designではなく、Claude CodeでHTMLファイルを作るのか。大きな理由は、Claude Codeが取り込める文脈の広さだ。

この記事を書くときも、筆者はClaude Codeに自分のコードフォルダを読ませ、生成済みHTMLを探し、分類し、各タイプを図解するHTMLを作らせた。記事内の図はその結果だ。

ファイルシステムだけでなく、MCP経由のSlackやLinear、ブラウザ、git履歴などから追加文脈を取れる。だからClaude Codeは、単なるHTML作成ツールではなく、文脈を吸い上げて読みやすい成果物にする場になる。

楽しい

ClaudeでHTML文書を作るのは単純に楽しい。作っているものに自分が関わっている感覚が強くなる。それだけでも十分な理由になる。

始め方：スキル化しすぎなくていい

筆者は、この記事を読んだ人がすぐに /html スキルのようなものを作りたくなるのを少し心配している。価値はあるかもしれないが、最初からそこまでしなくていい。

まずはClaudeに「HTMLファイルを作って」「HTML artifactを作って」と頼めばいい。大事なのは、そのartifactに何をさせたいのか、自分がどう使うのかを分かっていること。慣れてからスキル化すればいい。

ユースケース1：仕様、計画、探索

HTMLは、Claudeが問題に深く潜るための豊かなキャンバスになる。単純なMarkdown計画ではなく、複数のHTMLファイルを作る流れがあり得る。

たとえば最初に複数案をブレストさせ、次に特定案を深掘りし、モックやコードスニペットを作らせる。納得したら実装計画を書かせ、新しいセッションでそのHTML群を渡して実装させる。検証エージェントにも同じHTMLを読ませれば、必要な文脈が広く伝わる。

ユースケース2：コードレビューと理解

コードはMarkdownだと読みづらい。HTMLならdiff、注釈、フローチャート、モジュール関係などをレンダリングできる。エージェントが書いたコードを理解したり、PRレビューをしたり、レビュー担当者に説明したりするのに向いている。

筆者は、GitHubの通常diffよりもHTML説明のほうが機能することが多いと感じており、自分のPRには毎回HTMLのコード解説を添付している。

ユースケース3：デザインとプロトタイプ

Claude DesignがHTMLをベースにしているのは、HTMLがデザイン表現に非常に強いからだ。最終的な実装先がReactでもSwiftでも、ClaudeはまずHTMLでデザインを描き、その後で目的の言語に落とし込める。

アニメーションや操作のプロトタイプも作れる。スライダーやノブを用意して、求めている動きを調整させることもできる。

ユースケース4：レポート、調査、学習

Claude Codeは、複数の情報源から情報を合成し、読みやすいレポートに変換するのが非常に得意だ。Slack、コードベース、git履歴、インターネットなどを調べさせ、自分向け、上司向け、チーム向けの読みやすいレポートを作れる。

長いHTML文書、インタラクティブな解説、スライド/デッキ形式にもできる。SVGで図を描かせると理解しやすい。

ユースケース5：専用編集インターフェース

テキストボックスだけでは、自分が欲しいものを説明しづらいことがある。そんなとき、Claudeに「今このデータを編集するためだけの使い捨てHTMLエディタ」を作らせる。

ポイントは最後に必ずエクスポートを付けることだ。「copy as JSON」「copy as prompt」のように、UI上で操作した結果をClaude Codeに貼り戻せる形にする。

FAQ

HTMLはトークン効率が悪くない？
Markdownのほうがトークン数は少ないことが多い。でもHTMLの表現力と、人間が実際に読む可能性の高さを考えると、全体として良い出力になる。Opus 4.7の100万コンテキストでは、トークン増加もあまり気にならない。

今Markdownはいつ使う？
筆者はほぼ何でもHTMLにしていて、HTML最大主義寄りになっている。

HTMLファイルはどう見る？
ローカルでブラウザを開くか、共有したいならS3などにアップロードしてリンクにする。

生成に時間がかからない？
かかる。Markdownの2〜4倍かかることもある。でも結果にはそれだけの価値がある。

バージョン管理は？
ここは大きな弱点。HTMLのdiffはMarkdownよりノイズが多く、レビューしづらい。

自分の好みに合わせるには？
frontend design pluginが役に立つ。さらに自社のスタイルに合わせたいなら、コードベースを見せて単一のデザインシステムHTMLを作らせ、それを以後のHTML生成の参照にする。

結論：Claudeとの作業に「自分が関与している感覚」が戻る

筆者がHTMLを使う本当の理由は、Claudeとの作業において、より「ループの中にいる」と感じられることだ。計画を深く読まなくなったせいで、Claudeに判断を任せきりになってしまうのではないかという不安があった。

しかしHTMLを使うことで、以前よりもずっとループの中にいられるようになった。読者にもそう感じてほしい、という締めくくり。