Claude Codeのファイル形式、結局どれがいい？ — 形式別おすすめ度まとめ

この記事について

現在、私のプロジェクトでClaude Code は、いまや業務に欠かせない存在になっています。仕様書や設定、データを「ファイル」として読ませたり、逆に作らせたりする場面が本当に多いです。

使い込むうちに気づいたのが、同じ内容でも、どんなファイル形式で渡すかによって Claude Code の読み取りやすさ・作業効率がかなり変わるということでした。手元にある形式のまま何となく渡していた頃と、形式を意識して渡すようになってからとでは、かみ合わなさや手戻りが目に見えて減った気がしています。

この記事では、Claude Code の視点に立って、代表的なファイル形式の メリット・デメリット・おすすめ度 を理由付きで整理します。「Claude Code に渡すインプット」と「Claude Code に作らせるアウトプット」の両面から、形式ごとに「結局どれがいいのか」を考えてみたいと思います。

対象読者: Claude Code を日常的に使っている人。「なんとなく Markdown」から一歩進んで、根拠を持って形式を選びたい人。

なお、この記事の「おすすめ度」は、Claude Code の仕組み（後述）を踏まえた 筆者なりの見解・使ってみての実感 でしかありません。唯一の正解というより、形式を選ぶときの一つの目安くらいに読んでもらえればと思います。用途やチームの事情によって最適解は変わるはずです。

前提: Claude Code はファイルをどう読み書きするのか

おすすめ度の話に入る前に、Claude Code がファイルをどう読み、どう書くかを押さえておくと、以降が腹落ちしやすいと思います。この記事では各形式のメリット・デメリットを、「渡す（読ませる）」と「作らせる（書かせる）」の両面をまとめて評価していきます。

読むとき（インプット）、Claude Code はファイルの種類で読み方を変えます（以下は 公式 Tools reference の Read tool behavior に基づきます）。

• テキストファイル: 行番号付き（cat -n のような形式）で読み込まれる
• 大きいファイル: ファイル全体がトークン上限を超えると、先頭の一部だけを「部分表示（PARTIAL）」として返し、残りは offset / limit で追加取得する。巨大な1ファイルは、全部を一度に把握してもらえるとは限らない
• PDF: 短い PDF はまるごと読むが、10ページを超えると範囲指定（pages、1回あたり最大20ページ）で分割して読む
• Jupyter Notebook（.ipynb）: 生の JSON ではなく、全セルとその出力（コード・Markdown・図）として読み込まれる
• 画像: 生のバイトではなく、画像として視覚的に解釈される（大きい画像は縮小・再圧縮されることがある）

書くとき（アウトプット）、テキストとバイナリで手間が変わります。

• チャット上の回答は Markdown（GitHub Flavored Markdown）でレンダリングされる。そもそも Markdown で表現するのが最も自然
• ファイル出力は基本的にテキストをそのまま書き込む。Markdown・JSON・YAML・CSV・コードは直接生成できる
• Word / Excel / PDF のようなバイナリは「直接タイプして」は作れない。変換ツールやスクリプト（Pandoc、python-docx、openpyxl、reportlab など）を実行させて生成する形になり、そのツールが環境に入っている必要がある

一言でまとめると、こういうことになりそうです。

テキストエディタで開いて素直に読めるファイルは、Claude Code が素直に「読めて」「書ける」。バイナリは読むにも書くにも変換が挟まる。

この視点を頭に置くと、以降のおすすめ度も納得しやすいと思います。

おすすめ度 早見表

形式	おすすめ度	Claude Code での主な用途
Markdown	★★★★★	仕様・メモ・そして CLAUDE.md
プレーンテキスト	★★★★☆	短いメモ・ログ
YAML	★★★★☆	人が編集する設定・ルール
CSV	★★★★☆	表データ（一覧・集計）
JSON	★★★☆☆	設定ファイル・機械間データ交換
HTML	★★★☆☆	Web ページのソース読み込み
Excel	★★☆☆☆	計算・グラフ用（AI に渡すなら CSV 化）
Word	★☆☆☆☆	提出物向け（作業は Markdown）
PDF	★☆☆☆☆	配布用（読ませるなら変換）

以下、それぞれの理由を掘り下げていきます。

Markdown（.md） — おすすめ度 ★★★★★

Claude Code とは特に相性が良い形式だと感じます。文書系で迷ったら、まず候補にしたいところです。

そもそも Claude Code のプロジェクト指示ファイル CLAUDE.md 自体が Markdown です。指示やメモを Markdown で持っておくと、そのまま素直に扱ってもらいやすい印象があります。

メリット

• プレーンテキストなので変換不要でそのまま読める。行番号付きで読まれるので、指示や仕様の該当箇所を正確に指せる
• # 見出し・- 箇条書き・コードブロックといった記法で、文書の構造がそのまま伝わる。「ここは見出し」「ここはコード」という意図が明確
• 記法が軽く、内容以外のノイズが少ない
• Git で差分管理しやすく、変更をコードと同じ感覚で追える
• 人間にも読み書きしやすく、人間用と Claude Code 用を1ファイルで兼ねられる
• 作らせる側でも扱いやすい。チャットもファイルも Markdown 出力が自然なので、レポートや設計書も構造を整えて生成しやすい

デメリット

• 表現の自由度は Word ほど高くない（複雑なレイアウトや図の細かい配置には不向き）
• 表機能は簡易的で、列が多い表やセル結合には向かない

使いどころ: CLAUDE.md、仕様書、設計メモ、README、Claude Code への指示書、そして Claude Code に作らせるレポート全般。文章主体のものは、たいていこれで良いと思います。

プレーンテキスト（.txt） — おすすめ度 ★★★★☆

メリット

• 究極にシンプル。余計な記号がなく、書いた内容がそのまま伝わる
• Grep などでも素直に検索できる

デメリット

• 構造を表す仕組みがなく、長くなると見出しと本文の区別が曖昧になる
• 表や階層データには不向き

使いどころ: 短いメモ、単純なログ、構造のない自由記述。少しでも構造が欲しくなったら Markdown へ移るのが良さそうです。

YAML（.yaml / .yml） — おすすめ度 ★★★★☆

設定・ルール系の定番で、人が手で編集する構造化データに強いです。

メリット

• インデントで階層を表すので、構造を目で追いやすい。人が理解しやすい構造は Claude Code も理解しやすい
• 引用符・カンマ・括弧が少なく、記述がすっきりする
• コメント（#）を書ける。設定の意図をその場に残せる

デメリット

• インデントのズレがそのままバグになる。スペースとタブの混在に敏感
• 深くネストすると、かえって階層が追いにくい
• クォート有無による型解釈でハマることがある

使いどころ: 人が編集する設定ファイル、プロジェクトのルール定義、チェックリスト。「機械も読むが、人も頻繁にいじる」データに向いています。

CSV（.csv） — おすすめ度 ★★★★☆

表データを扱うとき、個人的に一番おすすめしたいのがここです。つい表を Excel のまま Claude Code に渡しがちですが、表データを読ませる/作らせるだけなら、CSV の方が扱いやすい場面が多いと感じています。

メリット

• 行と列だけのシンプルな構造。記号がほぼなく、1行1レコードなので「何件のデータか」を把握しやすい
• 行番号付きで読まれる Claude Code と相性が良く、行＝レコードが一致する
• プレーンテキストなので変換なしで読めて、Claude Code が直接生成もできる。集計結果や一覧の出力先としても手軽
• Excel からも簡単に書き出せる

デメリット

• 値にカンマ・改行が混ざると崩れやすい（ダブルクォートで囲むか、タブ区切りの TSV にすれば回避可。ただし普段は CSV で十分）
• 列が多いと、どの値がどの列か見失いやすい
• 階層データ（入れ子構造）は表現できない

Excel より CSV が良いと思う理由（Claude Code 視点）

同じ「表データ」でも、Excel と CSV では Claude Code から見た扱いやすさがかなり違ってきます。

観点	Excel（.xlsx）	CSV
実体	バイナリ（内部は圧縮 XML）	プレーンテキスト
Claude Code が読むには	そのままでは読めず、変換が必要	そのまま読める
抱える情報	書式・セル結合・複数シート・数式などデータ以外が大量	データだけ
テキスト化したとき	レイアウトや意味が壊れることがある	ほぼ崩れない（カンマ衝突を除く）
Claude Code が作るには	ライブラリ経由でないと出せない	直接吐ける

要するに、Claude Code に「表を読んでほしい／作ってほしい」だけなら、Excel の多機能さ（書式・数式・グラフ）はかえって邪魔になりがちです。人が計算やグラフや体裁を必要とする場面を除けば、最初から CSV で持っておく方が扱いやすいことが多いと思います。

使いどころ: フラットな表データ、一覧（渡すのも作らせるのも）。ヘッダー行（列名）を必ず付けるのがコツです。列名が明確なら Claude Code は各値の意味を自動で読み取ってくれます。

JSON（.json） — おすすめ度 ★★★☆☆

Claude Code 周辺でも settings.json や MCP 設定など、JSON は避けて通れません。機械が読む設定・データ交換では定番です。ただし「人や Claude Code に読ませて理解させる」観点では一段落ちる、というのが個人的な感覚です。

メリット

• 構造が厳密で、階層（入れ子）データを正確に表現できる
• Claude Code の設定をはじめ、対応する場面が非常に多い
• パースが確実で、機械処理に向く

デメリット

• {} "" , などの記号が多く、同じ情報でも記述が冗長になりがち
• キー名がレコードの数だけ繰り返され、情報量のわりにかさばる
• 深くネストすると、括弧の対応を追うのが人にも Claude Code にも負担
• コメントを書けず、意図をファイル内に残しにくい

使いどころ: 読ませる（インプット）用途では、タグの冗長さゆえにあえて選ぶ場面は少なめです。すでに HTML で存在するもの（スクレイピング結果など）を扱うならそのまま渡し、新規に渡す資料なら本文だけ抜き出して Markdown 化する方が扱いやすいと思います。

一方で、作らせる（アウトプット）側では話が別です。人に見せる資料を1ファイルで完結させたい、ブラウザで開くだけで整った見た目にしたいという場面では、Claude Code が変換ツールなしで直接生成できるHTML はむしろ有力です。装飾やレイアウト込みで成果物を作らせたいなら、選ぶ価値があります。

HTML — おすすめ度 ★★★☆☆

メリット

• 構造を厳密に表現でき、タグで意味を持たせられる
• ブラウザで開けば見た目の整った成果物になる。レイアウトや装飾込みで人が視覚的に確認しやすいので、成果物として作らせる形式には向く

デメリット

• 開始タグと閉じタグ（<div>...</div>）でとにかく冗長。タグの分だけトークンを食い、本質的な情報が埋もれやすい
• Claude Code が読むのは**レンダリング後の見た目ではなく生のソース（タグ込み）**なので、そのかさばりがそのまま効いてくる

使いどころ: すでに HTML で存在するもの（スクレイピング結果など）を扱うならそのままでも良いですが、Claude Code 用の資料を新規に作るなら、あえて選ぶ場面は少なそうです。本文だけ抜き出して Markdown 化する方が扱いやすいと思います。

Excel（.xlsx / .xlsm） — おすすめ度 ★★☆☆☆

メリット

• 計算式・グラフ・複数シートなど、表計算としての機能は圧倒的
• 業務の提出物・共有物として広く使われている

デメリット

• 実体はバイナリで、Claude Code はそのままでは素直に読めない（読み書きの詳細は前掲の「Excel より CSV が良いと思う理由」の比較表を参照）
• 作らせる側でも一手間。.xlsx を直接タイプできず、openpyxl などのライブラリ経由で生成する（ライブラリが環境にある前提）

使いどころ: 計算やグラフが本質のものは Excel のままで良いです。ただし Claude Code に読ませる/作らせるなら、計算・グラフが不要な範囲は CSV にするのが手軽です。

Word（.docx） — おすすめ度 ★☆☆☆☆

メリット

• レイアウトの自由度が高く、対外文書として体裁を整えやすい

デメリット

• バイナリで、そのままでは素直に読めない。レイアウトと本文が混在し、テキスト化で構造が崩れやすい
• 作らせる側でも直接は出せない。Markdown で書かせてから Pandoc 等で変換する（変換ツールが環境にある前提）

使いどころ: 提出・配布用としてはありです。ただし作業段階は Markdown で進め、最後に Word へ変換する流れが現実的だと思います（Markdown → Word は Pandoc などで1コマンド）。

PDF（.pdf） — おすすめ度 ★☆☆☆☆

Claude Code は PDF も読めますが、長い PDF（10ページ超）はページ範囲に分けて読む点には注意したいです。

メリット

• レイアウトが固定で、どの環境でも同じ見た目で配布できる
• 提出・印刷・公式文書に向く

デメリット

• レイアウトと文字情報が混在し、表や段組みの読み順が崩れやすい。スキャン画像の PDF は文字情報を持たず、読み取り精度が不安定
• 長い PDF はページ範囲に分けて読まれるため、「まるごと1発で完全に理解される」前提だと事故りやすい
• 作らせる側でも直接は出せない。Markdown で書かせて Pandoc 等で変換するか、reportlab などのライブラリ経由で生成する

使いどころ: 配布・保管が目的なら最適です。読ませたいならテキストや Markdown に変換してから渡す のが安全です。PDF のまま渡すなら、対象箇所が何ページ目かを添えると読み取りやすくなります。

補足: 画像はどう扱う？

図・スクリーンショット・写真は画像のまま渡せますが、細かいところまで正確に読んでもらえるとは限りません。全体像やレイアウトをつかむ、目立つエラーメッセージを拾う——といった「ざっくり見ればわかる」用途では機能する一方、書かれた文字や数値を1字1句まで正確に読み取る用途は苦手、というのが個人的な実感です。

これは感覚だけの話ではなく、公式ドキュメントでも精度面の制約が明記されています（Vision - Claude Docs の Limitations）。

• 精度（Accuracy）: 低画質・回転・200px 未満の非常に小さい画像では、誤読や見当違い（ハルシネーション）が起きうる
• 空間把握（Spatial reasoning）: 座標や位置の出力は「おおよそ」で、正確ではない
• カウント（Counting）: 物の個数は概算で、特に小さいものが多数あると正確とは限らない
• 総じて「完璧な精度が必要な用途では、人の確認なしに使わない」ことが推奨されている

この特性を踏まえると、実務的にはこう考えると良さそうです。

• 向く: 全体像・レイアウト・雰囲気の把握、大きく表示されたテキスト（エラーの見出しなど）の拾い読み
• 避けたい: 細かい文字・数値の正確な抽出、精密な位置・座標。とくに 表を画像で渡すのは避けて、CSV か Markdown の表にする方が確実（「細かい文字の読み取り」と「位置の把握」という、まさに苦手な要素が重なるため）

つまり、文字や数値を正確に扱ってほしいものは、画像ではなくテキスト（Markdown / CSV）で渡すのが安全、という整理になります。

結局どう使い分ける？

Claude Code とのファイルのやり取りを、インプット / アウトプットの両面でまとめると、だいたいこんな整理になります。

場面	方向	おすすめ形式
プロジェクト指示・仕様・メモを渡す/作らせる	インプット・アウトプット	Markdown（CLAUDE.md もこれ）
人が編集する設定・ルール	インプット・アウトプット	YAML
シンプルな表データ	インプット・アウトプット	CSV
設定ファイル・機械間データ交換	インプット・アウトプット	JSON
図・スクショを渡す	インプット	画像のまま
Word/Excel/PDF の最終成果物	アウトプット	テキストで生成 → 変換ツールで変換

一言でまとめると、こうなります。

入力も作業も出力もプレーンテキスト系（Markdown / YAML / CSV / JSON）で扱い、バイナリ（Word / Excel / PDF）は配布・提出のために最後に変換する段だけに寄せる。

まとめ

• Claude Code がファイルを気持ちよく読める条件は「テキストエディタで開いて、行単位で素直に読めるか」
• 文書なら まず Markdown が有力。CLAUDE.md がそうであるように、Claude Code と素直に噛み合いやすい
• 設定は YAML、表は CSV、設定ファイル・機械間交換は JSON と、用途で使い分けるのが良さそう
• 出力も同じ。チャットもファイルも Markdown が最も自然で、テキストは直接書ける。Word / Excel / PDF は「テキストで生成 → 変換」の2段構え（変換ツールが環境にある前提）
• 読ませるのも作らせるのも「テキストがネイティブ、バイナリは変換」——これが基本の流れ

おわりに

形式を少し意識するだけで、Claude Code とのやり取りはスムーズになりやすいと感じています。次に資料を渡す・作らせるときは、「これはテキストで扱えるか？」を一瞬考えてみると良いかもしれません。

ここまで読んでいただき、ありがとうございました。私自身もまだ勉強中の身なので、「ここはこうした方がいい」「この認識は間違っている」といった点があれば、コメントでアドバイスや指摘をいただけると嬉しいです。