Claude CodeにHTMLを読ませるとトークンが溶ける

AIエージェントの出力を、全部HTMLに寄せる必要はありません。

HTMLは人間が読むためには強い形式です。

ですが、AIが処理し、引き継ぎ、再利用する前提ならMarkdownで十分です。

見出し画像はAIで生成しました。
プロンプトはこの記事に掲載中。

結論：HTMLは人間ファースト、MarkdownはAIファースト

HTML出力を鵜呑みにしてはいけません。

HTMLが優れている場面はあります。

見た目の整理、比較、共有、操作UIには向いています。

ただし、AIエージェントの仕事全体を考えると、HTMLは常用形式ではありません。

理由は単純です。

• トークン消費が増える

• タグ、class、CSS、JavaScriptがノイズになる

• diffが読みにくい

• 再入力時の処理コストが高い

• エージェント間の受け渡しに向かない

AIファーストで考えるなら、まずMarkdownです。

目次

• 結論：HTMLは人間ファースト、MarkdownはAIファースト

• HTML推しの主張で見落とされていること

• AIが扱いやすい形式には条件がある

• HTMLが有効な場面

• Markdownで十分な場面

• 私の運用ルール

• そのまま使える判断テンプレ

• まとめ

【先着100名限定】Claude Codeデザインパターン
〜フォルダ構造・Skills・database・コンテンツ生成フロー全公開〜

HTML推しの主張で見落とされていること

HTML推しの主張は「人間が読まない問題」への解決策です。

そこは正しいです。

100行を超えるMarkdownの仕様書は、ほとんど読まれません。

HTMLなら、タブ、図解、色、比較レイアウト、ボタン、スライダーまで使えます。

つまり、HTMLの強みは「人間の理解補助」です。

一方で、AIファーストの観点では別問題です。

AIにとって重要なのは、見た目ではありません。

重要なのは次の4つです。

• 構造が明確

• ノイズが少ない

• 差分が追いやすい

• 次のAIへ渡しやすい

この条件なら、Markdown、JSON、YAMLの方が強いです。

HTMLは表示形式として優秀です。処理形式として常に優秀ではありません。

AIが扱いやすい形式には条件がある

AIファーストの形式は、見栄えより再利用性で決めます。

Claude CodeやCodexに作業を渡す時、必要なのは装飾ではありません。

タスク、制約、判断基準、変更対象、完了条件です。

たとえば実装計画なら、次の形式で十分です。

## Goal
- 目的

## Scope
- 変更対象
- 変更しない対象

## Constraints
- 技術制約
- UI制約
- テスト制約

## Steps
1. 調査
2. 実装
3. 検証

## Done
- 完了条件

この形式は軽いです。

AIが読んでも、人間が読んでも、git diffでも追えます。

HTMLにすると、同じ内容でも周辺コードが増えます。CSS、レイアウト、装飾、scriptタグが増えます。

人間には見やすくなります。AIには余計な情報が増えます。

HTMLが有効な場面

HTMLは使うべき場面があります。

特に「人間の意思決定」が入る場面です。

HTMLが向くのは次の5つです。

• 複数案の比較

• デザインモック

• PR説明

• 経営報告

• 操作できる一時編集UI

たとえば、オンボーディング画面を6案比較するならHTMLが向いています。

Markdownで6案を文章説明されても判断しにくいです。HTMLなら横並びにできます。密度、印象、導線、情報量を一目で比較できます。

PR説明も同じです。

複雑なdiff、処理フロー、リスク箇所、レビュー観点はHTMLで見せる価値があります。

ただし、これは「人間が判断するためのビュー」です。

AIが次に読む一次データではありません。

Markdownで十分な場面

AIが処理するだけなら、Markdownで十分です。

むしろMarkdownの方が向いています。

Markdownで十分な場面は次の6つです。

• 実装計画

• 作業ログ

• 引き継ぎメモ

• エージェントへの指示書

• チェックリスト

• 仕様の一次メモ

さらに厳密な処理が必要なら、JSONかYAMLです。

例です。

task:
  goal: "HTML出力の常用ルールを見直す"
  default_format: "markdown"
  use_html_when:
    - "visual comparison"
    - "interactive review"
    - "executive report"
  avoid_html_when:
    - "agent handoff"
    - "small plan"
    - "source of truth"

AIに渡すなら、こういう構造の方が強いです。

HTML化は最後で十分です。

私の運用ルール

出力形式は、用途で分けるべきです。

私なら、こう運用します。

• AI内部処理: Markdown / JSON / YAML

• エージェント間引き継ぎ: Markdown

• 人間レビュー: HTML

• デザイン比較: HTML

• 経営・顧客向け共有: HTML

• 長期保存する仕様: Markdown

• 操作UIが必要な一時ツール: HTML

重要なのは、HTMLを否定することではありません。

HTMLを「常用形式」にしないことです。

HTMLは強いです。だからこそ、使いどころを絞るべきです。

そのまま使える判断テンプレ

Claude CodeやCodexに頼む時は、最初にこの判断基準を入れると安定します。

出力形式は用途で選んでください。

- AIが次に処理する一次資料ならMarkdown
- 厳密な構造化データならJSONまたはYAML
- 人間が比較、レビュー、共有する成果物ならHTML
- 操作できる一時UIが必要な場合だけHTML

HTMLを使う場合も、同じ内容の要約Markdownを最後に付けてください。

HTMLが必要な時も、Markdown要約を残すのが実務では強いです。

人間はHTMLで読みます。

AIはMarkdownで次に進めます。

この二層構造が一番コストパフォーマンスが高いです。

まとめ

HTMLは便利です。

ただし、AIファーストではありません。

AIファーストで見るべき指標は、見た目ではなく処理効率です。

• 読みやすさ

• トークン効率

• 差分管理

• 再利用性

• エージェント間引き継ぎ

この5つで見ると、Markdownはまだ強いです。

結論です。

HTMLは「人間が読むためのビュー」。

Markdownは「AIが動くための作業形式」。

全部HTMLにする必要はありません。

AIファーストなら、まずMarkdownで十分です。

【先着100名限定】Claude Codeデザインパターン
〜フォルダ構造・Skills・database・コンテンツ生成フロー全公開〜

AI、デザイン、キャリアの個別相談はこちら

法人研修の無料相談・お問い合わせこちら

最大8名のグループコンサル

noteメンバーシップに参加すると800本以上の記事が読み放題です。

書籍「AIでゼロからデザイン」好評発売中

NewsPicks「実践！仕事術」

さらば森田のAI〇〇ラボ

ベイジTV（株式会社ベイジ 公式チャンネル）

San Francisco Design Talk（btrax Brandon氏のPodcast）

参照:
https://thariqs.github.io/html-effectiveness/

#AI #生成AI #AIエージェント #AI時代 #AI活用 #AI人材 #AI研修 #AIツール #Claude #ClaudeCode #Codex #Gemini