ライブコーディングでHTML・Markdown・JSONを使い分けるベストプラクティス

結論は、一つのフォーマットに統一しないことです。2026年時点の実務では、読む主体と責務ごとにフォーマットを分けるほうが、ライブコーディングの再現性と生産性が上がります。

• Markdown: AIや共同開発者に渡す仕様、議事録、プロンプト、永続メモリ
• HTML: 人間が最終的に読むレビュー資料、デモ、レポート、プレゼン
• JSON + JSON Schema: API入出力、状態、設定値、機械間の契約
• YAML: 人手で触る front matter や宣言的設定
• JSX/TSX: 状態とイベントを持つ、実際に動くインタラクティブUI

つまり「Markdown が死んだ」のではありません。Markdown は制御面、HTML は提示面、JSON Schema は契約面に寄ったと捉えるのが正確です。Claude の Artifacts は Markdown文書、単一HTMLサイト、図、Interactive React components を同じ成果物群として扱います。一方、Claude Code の永続メモリは CLAUDE.md、VS Code の custom instructions も Markdown ファイルを前提にしています。

なお、2026年5月11日時点で、Anthropic 公式に「HTML と Markdown の使い分け」を単独で体系化した設計文書は確認できませんでした。HTML の実務的優位は、Claude Artifacts / Cowork live artifacts の一次情報と、Claude Code チームの Thariq Shihipar 氏による HTML examples からの運用知見として扱うのが安全です。

まず判断表

フォーマット選定は、見た目の好みではなく 認知負荷、編集負荷、検証可能性 で決めます。

Markdown は制御面に残す

CommonMark は Markdown を、構造化文書を書くための plain text format と位置づけています。VS Code も Markdown preview、同期スクロール、KaTeX、preview security などを標準支援しています。さらに、Claude Code は CLAUDE.md をプロジェクトメモリとして読み、VS Code の Copilot custom instructions も .md ファイルを前提にします。

したがって、次のものは Markdown に残すのが自然です。

• CLAUDE.md、AGENTS.md、.github/copilot-instructions.md
• 設計メモ、仕様メモ、議事録
• AIエージェントに渡す実装方針
• レビュー前の下書き
• 人間が直接編集するチェックリスト

Markdown の強みは、最終表示力ではなく、人間が読めるソースであり続けることです。ライブ中に方針を変える、差分を見る、会話後に人間が直す、という場面では HTML より強いです。

AI指示ファイルの設計は、こちらも合わせて読むと位置づけが分かりやすいです。

• AIエージェント向け指示書・メモリ設計の実務テンプレート
• Claude Code と Codex の違い: 実務導入で見るべきポイント

HTML は提示面に強い

人間が最終的に読む成果物は、HTML に寄せる価値があります。HTML は見出し、main、nav、section、figure、table などのセマンティック要素を持ち、ブラウザでそのまま開けます。Claude Artifacts も、単一ページHTMLサイトや Interactive React components を成果物の代表例として扱っています。

特にライブコーディングでは、HTML が次の場面で効きます。

• PRレビューを、差分、注釈、重要度、ジャンプリンク付きで見せる
• 設計案を、複数カラム、色、図、比較表で並べる
• スライドを、1つのHTMLファイルとして矢印キーで進める
• 調査レポートを、目次、折りたたみ、図、表で読ませる
• 小さなプロトタイプを、ブラウザだけで触れる状態にする

Thariq Shihipar 氏の examples gallery は、この方向の具体例として参考になります。ただし、HTML は Markdown より差分が騒がしく、手で編集しにくいことがあります。生成物として読むHTML と 編集・合意形成に使うMarkdown を混ぜないのがコツです。

JSON は契約、YAML は人手設定

JSON は表示形式ではありません。RFC 8259 は JSON を軽量、テキストベース、言語非依存のデータ交換形式として定義しています。ライブコーディングで JSON が効くのは、UIそのものではなく、壊れてよい範囲を決める契約として使うときです。

JSON Schema を足すと、次を同じ定義から扱えます。

• VS Code の補完とバリデーション
• CI の入力検証
• フォーム生成
• LLM structured output の受け口
• 設定ファイルの必須項目と制約

YAML は front matter や宣言的設定に向きます。人間には読みやすい一方、空白感度、暗黙変換、アンカー、タグなどで事故りやすい形式でもあります。外部APIやツール間の境界は strict JSON、人手編集の設定層だけ YAML、という分け方が安全です。

VS Code の jsonc は設定ファイル向けには便利ですが、外部に渡すデータ契約では通常の JSON に戻します。

JSX/TSX は動くUIの本体

JSX/TSX は「HTMLっぽい記法」ではなく、UI、状態、イベント、型検査を同じ単位で扱うための形式です。React は JSX を JavaScript ファイルの中に HTML-like markup を書く構文として説明し、TypeScript は JSX/TSX の型検査と変換を支援します。

判断基準は単純です。

• レイアウトや説明だけなら HTML
• クリック、入力、状態、再利用部品が増えたら TSX
• データ物語化や小さな可視化なら Observable Framework
• 実アプリに入れる前の説明資料なら Markdown + 小さなコード断片

静的なHTMLプロトタイプを、理由なく React 化し続ける必要はありません。状態管理が必要になった時点で TSX に上げるほうが、編集負荷と実装負荷のバランスが取れます。

ユースケース別の推奨

実務の原則は、更新と確認のループを短くすることです。CodePen Live View は別ウィンドウや別デバイスへライブ更新を流せます。Debug View は iframe を外してブラウザデバッグを単純化します。Observable Framework は参照しているセルだけを再実行し、invalidation でイベントループやリスナーの掃除を促します。

同じカウンターを4形式で見る

同じ「カウンター」でも、責務によって書き方は変わります。

HTML: そのまま動く成果物

<button id="counter" aria-live="polite">Count: 0</button>
<script>
  let count = 0;
  const button = document.getElementById("counter");

  button.addEventListener("click", () => {
    count += 1;
    button.textContent = `Count: ${count}`;
  });
</script>

単一HTMLデモやプレゼン向けです。ブラウザだけで動き、セマンティクスやアクセシビリティ属性も直接持てます。

Markdown拡張: 説明と実演を同居

Observable Framework のように Markdown 内へ HTML と JavaScript を混在できる環境では、説明文と小さな実演を同じページに置けます。

# Counter demo

説明文は Markdown で書く。

<button id="counter">Count: <span id="value">0</span></button>

```js
let count = 0;
const btn = document.querySelector("#counter");
const value = document.querySelector("#value");

btn.addEventListener("click", () => {
  count += 1;
  value.textContent = String(count);
});
```

JSON Schema: 状態の契約

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/counter.json",
  "type": "object",
  "properties": {
    "label": { "type": "string", "default": "Count" },
    "count": { "type": "integer", "minimum": 0, "default": 0 },
    "step": { "type": "integer", "minimum": 1, "default": 1 }
  },
  "required": ["count"],
  "additionalProperties": false
}

これはUIではありません。フォーム、バリデーション、CI、エディタ補完に効く契約です。

TSX: 状態付きUI

import { useState } from "react";

export function Counter() {
  const [count, setCount] = useState<number>(0);

  return (
    <button aria-live="polite" onClick={() => setCount((c) => c + 1)}>
      Count: {count}
    </button>
  );
}

動くUIを育てるなら、状態、イベント、部品化、型検査を一緒に扱える TSX が最も強いです。

移行手順

既存プロジェクトでは、全部をHTMLに変えるのではなく、出力物を四層に棚卸しします。

1. Markdown層を標準化する
   指示、仕様、議事録、レビューコメント、CLAUDE.md、AGENTS.md を Markdown に集約します。CommonMark または GFM のサブセットに寄せ、レンダラ依存の記法を増やしすぎないようにします。

2. JSON Schemaを用意する
   API入出力、設定、状態オブジェクトに schema を付けます。VS Code の補完とCIの検証で同じ schema を使うと、ライブ中の入力ミスを早く潰せます。

3. YAMLは設定層に限定する
   front matter や人手編集の宣言的設定に使います。複雑なタグや暗黙変換に依存しないよう、schema で縛ります。

4. 人間向け成果物だけHTML化する
   長い比較表、設計レビュー、調査報告、プレゼンを HTML artifact にします。HTMLは「読ませる成果物」であり、「全員が手で直すソース」ではありません。

5. 状態が増えたらTSXへ上げる
   UIがイベント、フォーム、状態遷移を持ち始めたら、HTML断片から TSX コンポーネントへ移します。

セキュリティとアクセシビリティ

HTML と Markdown の raw HTML を同じ感覚で扱うと危険です。CommonMark には raw HTML があり、React の dangerouslySetInnerHTML は名前の通り XSS リスクを伴います。未信頼入力から生成した HTML や raw HTML を含む Markdown を、そのまま公開面に流してはいけません。

最低限の原則は次の通りです。

• 不特定入力から生成した HTML はサニタイズする
• dangerouslySetInnerHTML は最後の手段にする
• CSP は XSS 防御の一部として設定する
• Markdown preview の security 設定をむやみに下げない
• JSON Schema validation は品質対策であり、XSS対策そのものではない
• 最終HTMLでは main、nav、見出し階層、table、figure、aria-* を確認する

Markdown だけでは、最終的な見出し階層や表の意味づけはレンダラに依存します。長い学習資料、社内報告、研究メモを HTML 化するなら、最後にセマンティック要素を見直す価値があります。

まとめ

ライブコーディングの現在のベストプラクティスは、フォーマット統一ではなく 責務分離 です。

Markdown にすべてを閉じ込めると、最終成果物の可読性とナビゲーションが落ちます。HTML/TSX にすべてを上げると、編集負荷と差分ノイズが増えます。JSON/YAML に寄せすぎると、人間の認知負荷が上がります。

一番壊れにくい組み合わせは、説明は Markdown、提示は HTML、契約は JSON Schema、実装は TSX です。

参考リンク

• Claude Help Center: Artifacts
• Claude Help Center: Live artifacts in Claude Cowork
• Anthropic Docs: Manage Claude’s memory
• VS Code: Use custom instructions
• CommonMark
• RFC 8259 JSON
• YAML 1.2.2 Specification
• JSON Schema: Getting Started
• VS Code: Markdown
• VS Code: JSON
• CodePen: Live View
• CodePen: Debug View
• Observable Framework: Markdown
• Observable Framework: Data loaders
• Observable Framework: Reactivity
• Observable Framework: JSX
• React: Writing Markup with JSX
• TypeScript Handbook: JSX
• The unreasonable effectiveness of HTML examples