TL;DR
- 「AI可読性」は便利な言葉だが、そのままでは測定できないバズワードになりがちだ。本記事は5軸に分解し、4軸を実測した（シード固定・再現可能・架空ダミーデータ）
- 表形式データのトークン効率は CSV が圧勝（x1.00）。Markdown表は x1.22 で健闘、JSON(min) は x1.48、「AIに優しい」と言われがちな整形JSONは x2.4、XML は x2.8〜3.3。3トークナイザ（o200k / cl100k / Gemini）で順位は一致した
-
「YAMLはAIが生成時にコケやすい」は棄却された。通常データも意地悪データも、全6形式で構文成功 10/10（gemini-3.6-flash, N=10）。現代の生成の危険は構文エラーではなく、md表が改行を
<br>に静かに書き換える類の「検知できない内容改変」に移動していた - diff は1行1レコード形式（CSV / JSONL / md表）が仮説どおり優秀。ただし minified JSON の「±2行だが変更行4,349文字」という実測が、行数とレビュー可能性は別物だと教えてくれた
- 50%で切断すると、行指向形式は約半分を復元できるが、JSON / XML は 0 レコード。ゼロか半分か、の落差は測るまで分からなかった
- ファイルサイズはコストに直結する実務問題でもある。「AI可読性」は美学ではなくコスト最適化の話だ
- 型注釈が AI を助けるとしても、「AIが読みやすいから」で技術選定を歪めるのは本末転倒という立場を取る
- 結論: 「Markdownが最適」にはならなかった。用途で答えが変わる。同じCSVが「読ませる」王者で「書かせて機械が受ける」非推奨、という実測結果がそれを象徴している
- 未実測の残余（Claude の Token Counting API 実測・深いネスト・多モデル比較）は明記した。追試のマサカリを歓迎する
その『AI可読性が高い』、根拠はありますか
「AIに読ませるファイルはMarkdownが最適」という言説を、この1年でいったい何回見ただろうか。筆者自身、社内向けのAI駆動開発資料に「AI可読性の高いデータファイル」という項目を作ったことがある。書きながらふと気づいた。その「可読性」とは、具体的に何を指しているのか、自分でも説明できなかった。
トークンが少なくて済むという話なのか。構造を誤解されにくいという話なのか。それとも、AIが生成するときにエラーを起こしにくいという話なのか。三つとも別の性質なのに、「AI可読性」という一語にまとめて語られることが多い。まとめて語られた瞬間、それは検証不能なスローガンになる。
姉妹記事（都市伝説成仏ガイド）の「伝説その5」で、筆者は自分の資料の「Markdown＝AI可読性が高い」という一文に自分でツッコミを入れた。「で、測った？」と。本記事はその宿題を回収する記事である。測った。 結果には、仮説どおりのものと、仮説が気持ちよく裏切られたものの両方がある。
「AI可読性」を5つの測れる軸に分ける
バズワードを解体するには、まず軸を立てる必要がある。本記事では以下の5軸に分解して扱う。
- トークン効率 — 同じ情報量を表現するのに何トークン必要か
- 構造の曖昧さ耐性 — AIがそのフォーマットを生成する際、構文エラーや意味の壊れがどれだけ起きにくいか
- diff親和性 — 変更箇所だけを明確にdiffへ反映できるか
- 部分読み込み可能性 — ファイルの断片だけを読んでも意味が通るか
- 言語選定への波及 — 型システムや命名規則の一貫性がコード理解・生成の精度にどう影響するか
この5軸を貫く原則がひとつある。「AI」とだけ書いて済ませないことだ。Claude・GPT・Geminiはトークナイザが異なる。同じテキストでもモデルによってトークン数が変わる。以降、数値を出す場面では必ずどのモデルの計測かを明示する。
JSON・YAML・TOML・Markdown、同じ情報量で何トークン違うか【実測】
軸1、トークン効率。測った。
測定条件（シード固定・完全な架空ダミーデータ・再現可能）:
- データA: 表形式50レコード×6フィールド（id/名前/カテゴリ/価格/在庫/備考）を日本語・英語の2ロケールで用意
- データB: ネスト設定ファイル（3階層・リーフ30キー相当）
- トークナイザ: tiktoken
o200k_base（GPT-4o系）/cl100k_base（GPT-4系）をローカル計測、Gemini は countTokens API（gemini-3.6-flash）を実測 - Claude は未計測。ローカル完結の公式トークナイザが公開されておらず、Token Counting API を叩く必要があるが、執筆環境に API キーを保持していないため。追試する場合は Anthropic の count_tokens エンドポイントで同一テキストを投げればよい（本記事の数値表はそのまま比較対象として使える）
表形式データ（日本語50レコード）— o200k 昇順
| format | bytes | o200k | cl100k | Gemini | 対最小比(o200k) |
|---|---|---|---|---|---|
| CSV | 2,931 | 1,237 | 1,477 | 1,346 | x1.00 |
| Markdown表 | 3,671 | 1,513 | 1,807 | 1,696 | x1.22 |
| JSON(minified) | 5,599 | 1,829 | 2,069 | 1,938 | x1.48 |
| JSONL | 5,597 | 1,876 | 2,116 | 2,034 | x1.52 |
| TOML | 6,146 | 2,276 | 2,516 | 2,584 | x1.84 |
| YAML | 5,497 | 2,337 | 2,631 | 2,474 | x1.89 |
| JSON(pretty) | 7,700 | 2,928 | 3,168 | 3,438 | x2.37 |
| XML | 9,568 | 3,432 | 3,672 | 3,942 | x2.77 |
英語ロケールでも順位はほぼ同じ（CSV x1.00 → XML x3.26）。3トークナイザとも順位が一致した。
ネスト設定ファイル
| format | o200k | Gemini | 対最小比 |
|---|---|---|---|
| JSON(minified) | 182 | 213 | x1.00 |
| YAML | 221 | 266 | x1.21 |
| TOML | 222 | 286 | x1.22 |
| JSON(pretty) | 312 | 394 | x1.71 |
| XML | 384 | 472 | x2.11 |
仮説はどうなったか
- 「CSVは列名の繰り返しがない分効率的」→ 確認。表形式では圧勝（キー名を50回繰り返す JSON 系に対し、CSV はヘッダ1行で済む。JSONL と CSV の差=+52% が「キー名繰り返しの値段」そのものだ）
- 「ネストが深いJSONは括弧でトークンを浪費」→ 半分だけ正しい。浪費しているのは括弧ではなくインデントだった。JSON-pretty は JSON-min の約1.6倍。ネスト設定では minified JSON が最小で、YAML より効率的という仮説逆転が起きた
- 「Markdown は AI に優しい」→ 表形式のトークン効率では CSV に負ける（が、健闘の x1.22。人間可読性との両立を考えれば悪くない）
- おまけ: 日本語データは cl100k で +45% 膨らむが o200k では +26% に改善。トークナイザ世代でロケールペナルティが違う
AIに読ませる形式と、AIに書かせる形式は別の話
ここが本記事でいちばん言いたいことだ。世の中の「AI可読性」言説は、ほぼ全部「AIに読ませる」視点で書かれている。しかし実務では「AIに書かせて、それを人間や別システムが読む」場面が同じくらい多い。この二つは要件が逆向きになることがある。
通説はこうだ。「YAMLはインデント依存でAIが生成時にコケやすい。JSONは記号だらけで冗長だが、その記号が構造の境界を明示するので壊れにくい」。筆者もそう書くつもりだった。測ったら、話が違った。
測定方法: 同一の10レコード（シード固定ダミー）を各フォーマットで出力させる試行を、フォーマットごとに10回（モデル: gemini-3.6-flash、temperature はAPI既定）。判定は「標準パーサでそのままパースできるか（構文）」と「パース結果が元データと完全一致するか（内容）」の2段階。さらに、エスケープ地獄データ（コロン+スペース、二重引用符、改行入り値、行頭#、行頭-、裸の no、パイプ |、<tag>&、バックスラッシュ、末尾空白——各フォーマットの急所を突く10種）でも同じ試行を行った。
| format | 通常データ 構文/内容 | 意地悪データ 構文/内容 |
|---|---|---|
| JSON | 10/10 · 10/10 | 10/10 · 10/10 |
| JSONL | 10/10 · 10/10 | 10/10 · 10/10 |
| YAML | 10/10 · 10/10 | 10/10 · 10/10 |
| TOML | 10/10 · 10/10 | 10/10 · 10/10 |
| CSV | 10/10 · 10/10 | 10/10 · 0/10 |
| Markdown表 | 10/10 · 10/10 | 10/10 · 0/10 |
まず通常データ。全フォーマット、構文も内容も満点。「YAMLはAIが苦手」は、この難度・このモデルでは観測されなかった。仮説は気持ちよく棄却された。現行モデルの生成は、フラットな表データ程度なら構文的に堅牢である。
面白いのは意地悪データだ。構文レベルでは依然として全フォーマット満点。YAMLはコロン入りの値を正しくクオートし、CSVは二重引用符を "" に重ね、Markdown表はパイプを \| にエスケープした。モデルはエスケープ規則を知っている。
にもかかわらず、CSVとMarkdown表だけ内容の完全一致が0/10になった。出力の実物を突き合わせて原因を特定した。
-
Markdown表は改行を表現できないため、モデルが値を
<br>に書き換えた。構文エラーは出ない。パースも通る。しかしデータは変わっている。表現力の限界を、モデルが「気を利かせて」silent に埋めた -
モデルは GFM 準拠で
\|とエスケープしたのに、受け側の素朴なパーサ（|で split する世に無数にある実装）がそれを解釈できず、レコードが1件まるごと静かに消えた。どちらも「正しく」振る舞った結果、仕様の曖昧さがツールチェーンの断絶になった - CSVの不一致は末尾空白の1プローブのみ（モデルの出力は RFC 4180 準拠だった）。裸フィールドの末尾空白は仕様上は保持されるが、現実の受け側はしばしば trim する——本検証のハーネス自身がまさにそれをやらかした
つまり、こういうことだ。現代のモデルにとって、生成の危険は構文エラーからほぼ消えた。残った危険は「フォーマットの表現力不足を埋めるための静かな改変」と「仕様の曖昧さによる送り手と受け手の解釈不一致」に移動している。構文エラーは検知できる。静かな改変は検知できない。JSON / YAML / TOML が意地悪値でも完全にラウンドトリップしたのは、エスケープ体系が仕様として一意に確定しているからだ。
限界も明記する。単一モデル・N=10・フラットな表データでの結果であり、深いネストや長大出力、別モデルでは差が出る可能性は残る。また「素朴なパーサ」も測定系の変数だ——ただしそれは現実のパイプラインの変数でもある。
読ませる形式と書かせる形式、要件は正反対のことがある。
AIが変更箇所を見つけやすいのは、1行1レコードの形式【実測】
軸3、diff親和性。同一の変更操作を各フォーマットに適用し、unified diff（コンテキスト0行）の ±行数 と 変更行の最長文字数 を計測した。「±行数」は構文ノイズに加えて「そのフォーマットで1レコードが占める行数」を含む、いわば diff のフットプリントだ。
操作: (a) 50レコード中の1つの価格を変更 / (b) 末尾に1レコード追記（表形式・日本語データ）
| format | (a)値変更 | (b)追記 | 変更行の最長 | 一言 |
|---|---|---|---|---|
| CSV | 2行 | 1行 | 33c | 理想形。追記=綺麗に1行 |
| JSONL | 2行 | 1行 | 87c | 同上。行が少し長い |
| Markdown表 | 2行 | 1行 | 47c | 同上 |
| YAML | 2行 | 6行 | 20c | 追記レコード自体が6行を占む |
| TOML | 2行 | 8行 | 21c |
[[records]] ヘッダ等で+2行 |
| JSON(pretty) | 2行 | 8行 | 27c | 直前行の末尾カンマも変更扱いになる、あの事故 |
| XML | 2行 | 8行 | 29c | タグの開閉ぶん |
| JSON(minified) | 2行 | 2行 | 4,349c | 行数は最小。ただし変更行=文書全体という怪物diff |
数字が語る通り、「±行数」だけ見ると JSON-min が優秀に見えるが、最長 4,349 文字の1行diff は人間にもAIにも実質レビュー不能だ。行数とレビュー可能性は別物——これも測って初めて言語化できた。1行1レコード形式（CSV / JSONL / Markdown表）は仮説どおり、追記が純粋な1行として現れる。JSON-pretty の「1レコード足しただけで直前行の閉じカンマまで diff に載る」現象も実測で再現された。
ファイルを途中から読んでも意味が通るか【実測】
軸4、部分読み込み可能性。コンテキスト長とコストの制約から、大きなファイルは分割して読ませる場面がある。ここで効くのが「途中で切っても復元できるか」だ。
測定方法: 各ファイルを先頭50%バイトで機械的に切断し、「末尾の不完全な行を1行ずつ落とす」だけの修復を許して標準パーサ（json / yaml.safe_load / tomllib / csv / ElementTree）に投げ、復元できたレコード数を数えた。LLMの読解を介さない、純粋に機械的な下限値である。
| format | 復元レコード数（50レコード中） | 判定 |
|---|---|---|
| YAML | 25–26 | ○ 切断点まで素直に復元 |
| CSV | 25 | ○ 同上 |
| TOML | 25 | ○ 同上 |
| JSONL | 24–25 | ○ 同上 |
| Markdown表 | 24 | ○（ヘッダ2行ぶん歩留まり減） |
| JSON(pretty) | 0 | × 閉じ括弧がなく全損 |
| JSON(minified) | 0 | × 1行しかないので全損 |
| XML | 0 | × ルート閉じタグがなく全損 |
ネスト設定ファイル（リーフ30キー）でも同じ構図: YAML 14/30、TOML 13/30 に対し、JSON と XML は 0/30。
仮説どおり——ではあるが、ゼロか半分か、という落差の激しさは測るまで分かっていなかった。行指向フォーマットは「切断点までの情報が全部生きる」のに対し、括弧・タグで全体を包む形式は「1バイト欠けたら全損」。巨大ファイルを分割してAIに流す運用をするなら、この差はコンテキスト設計にそのまま効いてくる。
なお、これは標準パーサでの機械的復元率だ。LLM は壊れた JSON からも中身をある程度「読解」してしまうため、実利用での差はこれより縮む可能性がある。ただし復元をLLMの好意に依存した設計は、それ自体がリスクだというのが筆者の立場だ。
TypeScriptはAIに優しいのか、それとも人間に優しいだけなのか
軸5、言語選定への波及。静的型付け(TypeScript vs JavaScript、型注釈付きPython vs 素のPython)がAIのコード理解・生成を助けるという仮説はよく語られる。型情報は一種の「実行時に依存しないドキュメント」として機能しうる、という理屈自体には筋が通っている。
検証するなら、同一タスク(既存コードへの機能追加)を型注釈ありコードと型注釈なしコードで複数回AIに実行させ、生成コードの型不整合エラー率やレビュー指摘数を比較する、という設計になる。ただしサンプルサイズと再現性の限界は明記しておく必要がある。数回試して差が出ても、それが統計的に意味のある差なのか、たまたまなのかは慎重に見るべきだ。
そして、ここからが本記事で一番強く言いたい批判である。
型注釈やTypeScriptがAIの理解を助けるとしても、それを主目的にプロジェクトの言語選定を変えるのは順序が逆だ。型システムやフレームワークの選定は本来、保守性・チームの習熟度・パフォーマンス・採用のしやすさといった要因で決めるべきものであって、「AIが読みやすいから」を主要因にするのは本末転倒である。
AI可読性は技術選定の加点要素であって決定要因ではない。「AIがコードを理解しやすくなるから型を導入しよう」という提案自体は悪くない。しかし、その提案が「チームの誰も型の恩恵を実感していないが、AIのためだけに導入する」という話にすり替わった瞬間、それはツールのために人間の作業を犠牲にする転倒である。AIはあくまで開発を助ける道具であり、道具に合わせて設計思想を歪めるのは主従が逆だ。
AI可読性は美学ではない。課金明細の話だ
ここまでの5軸は、突き詰めると1つの実務問題につながっている。コストだ。
トークン効率の悪いフォーマットは、同じ情報を伝えるのにより多くのトークンを消費する。部分読み込みができない形式は、ファイル全体を毎回読み込む必要があり、コンテキストウィンドウとAPI課金の両方を圧迫する。これは継続的な会話やエージェントの反復実行で積み重なると無視できない差になりうる(プロンプトキャッシュ機構によって同一プレフィックスの再読み込みコストは軽減されるが、キャッシュが効かない差分部分にはこの問題がそのまま残る)。
つまり「AI可読性」を語ることは、美学の話でも流行りのバズワードの話でもなく、どのフォーマットを選べば同じ作業をより安く回せるかという、地に足の着いたコスト最適化の話である。ここまでの章で扱ってきたトークン効率・構造耐性・diff親和性・部分読み込み可能性は、すべてこの一点に収束する。
結局どれを使えばいいのか — 用途別の判断表【実測に基づく】
ここまでの実測を統合して、用途別の判断表を埋める。「Markdownが万能」という単純な結論にはならなかった。用途で答えが変わる、が実測の答えだ。
| 用途 | 第一候補 | 第二候補 | 非推奨 | 実測に基づく判断理由 |
|---|---|---|---|---|
| 表形式データをAIに読ませる | CSV | Markdown表 | JSON(pretty), XML | トークン x1.00 vs x2.4〜3.3。50レコードでキー名繰り返しの差が支配的 |
| 表形式データをAIに書かせる・機械が受ける | JSONL | JSON | CSV / Markdown表 | 意地悪値でも内容ラウンドトリップ10/10。CSV/md表は構文が通っても内容が静かに壊れることを実測 |
| 設定ファイル（人間が編集） | TOML / YAML | — | XML | トークン+21〜22%の代償で、diff最小・50%切断でも半分復元・コメント可 |
| 設定ファイル（AIが編集） | TOML / YAML | JSON(pretty) | JSON(min) | 生成耐性は全形式満点だったので運用性で決めてよい。json-min は変更行4,349文字の怪物diffでレビュー不能 |
| データ交換（システム間・diff不要） | JSON(min) | JSONL | XML | ネスト構造でトークン最小(x1.00)。diff・部分読込が不要な文脈なら最効率 |
| ログ（大量・追記型） | JSONL | CSV | JSON(配列) | 追記diff=1行、50%切断で半分復元、1行独立でストリーム処理可。JSON配列は追記のたび閉じ括弧が動く |
| ドキュメント / ルールファイル | Markdown | — | — | 見出し分割・人間可読の総合力。ただしこの用途は本ベンチの対象外なので、ここだけは定性判断と明記する |
ひとつ強調したい。同じCSVが「読ませる」では第一候補、「書かせて機械が受ける」では非推奨になっている。冒頭で立てた「読ませる形式と書かせる形式は別要件」という切り口は、実測でここまで具体的な形になった。
もう一つ、正直に書いておく。元になった社内資料には「Markdownは他形式(CSV・PowerPoint・SVG等)への変換が容易」という記述があった。この主張は検証していない。特にMarkdownからスライド形式への変換は、構造化されていない情報源からの生成になりがちで、品質の再現性が低いのではないかという疑いを持っている。この点は要検証のまま残す。断定はしない。
「AI可読性」を語る前に、まず測ろう
5つの評価軸に分解し、実測してから語る、という当たり前のことを当たり前にやる記事を書きたかった。改めてまとめる。
- 「AI可読性」はトークン効率・構造の曖昧さ耐性・diff親和性・部分読み込み可能性・言語選定への波及の5軸に分解でき、うち4軸は今回実測した
- 実測は仮説を3つ裏切った: YAMLの生成は壊れなかった。JSONのトークン浪費の正体は括弧ではなくインデントだった。そして構文が通っても内容が静かに壊れるフォーマットがあった
- 数値を出すときは必ずモデル名を明記する。Claude / GPT / Geminiでトークナイザが違う以上、「AI全般で」は語れない（今回も3系統で計測し、Claudeのみ未計測と明記した）
- 「読ませる形式」と「書かせる形式」は要件が違う。同じCSVが用途次第で第一候補にも非推奨にもなる、という実測がこの非対称性の実体だ
- AI可読性は技術選定の加点要素であって決定要因ではない。型やフレームワークの選定をAIのためだけに歪めるのは本末転倒である
- ファイル形式選定はコスト最適化の話でもある。美学ではない
- そして、測っていない数値は書かない。本記事に残る未実測（Claude実測・深いネスト・多モデル）は未実測と書いた。追試こそ最高のマサカリである
ドキュメントの単一ソース化という隣接領域については、OpenAPI → markdown 単一化の意思決定 — Phase 1 依存断捨離 + Phase 2 物理削除の意思決定プロセスで扱っている。あちらは「ドキュメントをどこに一本化するか」という意思決定プロセスが主題で、本記事は「なぜその形式がAI可読性の観点で有利/不利なのか」を掘り下げる位置づけになる。あわせて読んでもらえると理解が深まるはずだ。
途中で切られたときの反応が、両者の性格を一番よく表している。
参考
公式1次資料（要確認・外部リサーチで確定）
- JSON: ECMA-404 / RFC 8259
- YAML: yaml.org 公式仕様
- TOML: 公式GitHubリポジトリの仕様書
- CSV: RFC 4180
- Anthropic の Token Counting API 公式ドキュメント（ローカル完結の公式トークナイザは非公開のため、API 計測が正となる）
- OpenAI tiktoken 公式リポジトリ
関連記事（筆者）
- 「完全に理解した」の例のグラフ、原論文に無いってよ — 偏屈エンジニアのための都市伝説成仏ガイド
- OpenAPI→Markdown単一ソース化の意思決定記事（隣接領域、公開時にリンク確定）