Claude Code と HTML Artifacts の不合理な有効性

Markdown は agent との協働の第一段階を制しました。理由は単純です。

生成しやすく、diff しやすく、pull request に貼りやすく、ほとんどのメモには十分でした。そのため coding agents の自然なデフォルトになりました。計画、要約、仕様、レビュー notes、インシデント記録、実装チェックリストは、どれも Markdown になっていきました。

Anthropic の最新 Claude Code 記事は、このデフォルトが限界を見せ始めていると論じています。

主張は Markdown が悪いということではありません。Claude Code は今や長いテキストファイルを書く以上のことができ、HTML はその作業により良い表面を与える、ということです。より高い情報密度、より明確な視覚構造、共有しやすい artifacts、軽いインタラクションを持てます。

これは開発者にとって実用的な変化です。Claude Code に何を作らせるべきかを変えます。

中心となる考え方

公式記事で、Claude Code チームの Thariq Shihipar は、多くの Claude Code 出力で Markdown より HTML ファイルを好むようになった理由を説明しています。

理由は明快です。Claude Code がより大きなタスクを担うほど、出力も大きくなるからです。

30 行の Markdown checklist は問題ありません。300 行の実装計画、調査レポート、コードレビュー、アーキテクチャ説明、UI 探索は、技術的に render できるからといって読みやすいわけではありません。

HTML は Claude Code に、同じ情報を整理するためのより広い余地を与えます。

• 密度の高い比較には table
• 視覚的な階層には CSS
• 図には SVG
• 参照には画像
• ローカル操作には JavaScript
• ナビゲーションには tabs と sections
• 生成された prompts、JSON、diff、設定をコピーする buttons

これにより HTML は単なる文書形式ではなく、一時的な workbench に近くなります。

agent workflows にとって、この違いは重要です。

Claude Code ユーザーにとって重要な理由

Claude Code は通常のチャット UI とは違います。ローカル project を読み、git history を調べ、file を操作し、MCP servers を使い、実際の engineering work が行われる同じ workspace 内で artifacts を生成できます。

つまり、実際の context から有用な HTML artifacts を作るのに非常に向いています。

たとえば、次のように頼む代わりに：

Write a plan for refactoring the billing module.

次のように頼めます：

Create an HTML artifact that explains the billing refactor.
Include a module map, the key file changes, risks by severity,
a staged migration plan, and a copyable implementation prompt.

この 2 つの prompts の本質的な要求は同じかもしれません。しかし 2 つ目は、確認しやすく、共有しやすく、後の Claude Code session で参照しやすい形式を求めています。

これが本当の利点です。HTML は一度きりの回答ではなく、持続する project context になれます。

HTML が Markdown に勝る 4 つの場面

1. 仕様と計画

計画は、Markdown が最初に苦しくなる場所です。

長い実装計画には、architecture、code snippets、dependencies、diagrams、tradeoffs、screenshots、open questions が混在しがちです。Markdown はそれらを保持できますが、読者の navigation は助けません。

HTML なら Claude Code は計画をよりレビューしやすい表面に分割できます。

• 冒頭の overview
• system の flow diagram
• file ごとの change map
• risk table
• staged rollout plan
• unanswered questions
• copyable follow-up prompts

これは、計画が session をまたいで残る必要がある場合に特に有用です。将来の agent は HTML file を context として読め、人間は文字の壁を読まずに scan できます。

2. コードレビューと理解

コードレビューは単なる text ではありません。構造です。

良い review には、diff、severity labels、affected modules、call paths、data flow、なぜ重要なのかの短い説明が必要になることがよくあります。Markdown でも近似できますが、HTML なら直接 render できます。

Claude Code では、次のような workflow が考えられます。

Review this PR by creating an HTML artifact.
Show the diff with inline annotations, group findings by severity,
and include a small diagram of the streaming/backpressure path.

これにより review output は、より interactive な review packet に近くなります。一時的なものでも、他の engineer に渡しやすくなります。

3. デザインとプロトタイプ

出力に視覚要素や interaction がある場合、HTML は Claude Code の自然なターゲットです。

本番 app が React、Swift、Kotlin などであっても、HTML は layout を素早く sketch し、方向性を比較し、motion を試し、UI parameters を調整する手段になります。

元記事では sliders、knobs、copy buttons が有用な primitives として挙げられています。これは正しい mental model です。Claude Code は、文章で説明しにくい値を選ぶための使い捨て interface を作れます。

• color palettes
• easing curves
• component density
• crop regions
• prompt variants
• feature flag combinations
• ticket priorities

重要なのは export です。良い HTML artifact は、JSON として copy、Markdown として copy、prompt として copy、または diff を copy できるような有用な出力で終わるべきです。

artifact が engineering workflow に出力を戻せないなら、それはただの demo です。

4. レポート、調査、学習

Claude Code は codebase、git history、docs、MCP 経由の Slack、MCP 経由の Linear、web sources を横断して統合できます。Markdown はその context を要約できますが、HTML はそれを読みやすくできます。

社内説明、incident reviews、weekly status、dependency audits、onboarding guides では、HTML が関係性を説明するだけでなく見せるための視覚的余白をモデルに与えます。

ここで HTML は学習形式になります。

• annotated code snippets
• system diagrams
• glossary callouts
• timeline views
• risk matrices
• decision tables

結果は polished product である必要はありません。誰かが実際に使う程度に読みやすければ十分です。

隠れたポイント：HTML は人間を loop に残す

Anthropic の記事で最も強い部分は、format の議論ではありません。workflow の議論です。

Claude Code がより大きなタスクを扱うほど、開発者は agent が出したものを読む量が減る危険があります。長い Markdown plans は、深くレビューせずに承認されがちです。これは危険です。そこには弱い assumptions、抜けた edge cases、開発者なら選ばなかった changes が含まれているかもしれません。

HTML はこの failure mode を減らせます。人間により良い操作点を与えるからです。

• overview を scan する
• diagram を inspect する
• options を side by side で compare する
• risks に jump する
• slider を tweak する
• selected output を Claude Code に copy back する

これは review の必要性をなくしません。review が起きやすくなります。

真剣な agent workflows では、これは見た目の問題ではありません。control の一部です。

Markdown がまだ適している場面

HTML はあらゆる場所で Markdown を置き換えるべきではありません。

artifact が次を必要とする場合、Markdown の方がまだ適しています。

• 小さい
• diff しやすい
• 人が頻繁に手で編集する
• README に埋め込む
• issue や PR description に貼る
• Markdown を期待する tooling に処理される

実用的なルールは単純です。

出力が主に text で、人間が編集するものなら Markdown を使う。

layout、diagrams、dense comparison、interactivity、より良い reading experience が必要なら HTML を使う。

これにより HTML がまた別の過剰な default になるのを防げます。

シンプルな prompt pattern

Claude Code で試すなら、直接的な prompt から始めます。

Create a single HTML artifact for this task.
It should be readable in a browser, self-contained, and optimized for review.
Use tables, diagrams, and sections where useful.
Add copy buttons for any output I may want to paste back into Claude Code.
Keep all source references visible.

次に目的を具体化します。

For this refactor, include:
- a dependency map
- the proposed file changes
- migration steps
- risks by severity
- test plan
- open questions

時間が経てば、繰り返し現れる patterns は skills や templates になるべきです。しかし最初の一歩に infrastructure は不要です。Claude Code により良い artifact を求める習慣だけで十分です。

チームが次にやるべきこと

短期的な機会は、社内 doc system 全体を HTML 中心に作り直すことではありません。

有用な動きはもっと狭いものです。

1. チームが実際には読んでいない Claude Code outputs を特定する。
2. そのうち 1 つを HTML artifact に変換する。
3. artifact が workflow に戻せる有用なものを export することを求める。
4. 将来の sessions に役立つなら repo に残す。
5. 1 つの decision にしか役立たなかったなら削除する。

最後の点は重要です。多くの HTML artifacts は disposable であるべきです。その価値は、人間が今より良い decision をする助けになることです。

最後のまとめ

HTML の不合理な有効性は、Markdown より優れた markup language であることにあるのではありません。

Claude Code により豊かな collaboration surface を与えることにあります。

小さな notes には Markdown が今でも正しい道具です。しかし specs、code reviews、architecture explainers、design explorations、research reports、custom editing interfaces では、HTML は agent output をより読みやすく、共有しやすく、行動につなげやすくできます。

Claude Code がより大きな作業単位を扱えるようになるほど、出力形式は workflow design の一部になります。artifacts を first-class review surfaces として扱うチームは、Markdown の壁を承認し続けるチームよりも control を保ちやすくなります。

Source

• Claude blog: Using Claude Code: The unreasonable effectiveness of HTML
  https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html