2026年5月7日、私は「AIエージェント10種の正体は.mdファイルだった」を公開した。 Anthropic 金融エージェント10種の GitHub リポジトリを全部解剖し、「正体は.md ファイル集だ」と論じた記事だ。
その翌日。Anthropic の Claude Code エンジニアリングリードである Thariq Shihipar が X で 「HTML が AI 成果物の新デフォルト」 と提唱した。16時間で 440万view・8,200 likes・15,700 bookmarks。AI業界が一斉に「Markdown の時代は終わった」と騒いだ。
私の記事と、Thariq の主張。一見、完全に矛盾している。
だが結論を先に書く。両者は矛盾しない。レイヤーが違うだけだ。AIエージェント設計者にとって本当に必要なのは「.md か HTML か」の二択ではなく、3つのレイヤーで考えることだ。本記事ではこの3レイヤー設計を、Anthropic 公式情報と私自身の panda-hq での6つの実例で示す。
答えを先に：3レイヤーで考える
AIエージェントの周辺で動くテキストには、3つのレイヤーがある。
| レイヤー | 推奨フォーマット | 根拠 | 例 |
|---|---|---|---|
| A. エージェント定義・スキル | Markdown (.md) | SKILL.md 公式推奨。機械可読+人間可読の最適解 | .claude/agents/*.md、SKILL.md、CLAUDE.md |
| B. 中間生成物・エージェント間ループ | Markdown | トークン4-8倍効率、git friendly、ML親和性 | リサーチノート、要件定義、GitHub Issue |
| C. 最終成果物（人間が読む） | HTML | レイアウト・スタイル・インタラクティブ。Anthropic内部の新デフォルト | レポート、ダッシュボード、ブログ挿絵、スライド |
これだけ覚えて帰ってもらえれば、本記事の80%は達成だ。残りはこの3レイヤーを「なぜそうなのか」「どう実装するか」で具体化する。
A レイヤー：エージェント定義は今も Markdown
私が直前記事で書いた「.mdが正体」は、このレイヤーの話だ。
Anthropic 公式の anthropics/skills リポジトリで規定されている SKILL.md フォーマットは、Markdown + YAML frontmatter の構造を採用している。Anthropic は公式ドキュメントで 「SKILL.md は機械可読+人間可読の最適バランスとして Markdown を意図的に選択した」 と明言している。
これは Thariq の HTML 推奨が出た後も変わっていない。SKILL.md フォーマットの公式仕様は依然 Markdown だ。
panda-hq の A レイヤー実例
私の会社では、AI社員（ずんべぇ・すいっぺ・あざらす・うぉんば）の定義を .claude/agents/*.md に置いている。
例1: .claude/agents/script-writer.md
YMM4 動画用の台本を書くエージェント定義。name description の YAML frontmatter + Markdown 本文で、キャラ設定・口調ルール・ファイル所有権を記述している。Claude Code がセッション起動時にこれを読み、必要な時にこのエージェントを呼び出す。HTML にする理由がない。エージェントが「読む」だけだからだ。
例2: .claude/skills/skill_manage_calendar.md
Google Calendar 操作のスキル定義。MCP 接続情報・予定 CRUD の手順・HitL ゲート（create/update/delete は承認必須）を Markdown で書いている。エージェントから呼び出される時、Claude はこの Markdown をそのまま読んで実行する。
A レイヤーの本質は、「テキストはエージェントが消費する」 こと。人間が読むのは「設計時」と「デバッグ時」だけ。Markdown で十分どころか、最適だ。
B レイヤー：中間生成物も Markdown
エージェントが動く過程で生まれる中間ファイル——リサーチノート、要件定義、Issue、プロンプトのテンプレート——これも Markdown が圧倒的に強い。
理由はシンプルだ。トークンコストが HTML の1/4〜1/8。Cloudflare の解析では、同じ内容のドキュメントを HTML から Markdown に変換すると 約80%のトークン削減になる。1,000語のドキュメントが、Markdown 250トークン vs HTML 1,500トークン。
エージェント間でファイルを引き渡したり、コンテキストに大量のドキュメントを積む B レイヤーでは、このコスト差が累積する。私がSaaS開発1人体制で 4,000ターン超の Claude Code を回した時、Bレイヤーが HTML だったら API コストが破綻していた。
panda-hq の B レイヤー実例
例1: business/research/2026-05-26-fde-japan-4companies.md
今朝公開した FDE 記事を書く時、リサーチ素材をこのファイルに 250 行近く書き溜めた。比較表・差別化インサイト・SEO キーワード・Sources 全件——すべて Markdown。これを /pmbok-b2-write が読み込んで企画書に変換する。ここで HTML を使う合理的理由はゼロ。表は Markdown の | 記法で十分、編集も diff も git friendly。
例2: GitHub Issue 駆動の開発フロー
SaaS開発で 1機能 = 1 Issue の粒度に分解し、Claude Code に投げる運用をしている。Issue 本文は Markdown 一択。GitHub がネイティブにレンダリングし、Slack 通知でもそのまま読める。
B レイヤーは「エージェントと人間が交互に触る」場所だ。git で diff が読めること、ターミナルで grep できること、トークンが軽いこと——これらの要件を全部満たすのは Markdown だけだ。
C レイヤー：最終成果物は HTML
ここからが Thariq の主張する領域だ。人間が「読んで判断する」最終成果物——プラン、レビュー、レポート、ダッシュボード、監査結果——これは HTML が圧倒的に強い。
Thariq が示した HTML の4つの優位性を整理する。
- 情報密度 — テーブル / SVG / CSS / JavaScript / 画像を1ファイルに埋め込める。Markdown では不可能
- 可読性閾値 — 100行を超えると Markdown は事実上読めなくなる。HTML は折りたたみ・タブ・ナビで対応可能
- 共有効率 — HTML はブラウザで即レンダリング。Markdown はエディタが必要で、ステークホルダーが読まない
- インタラクティブ性 — スライダー・トグル・ボタンで「ユーザー操作 = 次のプロンプト」になる探索ツール化
Thariq 本人の 20 件 head-to-head 比較では、HTML が 17 件で勝利したとのこと。Anthropic 内部の Claude Code チームは既に HTML を新デフォルトとして採用している。
panda-hq の C レイヤー実例
例1: ブログ挿絵 HTML → PNG（今朝、本記事の前段で実証済み）
今朝公開した FDE 記事で、私は挿絵 4 枚を book/figures/blog/fde-three-paths-japan-4companies-*.html として HTML で書き、Puppeteer で PNG 化した。共通 CSS（book/figures/common/figure.css）には --accent --sub --success といったデザイントークン、.fig-card .compare-container といったコンポーネントクラスが定義されている。
この記事の挿絵 4 枚も、同じ仕組みで生成している。Markdown では絶対に作れない図表が、HTML なら制御可能だ。これは Thariq の言う「情報密度」「視覚的表現」の典型例だ。
例2: YMM4 動画スライド HTML → PNG
書籍 PMBOK-AI の動画版（CH01-04 公開済み）で、スライド18 枚を book/video/chXX/slides/*.html として作成している。1920×1080 のキャンバスに、CSS Grid と Flex でレイアウト、step アニメーション用に data-step 属性を使う。最終出力は PNG 18 枚 × 章数。
動画素材も「人間が見る最終成果物」だ。だから HTML で作る。Markdown で書いたら、デザインの自由度が崩壊する。
C レイヤーでも Markdown が残る6シナリオ
ただし、C レイヤーが常に HTML 一択ではない。Thariq 本人が「Markdown を残すべき」と挙げた 6 シナリオを引用する。
- Repository ドキュメント（GitHub/GitLab がネイティブにレンダリングし、検索インデックスにも乗る）
- Slack / Discord スニペット（code-fence の汎用性）
- ML training データ（学習データのパターン親和性）
- Git 中心ワークフロー（line-by-line blame の明確性）
- 個人ノート（単独著者・編集頻度高）
- RSS / Email newsletter（クライアントレンダリング不安定性）
ブログ記事の本文（このMDXを含む）も、実質「リポジトリドキュメント」の特性が強い。だから本文は Markdown のままで、挿絵だけ HTML→PNG が最適解になる。
「C レイヤーは HTML」と言っても、機械的な置き換えではない。「人間が一度限り読んで判断する深いコンテンツ」が HTML、「継続的にバージョン管理する文書」は Markdown という線引きが本質だ。
エージェント設計者への実践指針
AIエージェント設計者・SKILL.md 作者向けに、3レイヤー設計のチェックリストをまとめる。
A レイヤー設計時
- SKILL.md フォーマット（YAML frontmatter + Markdown body）に準拠する
- エージェント定義は短く、責務を1つに絞る
- HitL ゲート（破壊的操作の承認）を Markdown 内に明文化する
- HTML 化の誘惑に負けない（人間ではなくエージェントが読むため）
B レイヤー設計時
- エージェント間で引き渡すドキュメントは Markdown 統一
- git で diff が読める粒度に分割する
- トークン消費を意識し、不要な装飾を避ける
- 中間生成物には日付プレフィックスをつけて履歴化する（私の
business/research/YYYY-MM-DD-*.md流儀）
C レイヤー設計時
- 「誰が、いつ、どの場面で読むか」を最初に決める
- 一度限りの判断材料なら HTML、継続管理なら Markdown を選ぶ
- HTML 化する場合、デザイントークン（CSS variables）を統一する
- PNG 化する場合、Puppeteer などで自動化する
- トークンコストの増加を見越して、生成頻度を最適化する
全体設計
- 3レイヤーを混在させない（A の中に C のスタイルを混ぜると保守が崩れる）
- レイヤー間の境界（Markdown→HTML 変換ポイント）を明示する
- レイヤーごとに別ディレクトリで管理する（私の
.claude//business//book/figures/がそれ）
まとめ：論争ではなく補完
ここまでをまとめる。
- Anthropic の Thariq が提唱する「HTML が AI 成果物の新デフォルト」は事実
- だが SKILL.md は依然 Markdown 公式推奨で、変わっていない
- 両者は矛盾しない。3レイヤー（A定義 / B中間 / C成果物）で切り分ければ整合する
- A と B は Markdown、C は HTML（ただし C にも Markdown が残る6例外あり）
- AIエージェント設計者は、3レイヤーを意識して設計すれば、Anthropic の主張も自分の運用も両立できる
私が直前に書いた「.mdが正体」記事は A レイヤーの話で、Thariq の主張は C レイヤーの話だ。同じ Anthropic から出てきた2つのメッセージは、対立ではなく、設計レイヤーの違いとして読むのが正しい。
panda-hq では、.claude/agents/*.md（A）、business/research/*.md（B）、book/figures/blog/*.html → PNG（C）の3層を厳格に分けて運用している。本記事の挿絵 4 枚も、Thariq が言う通り HTML で作って PNG にした。論争を経た上での、最も Anthropic 公式な答えがこれだ。
「.md か HTML か」で迷ったら、自分が今書いているのはどのレイヤーかを問え。答えは自然に出る。
関連記事
- AIエージェント10種の正体は.mdファイルだった｜Anthropic金融リポジトリを全解剖 — 本記事の前提となる直前記事（A レイヤー解剖）
- FDEは3つの道がある — 日本企業4社が始めたAI実装組織を完全比較 — 本記事の挿絵生成パイプラインを実証した最新記事
- PMBOK-AIとは？従来PMBOKとの違い・5つの柱・導入ステップを徹底解説 — エージェント設計の全体フレーム
- Claude Code Agent Teams の実践ガイド — A レイヤーの実装パターン
- Claude Code 2026 PMガイド — Claude Code 利用者の運用設計
SKILL.md 設計・AIエージェント設計のご相談はお問い合わせからお気軽にどうぞ。