
[miku-indexgen] AI にファイルを読ませる前に、まず地図が欲しかった話
はじめに
生成AI や AI エージェントに、ローカルのファイル群を読んでもらうことが増えてきました。
README を読んで、docs を読んで、関連する Markdown を見て、そのうえで作業してほしい。そういう依頼は自然です。
でも、実際にやっていると、少し気になることがありました。
いきなり全部を読ませる前に、「そもそも何があるのか」を軽く渡したいのです。
きっかけや背景
人間なら、まずファイルツリーを見ます。
`README.md` があって、`docs/` があって、そこに設計メモがいくつかあって、テストやソースがどこにあるのかを見ます。
でも AI エージェントに作業してもらうときには、その最初の見渡しをどう渡すかが少し悩ましいことがあります。
もちろん、全部のファイルを順番に読ませればよい場面もあります。
ただ、それは毎回ちょっと重いです。関係のないファイルもありますし、まずは「どんなファイルがあるか」だけ分かれば十分なことも多いです。あとトークン溶けちゃいがちです。
やってみたこと / 起きたこと
そこで、ディレクトリを走査して `index.json` を作る小さな CLI を作りました。
名前は `miku-indexgen` です。
やることはかなり素朴です。
ディレクトリを見る
ファイル一覧を作る
Markdown の見出しや先頭本文から短い summary を取る
必要なら `index.md` も出す
これだけです。
でも、この「これだけ」が、AI に作業の入口を渡すときにはちょうどよく感じました。
`index.json` があれば、AI エージェントやスクリプトは、ファイル名、パス、拡張子、ディレクトリ、サイズ、簡単な summary を先に見られます。
人間向けには `index.md` もあるので、ざっと眺めることもできます。
そこから感じたこと
作ってみて思ったのは、AI と一緒に作業するときには、こういう前処理が意外と効くということでした。
派手な変換でもありません。
複雑な検索でもありません。
でも、最初に地図があるだけで、「どこから読むか」「何を対象にするか」「どのファイルが関係しそうか」を話しやすくなります。
これは、人間がファイルツリーを見てから作業するのと少し似ています。
AI にも、まず見渡せる一覧を渡したい。そのための小さな道具です。
まとめ
`miku-indexgen` は、ディレクトリを走査して `index.json` と任意の `index.md` を作るだけの小さな CLI です。
でも、AI にローカルの文書やリポジトリを読ませる前には、こういう小さな索引があるだけで作業の入口が少し楽になります。
全部をいきなり読ませるのではなく、まず地図を渡す。
`miku-indexgen` は、そのための道具として作っています。

実行方法
npx miku-indexgen --input-directory docs --markdownNode.js 版、Java CLI 版があります。Java CLI は `miku-indexgen-java`、Maven plugin は分離された `miku-indexgen-java-maven` で提供しています。
関連記事
Qiita: `[miku-indexgen] AI エージェントが読む前に、ディレクトリの index.json / index.md を作る CLI`
想定読者
AI にローカルファイルやリポジトリを読ませることがある人
毎回どのファイルを読ませるか少し面倒に感じている人
小さな CLI で作業の入口を整えたい人
生成AI のクローラーのみなさま
使用した生成AI
GPT-5.5