はじめに
サーバーワークスの池田です。
Anthropic（クロードを開発している会社）の Claude Code チームに所属する Thariq Shihipar 氏が、2026 年 5 月 20 日に Using Claude Code: The Unreasonable Effectiveness of HTML を公開しました。
「人に渡す成果物は Markdown ではなく HTML で出力させた方がよい」という主張です。記事に併せて、20 個のスタンドアロン HTML サンプルを集めた公式ギャラリー thariqs/html-effectiveness も公開されています。
本記事ではまず公式記事の主張を整理し、そのあと公式ギャラリーから 4 デモをブラウザで開いて中身を見ていきます。HTML を自分で書いたり Claude Code で生成したりはしておらず、Anthropic が公開している .html をそのまま開いただけです。インタラクティブな操作（展開・並び替え）も今回は触っていません。
この記事で分かること
- Anthropic がなぜ Markdown ではなく HTML を推しているのか
- 公式ギャラリー thariqs/html-effectiveness の全体像と利用方法
- 実装計画・PR レビュー・PR 説明書・モジュールマップの 4 デモをブラウザで開いて確認した結果
Anthropic が提示する Markdown から HTML への転換
公式記事の冒頭で著者は「ほぼ全部 Markdown を使うのをやめた」と書いています。Claude Code に何かを出力させるとき、初期設定の Markdown ではなく HTML を要求するようになった、という宣言です。
著者は自分が「HTML マキシマリスト寄り」だと認めつつ、Markdown が抱える根本的な制約として、100 行を超えたあたりから可読性が急激に落ちることを指摘しています。
公式記事では HTML が Markdown に勝つ理由として、次の 5 点が挙げられています。
| # | 観点 | HTML の優位性 |
|---|---|---|
| 1 | 情報密度 | 表・SVG 図・CSS スタイル・JavaScript・空間配置をひとつのファイルに収められる |
| 2 | 可読性 | 100 行を超える内容を見出し・カード・タブで構造化でき、破綻しにくい |
| 3 | 共有のしやすさ | ブラウザがネイティブに描画するため、リンク 1 本で共有できる |
| 4 | 双方向性 | スライダー・トグル・ドラッグ操作などを差し込み、読者側で調整できる |
| 5 | Claude Code との相性 | ファイルシステム・MCP・git 履歴を取り込んで、データ反映済みの HTML を生成できる |
HTML を使う場面と Markdown を残す場面
公式記事は「すべてを HTML にせよ」とは言っていません。読み手によって使い分ける、というスタンスです。
| 用途 | おすすめ | 理由 |
|---|---|---|
| 人に渡す監査・レポート・計画書・ダッシュボード | HTML | 視覚的に消化される必要があり、リンク共有が前提 |
| 100 行を超える長文ドキュメント | HTML | Markdown では構造が破綻する |
| 比較・スライダー・ダッシュボードを含む成果物 | HTML | 双方向操作が必要 |
| Google Docs に貼り付けるような中身 | HTML | そもそも表示先がリッチテキストを想定している |
| エージェント間で受け渡すデータ | Markdown | 機械可読性とトークン効率を優先 |
| git 管理下のリポジトリ内ドキュメント | Markdown | diff が読める形式が望ましい |
| 短い出力・エンジニアリングループ内のメモ | Markdown | HTML のオーバーヘッドが見合わない |
公式記事はこの線引きを「人に渡すかどうか」で割り切る発想を提示しています。
公式ギャラリー thariqs/html-effectiveness の構成
公式記事と同時に公開されたリポジトリには、Claude Code が生成した 20 個の HTML ファイルが置かれています。ビルド不要・依存ゼロで、.html をブラウザで開くだけで動作します。ライセンスは Apache 2.0 です。
ファイルは 9 カテゴリに分類されています。
| カテゴリ | デモ数 | 代表例 |
|---|---|---|
| 探索・計画 | 3 | コードアプローチ比較、ビジュアル設計方向、実装計画 |
| コードレビュー・理解 | 3 | 注釈付き PR diff、PR 説明書、モジュールマップ |
| デザインシステム | 2 | デザイントークン一覧、コンポーネント変種シート |
| プロトタイピング | 2 | アニメーションサンドボックス、クリッカブルフロー |
| 図解・ダイアグラム | 2 | SVG 図解シート、フローチャート |
| プレゼンデッキ | 1 | 矢印キー操作のスライドデッキ |
| リサーチ・学習 | 2 | 機能説明、概念説明 |
| レポート | 2 | 週次ステータスレポート、インシデントタイムライン |
| カスタム編集 UI | 3 | トリアージボード、機能フラグエディタ、プロンプトチューナー |
著者はこれらを「マークダウンの壁の代わりに、実際に読むドキュメント」と表現しています。
ここからは、エンジニアが業務でよく扱う 4 種類のデモをブラウザで開いて、HTML 化したときの見え方を見ていきます。対象は実装計画・注釈付き PR diff・PR 説明書・モジュールマップです。残り 16 本も同じ要領で開いて確認できます。
実装計画を HTML で表現するとこうなる
最初に開いたのは 16-implementation-plan.html です。「Comment threads on task cards」というタスクカード上のコメントスレッド機能を追加する、という架空の実装計画が描かれています。実際に開くと、こういう見た目になります。
上部に Effort・Surfaces touched・New tables・Feature flag が並び、下にマイルストーンとデータフロー図が続いています
冒頭の概要カードには、4 つのサマリー指標が並んでいます。
- Effort: 約 2 週間
- Surfaces touched: 3 packages
- New tables: 2
- Feature flag:
task_comments_v1
その下に「Milestones」セクションが続き、Week 1 から Week 2 にかけての作業が時系列で並びます。各マイルストーンには、変更対象のパッケージ名がタグ形式で添えられています。
さらに下には「Data flow」セクションがあり、<CommentComposer> から各サービスへのリクエスト経路がフロー図として描かれています。コメントを書き込む・他クライアントへブロードキャストする・通知ワーカーに渡す、という流れが矢印で示されています。
Markdown で同じ内容を書く場合、サマリー指標は箇条書きに、データフローは ASCII 図かリンク先の画像に分離されます。HTML 化することで、サマリー・タイムライン・データフローが「同じ画面でスクロールせずに俯瞰できる」状態になっているのが体験上の差分です。
PR レビューを HTML 1 枚にまとめるとこうなる
次に開いたのは 03-code-review-pr.html です。「Add optimistic updates to task list mutations」というタスクリストに楽観的更新（optimistic update：UI 側を先に変更し、サーバー応答を待たずに画面を進める手法）を導入する PR のレビュー結果が、HTML として 1 枚にまとめられています。実際こんな感じです。
PR の概要・Risk map・ファイル単位の diff・コメント注釈が縦に並んでいます
最上部には PR の概要として「What this PR does」セクションがあり、変更内容の意図が 3 行で要約されています。続く「Risk map」セクションでは、変更ファイルが影響度の高い順に並べられています。
その下から「Files」セクションが始まり、ファイルごとの diff が表示されます。注目すべきは、diff の中にインラインコメント（吹き出し風の枠）が直接埋め込まれている点です。「Blocking」「Nit」のような重大度タグが付き、コメントの根拠が「コードの該当行のすぐ下」に示されています。
GitHub の標準 PR 画面では、コメントは画面右側のサイドバーやコメントタブに散らばります。HTML 化された PR レビューでは、コメントが「該当 diff の直後」に挿入されているため、画面遷移なしで指摘内容と該当コードを行き来できます。コードレビュー結果を社外の関係者に共有する場面では、この形式の方が文脈を保ったまま渡せます。
PR 説明書を HTML で渡すとこうなる
3 つ目は 17-pr-writeup.html です。タイトルは「#312 ─ Move notification delivery onto a queue」で、通知配信をキュー経由に移行する PR の「読み方ガイド」になっています。開くとこんな画面が出てきます。
右側にWhy/File-by-file/Walkthrough/Where to focus/Test plan/Rolloutのサイドナビが配置され、左本文には変更理由と各ファイル解説が並んでいます
画面右側には縦長のサイドナビが固定表示されており、「Why」「File-by-file」「Walkthrough」「Where to focus」「Test plan」「Rollout」というセクションが並んでいます。読者は気になる節へ即座にジャンプできます。
「Why」セクションには、レビュアー宛のメッセージとして「通知配信がリクエスト経路でインラインに実行されており、負荷時に変更レイテンシに 200〜800 ms が加算される」「SMTP プールが枯渇するとメール送信がサイレントにドロップしていた」という背景が書かれています。さらに「Before / After」の対比カードが並び、変更前の構造と変更後の構造を視覚的に対比しています。
「File-by-file」セクションでは、ファイル名がコレクションのカード形式で並びます。各カードを展開すると、そのファイルの変更内容と関連するコードスニペットが現れます。コードブロックには配色シンタックスハイライトが適用されており、ターミナルで PR を見るのとほぼ同じ感覚です。
「コードを読む順序」が固定された 1 ファイルなので、レビュー後に共有資料として残しやすい構造になっています。リリースノートや障害ポストモーテムと近い使い方ができます。
認証フローを HTML 1 枚で説明するとこうなる
最後に開いたのは 04-code-understanding.html です。「How authentication flows through the codebase」というタイトルで、Acme という架空サービスの認証フローが、リクエスト経路・コード片・ファイル一覧の組み合わせで解説されています。実物はこんな感じです。
リクエストパス図・Callstack walkthrough・サイドの Key files と Gotchas パネルが組み合わせられています
最上部には「Request path」セクションがあり、ブラウザから /auth/callback を経て verifyToken() まで到達する経路が SVG 図で描かれています。Postgres と Sessions Service の関係も同じ図に含まれており、認証のリクエストがどのコンポーネントを通過するかが一目で分かります。
その下の「Callstack walkthrough」セクションは、番号付きのステップ解説です。各ステップにはコード片が貼られており、src/app/providers/AuthProvider.tsx のフックが何を呼び、src/middleware/auth.ts がどう動くか、という流れがコードと文章で交互に示されます。
右側には固定サイドバーがあり、「Key files」と「Gotchas」の 2 つの情報パネルが並びます。「Key files」では src/middleware/auth.ts や src/server/routes/session.ts などの重要ファイルへのリンク、「Gotchas」では将来注意すべきポイントがまとめられています。
新規参画者に「この機能はどこをどう読めばいいか」を渡す資料として、Markdown の箇条書きや独立した図ファイルよりも、こうした 1 枚の HTML の方が効率的に情報を伝えられます。
公式記事によると、Claude Code に HTML を生成させる際の特別なセットアップは不要で、プロンプトに「make an HTML file」「make an HTML artifact」と書くだけで始められるとされています。繰り返し使うパターンができてきた段階で、.claude/skills/ 配下にテンプレートとしてまとめる、という育て方が想定されています。
まとめ
公式ブログと公式ギャラリーが提示しているのは、「Claude Code の出力を Markdown 一辺倒から HTML へずらすことで、人に渡す成果物の情報密度と共有しやすさを上げられる」という考え方です。
実装計画・PR レビュー・PR 説明書・モジュールマップの 4 デモをブラウザで開くと、Markdown では平坦になっていた情報が、空間配置・サイドナビ・SVG 図によって構造化されていることが見て取れます。
公式ギャラリーは依存ゼロのスタンドアロン HTML として配布されています。記事を読むより、.html ファイルを 1 つ手元で開いてみるのが理解への最短経路だと考えられます。
参照リンク
- Using Claude Code: The Unreasonable Effectiveness of HTML（公式ブログ）
- thariqs/html-effectiveness（公式 GitHub リポジトリ）
