Claude Code の Markdown を HTML/XML に置き換えるべきか
Simon Willison の「HTML 再評価」論、Anthropic 公式の XML タグ推奨、Claude Code 内部の Markdown 実装。3 つの主張は矛盾するのか。トークン効率・パース精度・表現力の三軸で整理し、用途別の使い分け判断軸を提示します。
TL;DR
- トークン効率: 同一データで Markdown は JSON の約半分のトークン（Webmaster Ramos 2026-04 実測: JSON 15,879 / Markdown 7,814）。HTML/XML はタグオーバーヘッドで Markdown より重くなります。
- モデル感受性: Claude Opus 4.6 / Sonnet 4.6 はフォーマット非感受性（5 フォーマットで 100% 同一の回答）。Haiku 4.5 のみ精度差（最大 36 パーセントポイント）が出ます。
- 公式推奨: Anthropic は XML タグを推奨 していますが、これは「境界明示」目的であり「全体 XML 化」ではありません。
- 結論: Markdown 廃止は性急です。境界面で XML タグ、本文で Markdown のハイブリッド戦略が妥当だと私は考えます。
要点サマリ表
| 観点 | Markdown | HTML | XML タグ |
|---|---|---|---|
| トークン相対コスト | 軽い（基準） | 重いと推定（未実測・要検証） | 中〜重い（タグ密度依存・推定） |
| パース精度（Opus/Sonnet 4.6） | 影響なし（実測） | 影響なし（推定・要検証） | 影響なし（推定・要検証） |
| 表現力 | 限定的（テキスト中心） | 高い（SVG・対話的 UI） | 中（構造化 XML） |
| Claude 親和性 | 高い（学習データ豊富） | 中 | 高い（RLHF 由来の境界認識） |
背景・経緯
2024 年から 2025 年にかけて、LLM プロンプトのデフォルト形式として Markdown 一強の時代 が続きました。CLAUDE.md 文化が広まり、各社の AI コーディングツールも Markdown ベースの設定ファイルを採用しています。可読性・編集容易性・学習データの豊富さが揃った Markdown は、事実上の標準として定着しています。
そこに 2026 年 5 月 8 日、Simon Willison が 「The Unreasonable Effectiveness of HTML」 を公開しました。大規模コンテキスト窓口の時代に、SVG や対話的ナビゲーションを含む HTML の表現力を再評価すべき という主張です。これは「トークン効率より表現力」を提起する論で、Markdown 中心の現状に一石を投じました。
同時期に、Anthropic 公式の prompt-engineering best practices ページが XML タグ推奨を強化 しました。一方、dbreunig が 2026-04-04 に解析した Claude Code 内部実装は、依然として Markdown ベースの動的アセンブリ（110+ 条件分岐）です。公式推奨と自社実装の方向がねじれて見える状態です。
このねじれをどう読むのか。「Markdown を HTML/XML に置き換えるべきか」という問いに、トークン効率・パース精度・表現力の三軸 で正面から答えるのが本記事の問題設定です。
本題の詳細
トークン経済学：実測ベンチマークが示す Markdown の優位
Webmaster Ramos が 2026 年 4 月に公開した実測ベンチマークが、最も明快な数字を提供しています。同一の 200 商品カタログ を Claude API に送ると、JSON は 15,879 トークン、Markdown は 7,814 トークン でした。つまり JSON は Markdown の 約 2 倍 のトークンを消費します。
HTML / XML はさらにタグオーバーヘッドが重く、開始タグと終了タグの対が常に必要になります。<item>...</item> のような構造を 200 件分繰り返すと、データ本体よりタグの方が嵩む状況が容易に発生します。Markdown のリスト記号「-」1 文字と比較すれば、その重量差は明らかです。ただし HTML / XML の具体的トークン数は実測ではなく、タグ構造からの推定です（要検証）。
「200k トークン窓口があるから細かい差は無視できる」という反論はよく聞きます。しかし エージェントループや多ターン会話では累積コスト が効きます。同じシステムプロンプトが毎ターン再評価されるワークロードで、フォーマット選択は API 料金に直結します。
フォーマット感受性は Haiku のみ：Opus/Sonnet 4.6 の意外な事実
同じ Webmaster Ramos ベンチで、もう一つ重要な発見が報告されています。Claude Opus 4.6 と Sonnet 4.6 は 5 フォーマット（JSON / YAML / Markdown / Plain / TOON）で 100% 同一の回答 を返したのです。フォーマットが上位モデルの推論結果に影響を与えなかった、という実証です。なお、本ベンチの対象は JSON / YAML / Markdown / Plain / TOON の 5 種に限定されており、HTML / XML への一般化は別途検証が必要です（要検証）。
一方で Haiku 4.5 のみ精度差 が出ました。フォーマットによって最大 36 パーセントポイント の精度差が観測され、YAML が階層構造、JSON が依存関係を扱うタスクに向くという傾向が示されました。軽量モデルほどフォーマットの構造的ヒントに依存する、と読めます。
この結果は「Markdown では精度が落ちる」というよくある誤解を覆します。少なくとも Opus / Sonnet 4.6 を使う限り、Markdown を選んでも精度面のペナルティはありません。「フォーマット選択は精度よりコストの問題」だと整理し直す必要があります。
Haiku を使うワークロードでは話が変わります。階層構造の入力なら YAML、依存関係の入力なら JSON、という使い分けが推奨されます。なお、Webmaster Ramos のベンチには XML / HTML は含まれていません（要検証）。HTML/XML での Haiku の挙動は別途検証が必要です。
Anthropic 公式の XML 推奨は「境界明示」であって「全体 XML 化」ではない
Anthropic 公式の prompt-engineering best practices ページで推奨されている XML タグは、`<instructions>` `<example>` `<context>` `<thinking>` といった限定的なタグです。これらは セクション間の境界を明示する 目的で使われます。
たとえば「ここからが指示」「ここからが例」「ここからが入力データ」の境目を明示することで、Claude がプロンプトを誤って混同するリスクを減らせます。RLHF（人間のフィードバックによる強化学習）の過程で、Claude はこれらの XML タグを境界記号として強く学習している、と公式は説明しています。
重要なのは、本文の中身（指示文・例文・データそのもの）まで XML 化することは推奨されていない 点です。公式が想定する典型形は「<instructions> で囲んだ Markdown 本文」であって、「ネスト構造で完全に XML 化されたツリー」ではありません。タグはあくまで境界記号です。
この区別を理解しないと、Anthropic 公式の推奨を「全体 XML 化推奨」と読み違えてしまいます。Anthropic 公式の推奨内容は記事公開時点（2026-05-11）のものです。継続更新されるため、最新版は原典確認をお願いします（要検証）。
Claude Code が Markdown を選んだ理由：人間が編集する前提
dbreunig が 2026-04-04 に公開した解析によれば、Claude Code のシステムプロンプトは Markdown ベースで 110+ 条件分岐の動的アセンブリ という構造を取っています。プロジェクト種別、Git 状態、ツール有効化状況など、多数の条件で部分テンプレートが組み合わされてシステムプロンプトが生成されます。
これだけの分岐数を XML / HTML で書くと、保守不能になります。タグの開閉対応、ネスト深度の管理、エディタでの差分レビューの困難さ、すべてが指数的に悪化します。Markdown なら 1 行 1 トピックの素直な記述で済み、条件分岐部分も if-then の素朴な構造で書けます。
ユーザー側の CLAUDE.md 文化も同じ前提に立っています。ユーザーが自分で書いて編集する設定ファイルは、Markdown であることが事実上の必須条件です。XML や HTML を手書きで保守する負荷を、ユーザーに強いることは現実的ではありません。
ここから導かれる原則は明快です。編集容易性は実装可能性の必要条件 であり、人間が読み書きする境界面では Markdown が有利です。Anthropic は内部実装ではこの判断を取り、ベストプラクティスでは境界記号として XML タグを推奨する、という二段構えの設計をしています。dbreunig 解析は 2026-04-04 時点のものであり、本記事公開後の Claude Code 更新は未反映です（要検証）。
比較・代替手法
4 つのフォーマット候補を トークン相対コスト・パース精度・人間可読性・Claude 親和性・推奨用途 の観点で並べると、選択の優劣が明確になります。Opus / Sonnet 4.6 を前提とすると、精度軸は同点となり、コストと可読性で勝負が決まる構図です。
| フォーマット | トークン相対コスト | パース精度 (Opus/Sonnet 4.6) | 人間可読性 | Claude 親和性 | 推奨用途 |
|---|---|---|---|---|---|
| Markdown | 軽い（基準） | 影響なし | 高い | 高い | 本文・指示文・CLAUDE.md |
| プレーン HTML | 重いと推定（未実測・要検証） | 影響なし（推定・要検証） | 中（タグが混じる） | 中 | SVG・対話的 UI が必要な場合のみ |
| XML タグ（軽量） | 中（タグ密度依存・推定） | 影響なし（推定・要検証） | 中 | 高い | セクション境界の明示・複数入力の区切り |
| フル XHTML 構造化 | 最重と推定（要検証） | 影響なし（推定・要検証） | 低い | 中 | ほぼ非推奨（コスト見合わない） |
この表から読み取れる方針は単純です。本文は Markdown、境界は XML タグ、HTML はピンポイント という三層使い分けが、コスト効率と表現力のバランスを最も良く取ります。フル XHTML 構造化は、保守コストとトークンコストの両面で割に合わないため、原則として選択肢から外せます。
私の考察
私は、Claude Code の Markdown を HTML / XML に全面置換する必要はないと考えています。ただし、境界面では XML タグを積極採用すべき です。つまりハイブリッド戦略を推奨します。3 つの根拠でこの判断を支えます。
第一の根拠は、Claude Code 自身が Markdown を選んだ事実 です。110+ 条件分岐の動的アセンブリを XML / HTML で実装したら保守不能になる、という現実的判断が背景にあります。編集容易性は実装可能性の必要条件 であり、人間が書く設定ファイルや動的に組み立てるプロンプトでは Markdown が圧倒的に有利です。第二の根拠は、Anthropic の XML 推奨が「タグによる境界明示」であって「全体 XML 化」ではないという公式ドキュメントの精読結果です。境界記号としての XML タグと、本文フォーマットとしての Markdown は 同居可能 であり、矛盾しません。
第三の根拠は、Webmaster Ramos の実測です。Opus / Sonnet 4.6 ではフォーマットが精度に影響しない ため、選択軸は実質的にコストと可読性に絞られます。ここで「コスト軸」はトークン消費量、「可読性軸」は学習データ親和性と編集容易性、と定義します。Markdown はコスト軸で実測 2 倍の優位、可読性軸でも CLAUDE.md 文化と豊富な学習データという二点で優位なので、両軸で Markdown を選ばない理由がありません。Haiku を使う場合のみ別途検討が必要です。私のテイクアウェイは次の二層構造です。「構造的に厳格にしたい境界（システム / ユーザー / ツール結果のセクション区切り）は XML タグで囲み、内容そのものは Markdown で書く」。Simon Willison の HTML 再評価論は表現力という別の観点を提起していますが、それは「SVG や対話的 UI が必要なピンポイント用途」に限定して使えば十分です。読者の皆様も、自分のプロンプトでこの二層構造を実践してみることをおすすめします。
参考リンク
- The Unreasonable Effectiveness of HTML — Simon Willison, 2026-05-08
- Prompting best practices (Use XML Tags to Structure Prompts) — Anthropic 公式
- How Claude Code Builds a System Prompt — dbreunig, 2026-04-04
- Claude API Format Benchmark: YAML vs JSON vs Markdown vs TOON — Webmaster Ramos
- 5 Claude Code Skills That Cut Token Costs by Up to 70% — Benchmarked — MindStudio, 2026-05-01