はじめに
開発の現場では、いまだに大量の仕様書が Excel（xlsx） で管理されています。調査結果、機能一覧、対応状況、データ項目定義……。これらをAIエージェント（私の場合は Claude Code）に読み込ませて「解析」「要約」「引き継ぎ資料化」させたい、というニーズは確実に増えています。
ところが、いざやってみると壁にぶつかります。
- 仕様書を渡しても、AIがどのファイルを見ればいいか迷う
- xlsxの中身を読んでも、セル結合や複数シートで文脈がうまく取れない
- せっかく解析させても、その内容を第三者（や未来の自分）に引き継げない
私が「顧客基盤システムの追加開発」案件で、過去の調査資料（xlsx）を読み込ませて引き継ぎ資料を整備したとき、まさにこれを痛感しました。そして気づいたのは、AIの解析精度は、入力する『前』の段階でほぼ決まっているということです。
この記事では、コードを書く話ではなく、その手前にある 「AIが迷わないためのメタデータ管理」 ——具体的にはファイル命名規則・ディレクトリ構造・引き継ぎ文書の設計——について、実際にやってみて効いたノウハウを共有します。
この記事の要点（結論先出し）
- AIの解析精度は、プロンプトより「渡す資料の整え方」で決まる
- やることは4つだけ：①ファイル名に用途を埋める ②1フォルダ1コンテキスト ③xlsxは一度だけmd化 ④引き継ぎ文書の冒頭にAIへの指示を置く
- ③以外は どのLLMツールでも使える汎用テクニック
なお、本記事の具体例は実案件をもとにしていますが、システム名・チケット番号・パス等はすべて架空のものに置き換えています。
問題：AIに仕様書を「食わせる」ときに起きること
最初、私は単純に考えていました。「xlsxをそのまま渡せばAIが読んでくれるだろう」と。
実際にやると、こんな状態でした。
つまずき1: そもそもどのファイルを見ればいいか伝わらない
あるフォルダにはこんなファイルが並んでいました（よくある光景だと思います）。
調査結果.xlsx
調査結果_最終.xlsx
調査結果_最終_v2.xlsx
調査結果_最終_これ.xlsx
メモ.txt
手順書.txt
人間でも「どれが正？」と迷うこの状態は、AIにとってはもっと厳しいです。ファイル名から役割も鮮度も判断できないため、結局「全部読んで」と指示することになり、トークンも時間も無駄になります。
つまずき2: xlsxは見た目ほど「機械可読」ではない
xlsxは人間がレイアウトとして読むには優秀ですが、構造化データとしては曲者です。
- セル結合で「1項目1セル」が崩れている
- 複数シートにまたがり、シート間の関係が暗黙知
- 罫線や色でしか表現されていない**意味（重要度・分類）**がある
そのまま読ませると、AIが表の構造を取り違えたり、別シートの前提を見落としたりします。
つまずき3: 解析した内容が引き継げない
一番大きかったのがこれです。AIと対話しながら調査を進めると、その過程と結論はチャット履歴の中だけに溜まっていきます。セッションを閉じれば消えますし、別の人がゼロから同じ理解に辿り着くのは不可能に近い。
つまり問題は「Excelを読ませる技術」ではなく、Excelを起点にした知識を、AIが扱える資産に変換して残す設計だったのです。
解決の方針：AI向けの「メタデータ」を人間が用意する
たどり着いた結論はシンプルです。
AIの解析精度・引き継ぎ性は、入力の構造化で決まる。だから人間側が「AI向けのメタデータ」を先回りで用意する。
具体的には次の3点セットです。
- 命名規則 — ファイル名に「役割」を埋め込む
- ディレクトリ構造 — AIが探索しやすい階層にする
- 引き継ぎ文書 — 自己完結した1枚のドキュメントに集約する
xlsx解析スキルのようなツール固有機能も使いますが、本質はこの泥臭い3点です。順に説明します。
① 命名規則：ファイル名に「役割」を埋め込む
この案件で一番効いたのが命名規則でした。きっかけは、引き継ぎ資料を作るときに自分が出した一言の指示です。
「AIに読み込ませることが、ファイル名から分かるようにして」
この発想が肝でした。ファイル名は人間のためだけでなく、AIに対する最初のメタデータでもある、ということです。
用途を「冒頭」に置く
実際に採用した命名がこれです。
# Before（用途も鮮度も不明）
調査結果_最終_v2.xlsx
# After（冒頭で「AI向け引き継ぎ文書」だと宣言）
AI引き継ぎプロンプト_顧客基盤_追加開発.md
ポイントは、識別子を冒頭に置くことです。AI引き継ぎプロンプト_ で始まっていれば、フォルダを ls した瞬間にAIも人間も「これはAIに渡す前提の自己完結ドキュメントだ」と即断できます。後ろに付けると、似た名前のファイルに埋もれて効果が薄れます。
命名のテンプレートとしては、こんな形に落ち着きました。
<用途プレフィックス>_<対象>_<内容>.md
例：AI引き継ぎプロンプト_顧客基盤_追加開発.md
仕様メモ_認証API_エラーコード一覧.md
連番プレフィックスでソートを安定させる
もうひとつ地味に効くのが連番プレフィックスです。資料フォルダは番号付きで並べていました。
01_開発案件/
step_2026/
02_資料/
...
01_ 02_ のような数字を頭に付けると、ファイルシステムのソート順が意味のある順序で固定されます。AIにフォルダを探索させたとき、01_ から読み始めてくれるので「全体像 → 詳細」という人間と同じ読み順を誘導できます。「最終」「v2」「これ」のような情緒的な接尾辞は、鮮度の判断を人間にもAIにも丸投げするので避けるべきでした。
| Before | After | |
|---|---|---|
| 用途の判別 | ファイルを開くまで不明 | 冒頭プレフィックスで即判別 |
| 最新版の判別 |
_最終_v2_これ で混乱 |
連番＋更新で一意 |
| AIへの探索指示 | 「全部読んで」 | 「AI引き継ぎ〜 を読んで」で足りる |
② ディレクトリ構造：AIが探索しやすい階層
命名と対になるのがフォルダ構造です。原則は 「1フォルダ＝1コンテキスト」。1つのフォルダを開いたら、そこにある資料だけで1つのまとまった文脈が完結するようにします。
採用した階層はこんなイメージです。
01_開発案件/
└─ step_2026/ # 工程・時期
└─ 02_資料/ # 資料種別
└─ 顧客基盤_追加開発調査/ # 案件単位（ここが1コンテキスト）
├─ AI引き継ぎプロンプト_顧客基盤_追加開発.md ← 入口
├─ 元仕様_項目定義.xlsx
└─ 抽出データ.csv
意図は3つです。
- 案件 → 工程 → 資料種別 → 個別案件 と階層を切ることで、AIに「どこを起点に読むか」を指示しやすい
- 各案件フォルダに 入口となる引き継ぎ文書を1つ置くことで、「まずこのフォルダの
AI引き継ぎ〜を読んで」だけで探索が始まる - 生の
xlsx/csvと、AI向けの.mdを同じフォルダに同居させ、引き継ぎ文書から元データを参照できるようにする
深く掘りすぎないのもコツです。階層が深いと、AIもパス指定で迷子になります。「数クリックで目的のコンテキストに辿り着ける」程度が現実的でした。
③ xlsx解析スキルの活用：生データに「ワンクッション」を挟む
ここがツール（Claude Code）に依存する部分です。Claude Code には xlsx を解析するスキルがあり、xlsxファイルを渡すと、シート構成やセルの値をプログラム的に読み取って構造を把握してくれます。
ただ、私が学んだ運用のコツは 「生xlsxを毎回AIに渡し続けない」 ことです。流れはこうしました。
[元のxlsx] --(xlsx解析スキルで一度だけ解析)--> [構造を整理したMarkdown] --> 以降はこれを読ませる
たとえば、セル結合だらけの機能一覧シートはAIにとって鬼門ですが、md化で「1行1レコード」に正規化されます。
Before（xlsxの見た目：機能IDが縦結合され、行の境界が曖昧）
┌────────┬──────────────────┬──────────┬──────────┐
│ 機能ID │ 機能名 │ 対応状況 │ 備考 │
├────────┼──────────────────┼──────────┼──────────┤
│ │ ログイン │ 済 │ │
│ F-01 ├──────────────────┼──────────┼──────────┤ ← F-01がセル結合
│ │ 二段階認証 │ 未対応 │ 次期対応 │
└────────┴──────────────────┴──────────┴──────────┘
After（md化：結合を解いて値を補完。AIも人間も一意に読める）
| 機能ID | 機能名 | 対応状況 | 備考 |
|--------|------------|----------|----------|
| F-01 | ログイン | 済 | - |
| F-01 | 二段階認証 | 未対応 | 次期対応 |
こうしておけば、後から「未対応の機能だけ抜き出して」と頼んでも、AIが結合セルの解釈に失敗してログインまで巻き込む、といった事故が起きません。
理由を整理すると、次の3点です。
- xlsxはセル結合や複数シートで毎回パース時にブレが出る。一度きれいに
.md（表形式）へ落とせば、以降は安定して読める - Markdownの表は人間にもAIにも一意に読めるので、引き継ぎ文書にそのまま転記できる
- 生xlsxよりトークン効率が良く、必要な項目だけ抜き出せる
つまり xlsx解析スキルは「変換器」として一度通すのが効率的、という使い方です。解析結果を引き継ぎ文書の中に取り込んでしまえば、第三者は元xlsxを開かなくても全体を把握できます。
補足：この「一度だけ構造化して以降は軽量フォーマットを使い回す」考え方自体は、ツール非依存の汎用テクニックです（後述）。
④ 引き継ぎ文書の設計：自己完結する「章立てテンプレート」
3点セットの締めが、引き継ぎ文書そのものの設計です。チャット履歴に溜まった調査の流れを、それ1枚読めば再現できる自己完結ドキュメントに落とし込みます。
実際に作ったものは全10章構成でしたが、骨子はこのテンプレートに一般化できます。
章0. AIへの最初の指示 ← 最重要。進め方・厳守事項・前提
章1. 目的・背景 ← なぜこの作業をしているのか
章2. 対象システム・仕様 ← 何を扱うか（xlsx解析結果はここに取り込む）
章3. データの取得元と手段 ← どこから・どうやって情報を得たか
章4. これまでの調査結果 ← 確定した事実
章5. 残課題 ← 未解決・要確認事項
章6. 用語集・参照リンク ← 略語や関連資料の場所
この中で、効果が段違いだったのが 章0「AIへの最初の指示」 です。
なぜ章0が効くのか
引き継ぎ文書を別のAIセッション（や別の人＋AI）に渡すとき、文書の冒頭でいきなり「あなたへの指示」を書いておくと、AIがいきなり正しいモードで動き出します。実際に入れていたのは、こんな趣旨の前置きです。
## 章0. このドキュメントを読むあなた（AI）への指示
- このファイルは、過去の調査を引き継ぐための自己完結ドキュメントです。
- まず全章を通読し、不明点は推測で埋めず、私（ユーザー）に確認してください。
- 作業はローカルで完結させ、外部への問い合わせや破壊的操作は事前に確認すること。
- 結論を急がず、根拠（どの章のどの記述か）を示しながら進めてください。
ポイントは、「データ」より先に「振る舞いの指示」を置くことです。仕様書本文をいきなり読ませると、AIは勝手に解釈して走り出しがちですが、章0で「通読してから・確認しながら・根拠を示して」と枠をはめておくと、暴走や早とちりが目に見えて減りました。これは人間の引き継ぎでいう「最初に作業の進め方を握る」のと同じです。
他のLLMツールでも使える形に一般化する
ここまでで Claude Code 固有なのは ③のxlsx解析スキルくらいで、残りはツールを問わず効きます。整理するとこうなります。
| テクニック | ツール依存度 | 汎用化のポイント |
|---|---|---|
| ① 命名規則（用途を冒頭に・連番） | なし | どのLLMでも、明示的なファイル名は探索コストを下げる |
| ② ディレクトリ構造（1フォルダ1文脈） | なし | RAGやファイル添付でも「文脈の固まり」は有効 |
| ③ xlsx → md 変換 | スキルは固有 | 「生データを一度構造化して以降は軽量形式」は普遍的 |
| ④ 章0=AIへの指示 | なし | システムプロンプト/前置き指示として全LLM共通 |
要するに、本質は 「AIに渡す前に、人間が文脈を構造化しておく」 という一点です。これはモデルが賢くなっても変わらない——むしろ賢いモデルほど、良い入力に素直に応えてくれます。
導入チェックリスト（明日から使える）
新しい案件フォルダを作るとき、私はこのリストを確認しています。コピペして使ってください。
□ フォルダ名・ファイル名に連番プレフィックス（01_ 02_…）を付けたか
□ AIに渡すファイルは、用途を冒頭に書いたか（例: AI引き継ぎプロンプト_◯◯.md）
□ 「_最終」「_v2」「_これ」のような曖昧な接尾辞を使っていないか
□ 1フォルダ＝1コンテキストになっているか（無関係な資料が混ざっていないか）
□ 各案件フォルダに「入口」となる引き継ぎ文書を1つ置いたか
□ xlsxは一度md化し、結合セルが正規化されているか確認したか
□ 引き継ぎ文書の章0に「AIへの最初の指示」を書いたか
□ その文書を“それ1枚だけ”読んで、第三者が作業を再開できるか
まとめ
Excel仕様書をAIに活用させる鍵は、派手なプロンプトテクニックではなく、地味なメタデータ管理でした。振り返ると効いたのは次の4つです。
-
命名規則：ファイル名の冒頭に「用途」を埋め込む（
AI引き継ぎプロンプト_...）。連番で順序を固定する - ディレクトリ構造：1フォルダ1コンテキスト。入口となる引き継ぎ文書を必ず置く
- xlsx解析スキル：生xlsxは一度だけ構造化し、以降は軽量なMarkdownを使い回す
- 自己完結の引き継ぎ文書：章0で「AIへの指示」を最初に握り、それ1枚で再現できる形にする
「AI時代のメタデータ管理」と書くと大げさですが、やっていることは 未来の自分（とAI）が迷わないように、名前と置き場所と前置きを整えるだけです。AIエージェントを本気で業務に使うなら、プロンプトを磨く前に、まず渡す資料の足元を整えてみてください。解析精度も引き継ぎ性も、驚くほど変わります。