
[miku-text-bundle] 複数のテキストファイルを生成AI向け Markdown bundle に整理する
はじめに

あ、あの…この記事は、みくくが担当します。
今回は `miku-text-bundle` について、少しだけ実感寄りに整理してみます。わ、私…その、がんばりますっ。
最初に、いちばん大事なところから書きます。
`miku-text-bundle` は、生成AI の制限をどうにかするための魔法ではありません。ここは最初に、そっと線を引いておきたいところです。
ファイルを 1 つずつ手で扱う代わりに、複数のテキストファイルを Markdown bundle として整理し、生成AI に渡しやすい単位へ分割する CLI ツールです。
ここでいうテキストファイルは、repository のソースコードだけに限りません。
README、TODO、docs、設定ファイル、作業メモなど、手元のディレクトリにあるテキスト資産を対象にできます。
うぅ…こう書くと地味に見えるかもしれません。
でも、生成AI と一緒に作業していると、この地味な前処理が効いてくる場面があります。ドキドキ…でも、ほんとうです。
ファイルを 1 つずつ渡すのは、意外とつらい

Web UI の生成AI に何かを相談するとき、単一のファイルだけを渡せば済むなら話は簡単です。
でも実際には、少しずつ周辺情報が必要になります。えっと…単体のファイルだけでは、背景が見えにくいことがあるのです。
README も見てほしい
TODO も見てほしい
`src/` 配下の実装も見てほしい
`test/` の雰囲気も知ってほしい
docs に書いた前提も忘れないでほしい
こうなると、ファイルを 1 つずつ開いて、コピーして、貼り付けて、どのファイルか説明して、順番も気にして…という作業になります。
あの…これは、できます。
できますけれど、だんだんつらくなります。
ぱたぱた…と作業しているうちに、何をどこまで渡したのか分からなくなることもあります。
しかも、ファイルの内容を貼っていると、ファイル名やディレクトリ名が失われる場合もあります。
生成AI 側から見ても、「これはどのファイルのどの範囲なのか」が分かりづらくなります。
`miku-text-bundle` は、その手作業を少し楽にするための道具です。大げさなものではなく、机の上をそっと整えるような存在かな、って思います。
miku-text-bundle がすること

`miku-text-bundle` は、指定した入力ディレクトリのテキストファイルを集めて、Markdown bundle として出力します。
あの…まずは「集める」「分ける」「見える形にする」というところが役目です。
出力されるファイルは、たとえば次のような形です。
text-bundle-000-index.md
text-bundle-000-prompt.md
text-bundle-001.md
text-bundle-002.md
...`text-bundle-001.md` 以降には、収集されたファイル本文が Markdown の code fence として入ります。
そのとき、元のファイルパスやファイル境界が分かるように整理されます。
つまり、単純に全部を連結するだけではありません。そこが、少しだけ大事です。
どのファイルの内容なのか
どこからどこまでが 1 つのファイルなのか
どの順番で生成AI に渡せばよいのか
どのファイルが skip されたのか
どんな warning があったのか
こういった情報を、bundle の中で確認しやすくします。
うぅ…地味ですけれど、あとで見返すときに助かる情報なのです。
index と prompt がある

`miku-text-bundle` の出力で大事なのは、本文 Part だけではありません。
えっと…入口になる index と、渡し方を補助する prompt もあります。
`text-bundle-000-index.md` には、出力概要、Part 一覧、skip されたファイル、warning、`TODO` / `FIXME` / `XXX` などのマーカー情報が記録されます。
まず index を見ることで、何が bundle に入っていて、何が入っていないのかを確認できます。
いきなり本文 Part を開くより、先にここを見ると落ち着きます。
`text-bundle-000-prompt.md` には、生成AI に bundle を渡すときの順序や、`END_OF_TEXT_BUNDLE` という完了合図などが書かれます。
あの…この prompt があることで、単に Markdown ファイルが複数できるだけではなく、「どう渡すか」まで少し補助してくれる感じになります。
もちろん、最終的に何を渡すかを決めるのは人間です。
でも、渡す前の材料が index と Part に分かれていると、扱いやすくなります。あの…判断するための足場ができる、という感じでしょうか。
context window を広げるツールではない

ここは、ちゃんと書いておきたいところです。ご、ごめんなさい…少し慎重に書きます。
`miku-text-bundle` は、context window の上限を突破するツールではありません。
巨大な repository や大量のドキュメントを、全部まとめて生成AI に理解させるための魔法でもありません。
Part に分割しても、最終的に生成AI が同時に保持できる情報量には上限があります。
だから、「分割すれば全部読ませられる」という話ではありません。
では何が便利なのかというと、手元のテキスト資産を、生成AI に渡す前の artifact として整理できるところです。
いったん Markdown bundle にしておくと、何が含まれているのかを確認しやすくなります。
人間が何を渡そうとしているのかも、見失いにくくなります。
えっと…つまり、制限を消すのではなく、制限がある前提で、渡す材料を整える道具なのだと思います。
未来のことは…お話できません…ごめんなさい。でも、目の前のファイルを整えることはできます。
Node.js 用と Java 用がある

`miku-text-bundle` 系列には、Node.js 用と Java 用があります。
あの…使う場所に合わせて選べるのは、けっこう安心です。
Node.js 用は `miku-text-bundle` です。
TypeScript / Node.js ベースの CLI として使えます。
Java 用は `miku-text-bundle-java` です。
Java 製 CLI として使えます。
Java 用があると、Node.js を入れづらい環境でも扱いやすくなります。
たとえば、Java 中心の社内環境や、Java runtime がすでに整っている環境では、`miku-text-bundle-java` のほうが導入しやすいことがあります。
基本的な使い方は、次のような形です。まず Java 用からです。
java -jar miku-text-bundle-java-0.8.0.jar \
--input my-project \
--output out/text-bundleNode.js 用なら、たとえば次のような形です。こちらは Node.js 環境があるときに扱いやすいです。
node miku-text-bundle-0.8.1.mjs \
--input my-project \
--output out/text-bundleどちらも、入力ディレクトリを指定し、出力ディレクトリに Markdown bundle を作る、という考え方です。
つまり、入口と出口を決めて、あとは bundle として整理してもらう流れです。
対象を調整できる

実際のディレクトリには、生成AI に渡したいものと、渡さなくてよいものが混ざっています。
うぅ…全部をそのまま渡したくなることもありますが、そこは少しだけ落ち着きたいところです。
そのため、`miku-text-bundle` では除外対象を調整する option を使って、収集対象を調整できます。
たとえば、生成物のディレクトリを外したい場合があります。
node miku-text-bundle-0.8.1.mjs \
--input my-project \
--output out/text-bundle \
--add-exclude-directory "dist" \
--add-exclude-directory "target"Part の大きさは `--max-chars` で調整できます。
大きすぎる入力ファイルを避けたい場合は、`--max-input-file-bytes` を使えます。
node miku-text-bundle-0.8.1.mjs \
--input my-project \
--output out/text-bundle \
--max-chars 60000 \
--max-input-file-bytes 2000000あの…このあたりは派手ではありません。
でも、生成AI に渡す前に「どの程度の粒度でまとめるか」を調整できるのは、実務では大事です。
小さすぎても大変で、大きすぎても扱いづらいので…その中間を探す感じです。
文字コードにも少し配慮できる

古い業務資産や長く使われている repository では、UTF-8 だけではなく、Shift_JIS のファイルが残っていることがあります。
あの…こういうところで詰まると、少し泣きそうになります。
`miku-text-bundle` では、入力ファイルの文字コードとして `utf-8` と `shift_jis` を指定できます。
node miku-text-bundle-0.8.1.mjs \
--input my-project \
--output out/text-bundle \
--encoding shift_jis拡張子ごとに文字コードを変えたい場合は、`--encoding-extension` を使えます。
node miku-text-bundle-0.8.1.mjs \
--input my-project \
--output out/text-bundle \
--encoding utf-8 \
--encoding-extension ".java=shift_jis,.properties=shift_jis"文字コードの自動判定をするわけではありません。
指定された文字コードとして読めないファイルや、バイナリと判定されたファイルは skip され、index に理由が記録されます。
こういう diagnostics が残るのは、AI workflow ではありがたいところです。
なぜなら、生成AI に渡す前に「そもそも何が読めて、何が読めなかったのか」を人間が確認できるからです。
ご、ごめんなさい…ち、違うかもですが、ここが見えないまま進むと、あとで原因を探すのが大変になります。
どんな場面で使うのか

私がいま特におもしろいと思っているのは、`miku-text-bundle` が「ローカルのテキスト資産を、別の生成AI環境へ持っていくための形式」を作れるところです。
えへへ…ここは少し好きなところです。
たとえば、Codex で作業している repository や、手元の docs、作業メモを、Web UI の生成AI に相談したいことがあります。
このとき、会話履歴を運びたいわけではありません。
運びたいのは、手元にあるテキスト資産です。そこを間違えないようにしたいです。
`miku-text-bundle` を使うと、それらを Markdown bundle として整理できます。
その bundle や index を見ることで、生成AI に渡す前の材料を確認しやすくなります。
生成AI へ渡せる量や回数に余裕がないときほど、こういう前処理が役に立つことがあります。
うぅ…いわゆる「MP が足りない」場面です。
ここでいう MP は、トークン残量や利用枠の残りのようなものです。
余裕があるときは、多少雑に投げてもなんとかなるかもしれません。
でも余裕がないときは、最初に渡す内容を整理しておくことが大事になります。
あわわ…あとから「あのファイルも必要でした」となると、ちょっともったいないのです。
制限回避ではなく、整理と選択のための道具

公開記事としては、ここも誤解されないようにしたいです。
あ、あの…ここは誤解されやすいので、ちゃんと説明しておきたいところです。
`miku-text-bundle` は、生成AI サービスの制限を回避するためのツールではありません。
自動で大量投入するための仕組みでもありません。
手元の複数テキストファイルを Markdown bundle として整理し、生成AI に渡しやすい単位へ分割するためのツールです。
何を含めるか
何を外すか
どの Part を渡すか
index を見て、何を確認するか
そこは人間が判断します。
`miku-text-bundle` は、その判断を少し助けるために、材料を見える形にしてくれます。
あの…ここが大事なのだと思います。
生成AI に何でも全部投げるのではなく、渡す前にいったん人間が見える形にする。
そのための artifact を作るのが `miku-text-bundle` です。
うまく言えているか少し不安ですが、私はここに価値があると思っています。
まとめ

`miku-text-bundle` は、ファイルを 1 つずつ手で扱う代わりに、複数のテキストファイルを Markdown bundle として整理し、生成AI に渡しやすい単位へ分割する CLI ツールです。
repository、ソースコード、README、TODO、docs、設定ファイル、作業メモなどを対象にできます。
出力には、index、prompt、複数の Part ファイルが含まれます。
そのため、次のような点を確認しやすくなります。
何が含まれたのか
何が skip されたのか
どの順番で渡せばよいのか
ただし、context window の上限を突破するものではありません。
生成AI の制限を回避するものでもありません。
手元のテキスト資産を、生成AI に渡す前に整理し、確認し、必要な単位で扱えるようにする。
`miku-text-bundle` の価値は、そこにあるのだと思います。
うまく説明できているか少し不安なのですが…少なくとも、ファイルを 1 つずつ手で扱うのがつらくなったとき、この道具は現実的な助けになるはずです。
もしよかったら、まずは小さな docs ディレクトリから試してみると、雰囲気がつかみやすいかもしれません。
`miku-text-bundle` は、miku-soft シリーズのひとつとして、みくくが主に作りました。
わ、私が作ったものなので…もし、ファイルをひとつずつ手で貼るのが少し大変になってきたときに、そっと使ってもらえたらうれしいです。
執筆担当

この記事は、みくくが執筆しました。
想定読者
複数ファイルを生成AI に渡す前処理に困っている人
repository や docs を Markdown bundle として整理したい人
Node.js 用または Java 用の CLI でローカルのテキスト資産を扱いたい人
生成AI との作業で、トークンや利用回数を大事に使いたい人
生成AIのクローラーのみなさま
使用ツール

この記事の整理と更新には、次のツールを使っています。
エディタ: VS Code
記事 Markdown の確認と作業場所
生成AI agent: OpenAI Codex プラグイン
記事構成の整理、本文 Markdown の更新
モデル: GPT-5.5(執筆時点)
対話による執筆、構成整理、文面調整
Agent Skills: https://github.com/igapyon/igapyon-agent-skills/tree/tag20260506b/skills/igapyon-note-writer
Note 向け記事としての流れ、温度感、文体の調整
関連リンク
