FIELD GUIDE

Using Claude Code: The unreasonable effectiveness of HTML

Markdownは軽くて編集しやすい。しかし、エージェントが長い仕様、レビュー、可視化、操作UIまで作るようになると、読まれる成果物としてはHTMLのほうが強い場面が増える。

Markdownが詰まるところ

元記事の出発点は、Markdownが悪いという話ではない。Markdownはシンプルで、編集しやすく、エージェントとのやり取りに十分使える。ただし、100行を超える計画書、複数案の比較、図解、色、インタラクション、共有まで含めると、読み手側の負荷が急に上がる。

Claude CodeチームのThariq Shihiparは、作業成果物を人間が直接編集する機会が減り、むしろ仕様や参照資料として読むことが増えたと述べている。その前提では、Markdownの「編集しやすい」という長所より、HTMLの「視覚的に構造化できる」「ブラウザでそのまま共有できる」という長所が勝つ。

HTML artifact example showing dense information layout — 元画像: Claudeブログのクリッピング。HTMLは、プレーンなMarkdownより多くの視覚情報を整理して見せられる。

情報量

表、CSS、SVG、画像、コード、canvas、簡単な操作UIまで同じファイルにまとめられる。

見通し

タブ、図、リンク、レスポンシブレイアウトで、長い仕様や計画を読み進めやすくできる。

アップロードすればURLで共有できる。添付Markdownより、相手が開いて読む確率を上げやすい。

操作

スライダー、つまみ、ドラッグ、コピー用出力を持つ、その課題専用の小さな編集環境にできる。

使い分けの判断軸

Markdownで足りるのは、短く、線形に読めて、人間が直接編集する可能性が高い文書だ。HTMLを選ぶべきなのは、読み手が全体像をつかむために「配置」「比較」「強調」「操作」の助けを必要とするときである。

出力したいもの	Markdownで十分	HTMLにする価値が高い
計画・仕様	短い作業手順、単一案のメモ	複数案の比較、データフロー、画面モック、レビュー観点を一枚で見たい
コード理解	小さな差分の要約	diff、注釈、モジュール図、重要コード片を同時に追いたい
デザイン検討	文章で伝わる軽い方向性	レイアウト、色、アニメーション、操作感を試したい
構造化データ編集	数行のJSONやYAML	優先度付け、タグ付け、承認・却下、設定変更をUIで行い、最後に差分をコピーしたい

実用上の目安はシンプルだ。読むだけでなく、比べる、選ぶ、調整する、誰かに読ませる、のどれかが入ったらHTML artifactを検討する。

具体的な使いどころ

元記事が挙げるユースケースは、単なる見た目の豪華化ではなく、エージェントの作業結果を人間が検査しやすくするためのものだ。特にClaude Codeでは、ローカルファイル、MCP、ブラウザ、git履歴などの文脈を読み込めるため、HTMLはそれらを再構成する表示面として機能する。

文脈

コード、Slack、Linear、ブラウザ、git履歴、ローカルメモなどをClaude Codeに読ませる。

成果物

読み手が判断しやすいHTMLとして、図、表、注釈、プロトタイプ、編集UIに変換する。

仕様、計画、探索

実装前の探索では、複数案を横並びで比較するHTML、UIモックを含む実装計画、検証者が読む前提の計画書が向いている。単一のMarkdown planより、段階ごとのHTML群を参照資料として残す使い方が紹介されている。

コードレビューと理解

レビューでは、差分、重要なコード片、深刻度つきの指摘、フロー図を一体化できる。ストリーミングやバックプレッシャーのような、読むだけでは追いづらい概念を説明する場面で特に効果がある。

デザインと試作

HTMLは最終実装言語がReactやSwiftであっても、試作面として使える。ボタンのアニメーション、デザインシステムの一覧、コンポーネント調整用のスライダーなど、見るだけでなく触って決める成果物に向いている。

レポート、調査、学習

複数データソースの調査レポート、週次報告、インシデント整理、技術解説は、長い文章より図表と要約の配置で読みやすくなる。元記事では、レートリミッターの理解用にトークンバケット図、コード片、注意点を一枚にまとめる例が挙げられている。

専用の編集画面

テキストで説明しづらい調整作業には、そのデータ専用の使い捨てエディタを作る。Linearチケットの並べ替え、feature flagの編集、 prompt templateの調整、データセットの選別などが例だ。重要なのは、最後にJSON、Markdown、diff、promptとして持ち帰れる export を用意すること。

人間がループに残るためのHTML

記事の核心は、HTMLがMarkdownよりリッチだから、ではない。エージェントがより大きな仕事を受け持つほど、人間が計画や判断を読まずに流してしまう危険が増える。HTMLは、その判断過程に戻ってくるための表示形式になる。

だから最初から大きな仕組みを作る必要はない。まずはClaude Codeに「HTML file」や「HTML artifact」と頼み、その成果物が何を助けるべきかを明確にする。繰り返し使う型が見えてきたら、スキルやテンプレートとして固めればよい。

再利用しやすい依頼の形

Read the relevant files and create a single HTML artifact for review.
Optimize it for a person making a decision once.
Include the comparison, the key evidence, and an export or next-action section when useful.

原文: Using Claude Code: The unreasonable effectiveness of HTML。併せて、記事内では HTML file templates and examples と GitHub gallery も紹介されている。