アフェリエイト広告

MD・XML・HTML、結局どれで書くべきか ― AI駆動開発の「フォーマット三つ巴」に答えを出す

AI駆動開発
アフェリエイト広告

エディタを乗り換えても、何かが足りなかった

ここ数年、AI駆動開発の話題はずっと「どのエディタを使うか」だった。

VS Code + Copilot で始まり、Cursor に乗り換え、最近は Claude Code や Codex のようなターミナル常駐型エージェントに手を出す。私自身もこの流れをひと通り追ってきた。

世代代表ツール思想
第1世代VS Code + CopilotAIが補助する開発
第2世代CursorAI中心に再設計したIDE
第3世代Claude Code / Codex / OpenHands / HermesAIに任せ、人間が監督する開発

世代が進むほど、コードを書くのはAIの仕事になっていく。優秀さの定義も「速くコードを書く人」から「良い仕様を書く人」へ移った。

そして、いくつものツールを触っているうちに、だんだん妙な確信が芽生えてきた。

本当の勝負は「エディタ」ではなく、「人間が書く設計書・知識をどう残すか」で決まっているのではないか。

人間の主戦場がコードから設計書・知識へ移ったなら、まず向き合うべきはエディタ選びではない。その設計書を、どのフォーマットで書くか ― だ。

まず、設計書はMarkdownで書く

結論を先に言うと、私が設計書を書くフォーマットはMarkdown（MD）だ。理由は単純で、人間が書きやすく、読みやすいから。

# FX分析システム
## 要件
- MT5連携
- ドル円監視
## 制約
- Python

見出し・箇条書き・リンクが直感的で、構造が頭にすっと入る。しかもプレーンテキストだから、5年後に開いても壊れない。特別なアプリに依存しない。

AI時代の「良い設計書」は、実はかなりフォーマットが定まってきている。README一枚で済ませていた時代から、いまは PRD（要件定義）・ADR（設計判断記録）・AGENTS.md（AI指示書） をMarkdownで揃える運用が当たり前になった。「良いプロンプトを書く」より「良い設計書を書く」方向へ、上級開発者ほど寄っている。

設計書は、そのまま「AIへのコンテキスト」になる

Markdownで設計書を書く本当の旨味は、ここから先にある。

第3世代のエージェント（Claude Code、Codex など）は、コードだけでなくこちらが書いた文書を読んで動く。つまり、人間向けに書いた設計書が、そっくりそのまま AIへのコンテキスト（文脈） になる。

設計書（Markdown）= 人間が読む資料
              ↓ そのまま
            AIが読む文脈

ここで効くのが、LLMがそもそもMarkdownで学習されているという事実だ。だから .md のフォルダをエージェントに指すだけで、変換レイヤーもパース処理もなしにそのまま理解される。「人間用」と「AI用」を二重管理しなくていい。一つ書けば、両方に効く。

そしてObsidianが「文脈の源（source of truth）」になる

この発想と最高に相性がいいのが Obsidian だ。

2026年の知識管理で起きている最大の変化は、新しいアプリの登場ではない。AIエージェントがあなたのノートを直接読めるようになったことだ。MCP（Model Context Protocol）経由で Claude Code などが Obsidian Vault に直結し、書きためたノート群がまるごとAIの文脈になる。

設計の合言葉は 「一つの真実、多数のエージェント入口（one source of truth, many agent entry points）」。知識を一度Markdownにコンパイルしておけば、Obsidianは人間の閲覧役、LLMはその保守役として、同じファイルを共有できる。Andrej Karpathy が提唱した “LLM Wiki” パターンも、まさにこの系譜だ。

私が「Obsidianの価値はむしろこれから上がる」と思う理由はここにある。コードはAIが書く。知識は人間がMarkdownで管理する。 その器として、.md フォルダほど強い置き場所はない。

さらに、Markdownは「安い」

実利の話もしておきたい。設計書を毎回AIに読ませるなら、無視できないのがトークン効率＝コストだ。

各種の計測では、同じ内容でも Markdown は HTML より最大10倍トークンが少ない。Cloudflareの分析では約80%削減、実際のWebページからの変換では最大87%削減という数字も出ている。(Save / searchcans)

設計書を読ませるたびにこの差が効く。トークンが少なければ、コストが下がり、レビューも速く、文脈枠も食い潰さない。人間が書きやすく、AIがそのまま読め、しかも安い ― 設計書の土台としてMarkdownを選ばない理由が、正直見当たらない。

ところが ― 「理解しやすさ」を突き詰めると話が分かれる

ここまでなら「Markdown一強」で終わる。ところが2026年、議論はもう一歩踏み込んでいる。きっかけは、「理解しやすさ」を2つの軸に分けて考え始めたことだ。

  • AIにとっての理解しやすさ → 構造が曖昧だと、AIは「どれが要件で、どれが制約か」を推測する。明示したい。
  • 人間にとっての理解しやすさ → 最終的に人が読む成果物は、ただのテキストより、見た目が整っている方がいい。

この2軸で見たとき、Markdownの弱点を補う候補として浮かび上がってきたのが XML と HTML だ。

XML ― AIに「構造」を明示する

<project>
  <goal>FX取引支援システムを作る</goal>
  <requirements>
    <requirement>MT5からデータ取得</requirement>
  </requirements>
  <constraints>Python使用</constraints>
</project>

何がどの役割の情報なのかが一目瞭然。実際 Claude は元々XMLタグを解釈するよう設計されており、プロンプト内でセクションの境界を曖昧さなく区切る用途では今もXMLが推奨されている。Anthropic社内ですらタグ名のレジストリを共有しているという。(Claude Docs / kindatechnical)

弱点は、人間が手で書くには冗長で、スマホ入力がつらいこと。

HTML ― 人間に「見せる」成果物

<h1>FX分析システム</h1>
<h2>要件</h2>
<ul>
  <li>MT5連携</li>
  <li>通知機能</li>
</ul>

HTMLは本来「ブラウザで見せるための言語」だ。面白いのは、Markdownを変換すると、ほぼこのHTMLになること（MDはHTMLの簡易記法とも言える）。そして2026年5月、Karpathy が「LLMの回答はHTMLで構造化させるとよい」と発言、Anthropic の Claude Code チーム（Thariq Shihipar）も「AI生成出力のデフォルトをMarkdownからHTMLへ」と打ち出した。コンテキストが100万トークン級になり「節約のためのMarkdown」という制約が薄れたことが背景にある。(beam.ai / Tarik Davis)

3フォーマットを真正面から比較する

「理解しやすさ」を軸に3者を並べると、得手不得手がはっきりする。

観点MarkdownXMLHTML
人間が読む◎△○
人間が書く（スマホ含む）◎△△
Obsidian相性◎○△
AIが構造を理解○◎○
プロンプト内の境界明示△◎○
トークン効率（コスト）◎△✕
最終成果物・表示△✕◎
バージョン管理（差分）◎○△

きれいに役割が割れている。人間の可読性・執筆性・コストはMarkdown、AIへの構造明示はXML、見せる成果物はHTML ― それぞれ別の土俵で強い。

答え ― 3フォーマットは「競合」ではなく「役割分担」

論争を整理すると、こう分かれる。

【入力】 プロンプト内で役割を区切る        → XML タグが強い
【執筆】 人間が設計書・知識を書いて管理する → Markdown が強い
【出力】 人に見せる成果物・ダッシュボード   → HTML が強い

私たちが毎日、手で触り続けるのは真ん中の「執筆」レイヤーだ。ここはトークン効率・スマホ入力・Obsidian相性・差分管理のすべてでMarkdownが勝つ。

XMLはAIに渡す瞬間に効かせればいいし、HTMLはツールやAIに生成させればいい。人間がゼロから書く層を、わざわざ冗長なXMLや表示用のHTMLで書く理由はほとんどない。

人間は Markdown を書く
   ↓
AI が必要に応じて XML へ変換（入力時）
   ↓
ツール / AI が HTML を生成（公開・表示時：Docusaurus, MkDocs など）

結節点としての YAML Front Matter

ではMarkdownのまま、どうやってAIに「構造」を渡すのか。その答えが YAML Front Matter だ。

ノートの先頭を --- で囲み、メタ情報をYAMLで書く。

---
project: fx-system
status: active
version: 1.2
language: python
agent: claude-code
priority: high
owner: hiro
---

# ドル円分析システム

## 要件
MT5から価格を取得し、ドル円を監視する

## 制約
Python を利用する

タイトルと本文だけだと、AIは「プロジェクト名は？」「何が重要？」を推測するしかない。だがFront Matterで明示されていれば、AIは推測せず事実として受け取れる。Markdownの読みやすさを一切犠牲にせず、XML級の構造化情報をAIに手渡せる ― これがYAMLの妙味だ。

しかもこの「YAML + Markdown」構造は、私の思いつきではなく業界標準そのものだ。

  • AGENTS.md がデファクト標準化。OpenAI Codex・Cursor・GitHub Copilot が横断採用し、2026年半ばで6万超のOSSリポジトリで使用。ガバナンスはMCPと同じLinux Foundation傘下へ。(Augment Code / codersera)
  • SKILL.md もまさに「YAML Front Matter + Markdown本文」構造。(agensi.io)
  • Cursor の .cursor/rules/ もYAML Front Matterでルールをスコープ。(Agentailor)
  • Obsidian × MCP が「AIの文脈源（source of truth）」に。(ericmjl)

つまり、いま業界が共通して採用しているのは ― Markdown + YAML Front Matter なのだ。

まとめ：覚えるべきは新エディタではなく、--- の3文字

設計書はMarkdownで書く。それは人間が読み書きしやすいからであり、そのままAIのコンテキストになるからであり、Obsidianを通じて知識の源（source of truth）になるからであり、そして単純に安いからだ。

その土台の上で、「AIの理解しやすさ」を突き詰めると入力レイヤーでXMLが、「人間に見せる」を突き詰めると出力レイヤーでHTMLが議論されている ― それが2026年の「フォーマット三つ巴」の正体だった。だがこれは勝ち負けではなく、入力=XML／執筆=Markdown／出力=HTML という役割分担だ。

私たちが日々書く「執筆」レイヤーでは、いまも Markdown が圧倒的に強い。次に覚えるべきは、新しいIDEでも、HTMLタグでもない。ノートの先頭に書く --- の3文字 ― YAML Front Matter だ。

Markdownの書きやすさはそのままに、AIに構造を手渡せる。Obsidian × Markdown + YAML は、派手さこそないが、フォーマット三つ巴の答えとして確実に来ている本命だと思う。

参考にした記事

コメント

タイトルとURLをコピーしました