HTMLでMarkdownを置き換える：Claude Codeチームの一次実践（英中対照）
AnthropicのClaude Codeエンジニアリング責任者であるThariq Shihiparが、なぜHTMLのほうがAIの出力形式としてMarkdownより適しているかを解説する。情報密度、可読性、双方向インタラクションを中心とした5つの利点と具体的な活用シーンを詳述。英中対照で学習に適した内容。
*Claude Code：HTMLの驚くほどの有効性*
著者：Thariq Shihipar（Anthropic Claude Code エンジニアリング責任者）| 英中対照版
Markdownは、エージェントが人間とやり取りするための主要なファイル形式として定着してきました。単純で持ち運びやすく、ある程度のリッチテキスト機能を持ち、編集もしやすい。ClaudeはMarkdown内でASCII文字を使ってダイアグラムを描くのも意外と上手くなっています。
ただ、エージェントがますます高度になっていくにつれ、Markdownはますます制約の大きい形式だと感じるようになってきました。具体的には、100行を超えるMarkdownファイルを読み切るのは難しくなり、Claudeにはより豊かな可視化・色・図を生成してほしいし、成果を他者とより簡単に共有したい、という欲求が生まれました。
加えて、私はこれらのファイルを自分で直接編集する場面が減り、ほとんどは仕様書やリファレンスとして利用するようになりました。編集が必要なときでさえ、ほぼClaudeへの指示で対応しています。つまり、Markdown最大の利点である「人間が直接編集しやすい」という強みは、実質なくなってしまうのです。
そのため、私は出力形式としてMarkdownではなくHTMLを使うことを好みはじめ、Claude Codeチームの他のメンバーにもその流れが広がっていると感じています。本記事では、なぜそうしているのか、またチームがどのようにHTMLを使ってより豊かで読みやすいClaude Codeのアウトプットを作っているかを共有します。
もしClaude Codeを使い始めたばかりなら、CC Switch ツール紹介が複数のClaudeツールの切り替えを簡単にします。Claudeの能力を再利用可能なSkillとしてラップする方法については、『Skill入門』をご参照ください。
1. なぜHTMLを使うのか？ / Why Use HTML?
現在私がClaude Codeで行っている作業には、HTMLのほうがMarkdownより適している点がいくつかあります。
以下が、MarkdownよりHTMLを選ぶ理由です。
1. 情報密度 / Information Density
HTMLはMarkdownと比べ、はるかに豊かな情報を伝達できます。もちろん見出しや基本的な体裁などの簡易的な文書構造も扱えますが、それだけではありません。次のようなあらゆる情報を表現できます。
- 表データを
<table>で表現 - CSSでデザイン情報を表現
- SVGで図を描画
<script>タグでコードスニペットを埋め込み- JavaScript＋CSSを使ったHTML要素のインタラクション
- SVGとHTMLによるワークフロー図
- 絶対位置やCanvasを使った空間データ
<img>タグで画像を直接表示
Markdownではほとんど表現できない情報などはClaudeが読めないものではない、というのが私の実感です。結果として、HTMLはモデルがより深い情報をあなたへ伝え、あなたがそれをレビューする上で非常に効率的な手段になります。
逆にこれが使えない状況だと、モデルはMarkdown内でASCII図を無理に使ったり、私のお気に入りの例ですがUnicode文字で色を近似したり、といった非効率な代替策に走りがちです。
2. 視覚的明快さと読みやすさ / Visual Clarity and Ease of Reading
Claudeが複雑なタスクをこなせるようになるにつれ、出力する仕様書や計画書も巨大化します。私は実際、100行を超えるMarkdownを真剣に読めたことがほとんどなく、組織内の他の人にもそれを読んでもらうのはさらに難しいです。
一方でHTML文書は、はるかに読みやすいです。Claudeがタブ、図、リンクといった視覚要素を使って構造を整理できるため、閲覧・ナビゲーションがしやすい。さらにモバイルでも見やすく、画面サイズに応じて適切に再構成できるため、読む場所を選ばず情報を追いやすくなります。
3. 共有しやすさ / Ease of Sharing
Markdownファイルは共有しづらいことがあります。多くのブラウザがMarkdownをネイティブに快適表示できないため、メールやメッセージに添付して送ることが多くなります。
それに対しHTMLは、クラウドにアップロードしてリンクを共有するだけで済みます。同僚は好きなタイミングでどこからでも開いて参照できます。
あなたの仕様書、レポート、PR説明がHTMLなら、実際に読まれる可能性はかなり高まります。
4. 双方向インタラクション / Two-Way Interactions
HTMLは文書への「インタラクション」も可能にします。たとえば、デザインを調整するためのスライダーやノブを追加したり、アルゴリズムの異なる選択肢を切り替えて結果を即座に比較したりできます。さらに、その変更内容をプロンプトとしてコピーし、Claude Codeに貼り戻せるようにすることも可能です。
必要に応じて、取り組んでいる課題に最適化された個別の編集環境を作れる、ということです。
5. データの取り込み / Data Ingestion
Claude.aiやClaude Designではなく、Claude CodeでHTMLを作る最大の理由の一つは、Claude Codeが取り込めるコンテキスト量の大きさです。この記事を作成する際にも、Claude Codeにコードフォルダを一通り読ませ、これまで生成したHTMLをすべて収集して分類し、各タイプを図示したHTMLを作成させました。この記事にある図は、まさにその成果です。
ファイルシステムに加えて、Claude CodeはMCP（Slack、Linearなど）、ブラウザ（ChromeのClaude連携）、Git履歴なども文脈情報として活用できます。
2. 始め方 / Getting Started
重要なのは、ここで挙げたようなHTMLを最初から大量に設定しておく必要がないことです。単に「HTMLファイルを作って」「HTMLアーティファクトを作成して」と指示するだけで始められます。実務上は、成果物が何をするのか、どのように使うのかを明確にすることが重要です。運用が進めば、反復パターンをSkill化すると良いですが、まずはゼロからのプロンプトで、さまざまな用途で試すのが理解を早める一番の方法です。
3. 利用シナリオ / Use Cases
このアプローチが実際に有効な場面を具体化すると、以下のようなユースケースが挙げられます。
1. 仕様、計画、探索 / Specs, Planning, and Exploration
HTMLは、Claudeが問題へ深く入り込むための豊かなキャンバスです。単純なMarkdown計画に頼る代わりに、私は複数のHTMLファイルを網羅的に連携させる構造を作ります。たとえば最初に異なる選択肢のブレインストーミングを依頼し、次にその中の1つをさらに掘り下げてインターフェースのモックアップや具体例を作成させます。最終的に方向性が固まれば実装計画を作る。計画がよければ新しいセッションを作成し、これらのHTML群をすべて読み込ませて実装へ進めます。
検証時には、検証エージェントにこれらのHTMLを読ませることで、必要な前提や意図を広い文脈で把握させることもできます。
プロンプト例 / Example prompts:
オンボーディング画面の方向性がまだ決まっていません。レイアウト、トーン、情報密度をそれぞれ異なる6種類の案を生成してください。1枚のHTML内でグリッド表示し、並べて比較できるようにしてください。各案には、採用したトレードオフを明記してください。
詳細な実装計画を1つのHTMLファイルに作成してください。視覚的なモックアップを入れ、データフローを示し、確認の対象になる重要なコードスニペットを追加してください。読みやすさを重視した構成にしてください。
この用途に使う / Use this for:
- コードの他の実装方法を探索する / Exploring other ways to implement something in code
- 複数のビジュアルデザインを同時に試す / Experimenting with multiple visual designs at once
2. コードレビューと理解 / Code Review and Understanding
Markdownではコードを読むのが難しいことが多いですが、HTMLなら差分表示、注釈、フローチャート、モジュール図をレンダリングできます。AIが書いたコードを理解する、レビューする、PRを他者に説明する用途でHTMLが有効です。
プロンプト例 / Example prompt:
このPRをレビューしたいです。HTML成果物として説明ページを作成してください。特にストリーミング/バックプレッシャー（受信側の処理が間に合わない場合に、送信側へ速度低下を要求する制御）については私の理解が薄いので重点的にお願いします。実際の差分を描画し、インラインで余白注釈を付け、発見事項を重大度ごとに色分けし、概念が伝わりやすい図も必要なら追加してください。
この用途に使う / Use this for:
- PR説明資料の作成 / Creating a PR / 作成文書
- PRレビュー / Reviewing a PR
- コードテーマの理解 / Understanding a topic in code
3. デザインとプロトタイピング / Design and Prototypes
Claude DesignはHTMLを土台にしているのは、最終的な表示先がHTMLでなくても、デザイン表現力という点でHTMLほど適したものがないためです。ClaudeはまずHTMLでラフに設計し、そこからReactやSwiftなど必要な言語へ変換できます。
また、アニメーションや操作フローなどのインタラクションもプロトタイプ化できます。スライダーやノブを追加して、狙っている体験を微調整していくのに適しています。
プロンプト例 / Example prompt:
新しい決済ボタンのプロトタイプを作りたいです。クリックするとアニメーションを再生し、すぐに紫色へ変化する挙動としてください。複数のスライダーとオプションを備えたHTMLを作って、異なる設定を試せるようにし、設定が良かったときは値をコピーできるボタンを追加してください。
この用途に使う / Use this for:
- デザインシステム資産の作成 / Creating design system artifacts
- コンポーネントの調整 / Adjusting components
- コンポーネントライブラリの可視化 / Visualizing component libraries
- アニメーションのプロトタイピング / Prototyping animations
4. レポート、調査、学習 / Reports, Research, and Learning
Claude Codeは複数ソースの情報を集約し、読みやすいレポートへ変換するのが得意です。Slack、コードベース、Git履歴、必要に応じてWeb上の情報を検索対象にして、可読性の高いレポート生成を依頼できます。
長文のHTMLドキュメント、対話型の解説ページ、さらにはスライドデッキとしてまとめることも可能です。図示にはSVGを多用するように指示すると、理解しやすさが格段に上がります。
プロンプト例 / Example prompt:
レートリミッターが実際にどう動いているか理解できません。関連コードを読んで、1枚のHTML解説ページを作ってください。トークンバケット方式のフローダイアグラム、重要なコードスニペットを3〜4個注釈付きで含め、ページ下部に「注意点（Gotchas）」セクションを置いてください。初見で1回読めば理解できるように最適化してください。
この用途に使う / Use this for:
- 機能サマリー作成 / Writing feature summaries
- 解説記事の作成 / Generating explainers
- 週次ステータスレポートの作成 / Drafting weekly status reports
- インシデントレポートの作成 / Creating incident reports
- SVGの図解・フローチャート・技術図の作成 / Producing SVG illustrations, flowcharts, and technical diagrams
5. カスタム編集インターフェース / Custom Editing Interfaces
テキスト入力だけで意図を伝えるのが難しい場面は珍しくありません。この場合、私は目的に合わせて使い捨ての編集画面を作るよう依頼します。これは製品や再利用可能ツールではなく、特定のデータ1件に最適化された単一HTMLファイルです。
ポイントは最後に「export」への導線を設けることです。たとえば「JSONとしてコピー」「プロンプトとしてコピー」ボタンを用意して、UI上で行った編集結果を再びClaude Codeへ貼り付けられる形に戻せるようにします。ループの中に居続けながら、より密な反復が可能になる、というわけです。
プロンプト例 / Example prompts:
この30件のLinearチケットを優先度再調整したいです。Now / Next / Later / Cutの4列にまたがるドラッグ可能なカード形式のHTMLを作ってください。まずあなたの予測で並び替えておいてください。最後に「Markdownとしてコピー」ボタンを追加し、各バケットごとに1行の理由も付けて最終順序をエクスポートできるようにしてください。
こちらが機能フラグの設定です。フォームベースのエディタを作成し、領域ごとにフラグをグループ化し、依存関係を可視化してください。依存元が無効のまま別のフラグを有効化しようとすると警告を出してください。最後に「差分をコピー」ボタンを追加し、変更されたキーだけを出力できるようにしてください。
このシステムプロンプトを調整しています。左右分割のエディタを作ってください。左側に編集可能なプロンプトを置き、変数欄をハイライトする。右側にサンプル入力を3件用意し、左側編集と同時に即時反映されるテンプレートレンダリングを表示する。文字数とトークン数カウンタ、コピー用ボタンも追加してください。
この用途に使う / Use this for:
- 再並び替え、トリアージ、分類 / Reordering, triaging, or bucketing anything
- 構造化設定の編集 / Editing structured config
- リアルタイムプレビュー付きのプロンプト/テンプレート調整 / Tuning prompts and templates with live preview
- データセットの選別 / Curating datasets
- 文書・文字起こし・差分への注釈付け / Annotating documents, transcripts, or diffs
- 文章だけでは表現しづらい値の選定 / Picking values painful to express in text
よくある質問
以下は、私がHTML運用について聞かれることが最も多い質問と、それに対する日々の実践的な回答です。
これだとTokenを無駄に使わないですか？
Q: より非効率ではないでしょうか？
Markdownのほうがトークン効率が良い場面が多いのは事実です。しかし、HTMLの表現力の高さと、実際に私が読み進められる確率の向上を考えると、結果としては全体の品質が上がります。Opus 4.7の1MMコンテキストウィンドウでは、追加トークン量はコンテキスト枠から見ればほとんど気にならないレベルです。
それでもMarkdownは使うの？
Q: 現在、いつMarkdownを使いますか？
率直に言って、ほぼすべての場面でMarkdownはやめています。とはいえ、私がHTML志向の「極端派」に寄りすぎている面は自覚しています。
生成したHTMLファイルはどう見るの？
Q: 生成されたHTMLはどこで見ればよいですか？
普段はローカルでブラウザを開いて確認します（Claudeに開かせることも可能です）。リンクで共有したい場合は、S3にアップロードして共有します。
HTMLの方がMarkdownより時間がかかりませんか？
Q: HTML生成はMarkdownより遅くならないのですか？
はい、そうです。HTMLの生成はMarkdownの2〜4倍かかることがあります。ただし私の検証では、その待ち時間を上回る価値がある品質が出てきます。
バージョン管理はどうしていますか？
Q: バージョン管理は大丈夫？
正直なところ、これがHTMLの最大の痛点です。Markdownに比べてHTMLの差分はVCS上で非常に乱雑になりやすく、コードレビューが難しくなりがちです。
計画文書は置き換えられますか？
Q: これで計画は置き換えているのですか？
私は1つの単一計画の代わりに、計画の各パートやフェーズごとに複数のHTMLを持つ形にしています。たとえば最初に実装計画のHTML、次にUI探索のHTML、最後に設計案を一覧化したHTMLコンポーネントを作るといった具合です。これらのHTMLは将来の参照用として保存し、検証時にも活用しています。
HTMLを見栄えよく出させるには？
Q: Claudeに見栄えの良いページを出させるには？
Claudeの組み込みフロントエンド設計機能でも、かなり整ったHTMLを生成できます。会社のブランドに合わせた仕上がりを求める場合は、まずコードベースをスキャンしてデザインシステムのHTMLを作らせ、基準ファイルとして渡すと良いです。そうすれば他のHTML作成時にも一貫したトーンとスタイルを維持しやすくなります。
5. Claudeとの協調を維持するには / Staying in the Loop with Claude
以上のポイントをまとめると、私がMarkdownの代わりにHTMLを選ぶ本質的な理由は、Claudeとの協業で「自分がループ内にいる感覚」を保ちやすいからです。Claudeが担う範囲が広がるにつれ、私は計画を以前よりも深く読めなくなっていたのです。作業を単に委譲して終わりではなく、意思決定の流れに引き続き関わりたい。HTMLが、そのための最適解になりました。今は以前よりはるかに密接に、コラボレーションのループに参加できていると感じます。
*本記事の元著者はThariq Shihipar（Anthropic Claude Code エンジニアリング責任者）であり、意見とHTML志向の運用実践は本人の個人的見解を反映しています。*
*本記事はAnthropicのClaude Codeエンジニアリング責任者であるThariq Shihipar氏による執筆であり、HTMLファイルを用いたClaude Code運用への個人的な見解と選好を示しています。*
参考情報
Share