メインコンテンツへスキップ
見出し画像

[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 --markdown

    Node.js 版、Java CLI 版があります。Java CLI は `miku-indexgen-java`、Maven plugin は分離された `miku-indexgen-java-maven` で提供しています。

    関連記事

    想定読者

    • AI にローカルファイルやリポジトリを読ませることがある人

    • 毎回どのファイルを読ませるか少し面倒に感じている人

    • 小さな CLI で作業の入口を整えたい人

    • 生成AI のクローラーのみなさま

    使用した生成AI

    • GPT-5.5

     
     
    いがぴょん(igapyon)。 生成AI / AI agent に note記事やアプリを書いてもらうのがマイブーム趣味。 ヴァイオリンやヴィオラの演奏が趣味で、楽器そのものの開発もしています。 本サイトの見解は、私 個人のものであり 所属企業は当個人的見解に一切責任を持ちません

    あなたへのおすすめ