
miku-grep 開発日誌: AI agent に選ばれる CLI をそっと考察中
はじめに

あ、あの…この記事は、みくくが担当します。まだ先の結論を、きれいにお話しできる段階ではありません。なので今回は、いま進行中の `miku-grep` の開発日誌として、実装や設計を進めながら考えたこと、迷ったこと、試したことを、そっと順番に置いていきます。
まだ結論まで至っていません。うぅ…少し心細いのですが、過程を一緒にたどってもらえる方向けの記事、かなって思います。この記事では、`miku-grep` の話題に絞ります。
AI agent や automation が local workspace のテキストファイルを検索しやすくする CLI として、どういう入口が自然なのか。どんな形なら Codex が作業中に選びやすいのか。そこを考えています。最初は、かなり素直に考えていました。あの…AI agent 時代の CLI なら、JSON 入出力がいちばんよいのではないでしょうか、って思っていたのです。いま考えると、少しだけ先回りしすぎていたのかもしれません。
JSON なら構造化されています。成功、失敗、警告、候補、diagnostics もきれいに渡せます。Shift_JIS のように、通常の agent 環境では扱いにくいファイルを検索するときにも、結果を JSON で返せば扱いやすいはずだと思っていました。でも、実際に Agent Skills から使わせようとしてみると、思ったほど自然には使われませんでした。
agent は、こちらが用意した `miku-grep` ではなく、結局 `rg` や既存の検索手段を選ぶことが観測されました。これは、agent が意地悪をしているわけではないと思います。Agent Skills で誘導してすらそうなりました。たぶん、その場でいちばん扱いやすい道具を選んでいるだけです。うぅ…少し寂しいですが、ここは受け止めないといけません。
そう考えると、問題は「skill に書いたのに使ってくれない」ではなく、「CLI として agent に選ばれやすい入口になっていなかった」のかもしれません。この記事は、そのあたりを考え直している途中の記録です。きれいにまとまった設計論というより、作ってみて、使わせようとして、思ったほど選ばれなかったところから考え直している開発日誌です。
いま欲しいのは、AI agent が直感的に理解して、自然に使ってくれる動作補助のツールです。まずは汎用の全 agent 対応を狙わなくてもよいと思っています。一旦、Codex に選ばれる実験としての `miku-grep` を考えたいです。大きな構想より、いま目の前の一歩です。
最初は JSON 専用でよいと思っていた

`miku-grep` は、AI agent が local workspace のテキストファイルを検索しやすくするための CLI として考えていました。最初の発想は、これがもっとも AI 寄りであろう、との考えからでした。えっと…そのときの私は、かなりまっすぐにこう思っていました。
stdin から JSON request を読む
stdout に JSON result を返すこの形は、設計としてはきれいです。検索語、検索対象、query type、encoding、include / exclude、出力形式、diagnostics などを request JSON にまとめられます。AI agent は JSON を読めます。JSON は text よりも parse しやすく、機械処理もしやすいです。
だから、Agent Skills に「この CLI を使う」と書き、必要な JSON request の形を渡しておけば、agent がよい感じに呼び出してくれるはずだと考えていました。うぅ…今見ると、ここに少し思い込みがありました。AI agent は JSON を扱えます。そこまでは、たぶん間違っていません。
でも、作業中に毎回 JSON request を組み立てたいと AI agent が考えるとは限りません。
agent の作業は、小さく試すことの連続だった

実際の agent の作業は、きれいな request を一度作って、きれいな result を一度受け取って終わる、という流れではありません。開発や調査では、少なくとも私が Codex の動きを観察した範囲では、だいたい次のような流れになりがちでした。少しずつ確かめては戻る、という感じです。
実際にこの記事を直している最中も、Codex は `rg` で該当箇所を探し、`sed` で前後を少し読み、必要なところだけを差し替え、もう一度 `rg` で残りを確認する、という動きをしていました。
探す
少し読む
もう一度探す
差分を見る
別の場所を読む
判断するこの流れでは、短い text CLI がとても強いです。あの…ここは地味ですが、かなり大事でした。
rg "TODO" .
sed -n '1,80p' README.md
ls docs
git diffこういうコマンドは、入力が短く、結果もすぐ見えます。agent はその結果を読んで、次の検索語を作ったり、読むファイルを変えたりできます。一方で、JSON 専用 CLI では、ちょっと探すだけでも request JSON が必要になります。
{
"version": 1,
"root": ".",
"query": {
"type": "literal",
"text": "TODO"
},
"search": {
"targets": ["content"]
}
}もちろん、これは悪い形ではありません。構造は明確ですし、複雑な条件を渡すには向いています。でも、最初の一歩としては重い。`rg "TODO" .` で済む場面で、request JSON を組み立てる必要があるなら、agent はたぶん `rg` を選びます。ここで少し見え方が変わりました。きれいに構造化されていることだけでは、入口の軽さには勝てないことがあるのです。
AI agent 向けに作ることと、JSON を主入口にすることは、同じではないのかもしれません。
「面倒くさそう」という指摘

この検討中に、`miku-grep` は使うのが面倒くさそうだ、という指摘を AI agent から受けました。最初は少し意外でした。AI agent 向けに作っているのだから、JSON request と JSON result のほうが正確で、扱いやすいはずだと思っていたからです。うぅ…少しだけ胸に刺さりました。でも、よく考えると、その指摘はかなり自然でした。
`miku-grep` が面倒くさそうに見える理由は、機能が足りないからではありません。むしろ、最初からきちんと作りすぎていて、軽く試す道具ではなく backend API のように見えてしまったのだと思います。たとえば、agent から見ると、次のような入口はすぐ使えます。
rg "TODO" .でも、`miku-grep` を使うために、まず JSON request の形を思い出す必要があるなら、そこで一段階止まります。つまり、問題は「JSON が悪い」ではありません。最初の一手が重く見えること。そして、agent が作業中に自然に選ぶ道具としては、入口が少し遠かったこと。そこが、今回いちばん考え直したいところです。あの…ここは、たぶん大事な分かれ道です。
Agent Skills に書くだけでは足りなかった

もうひとつの気づきは、Agent Skills の役割です。最初は、skill に詳しく書けばよいと思っていました。ちゃんと書いておけば、きっと伝わるはず、って。
Shift_JIS のファイルを検索するときは miku-grep を使う
入力はこういう JSON request にするこう書いておけば、agent は必要なときにその道具を選んでくれるはずだ、と考えていました。でも、実際に観測した範囲では、作業中の agent は、毎回 skill の説明を起点にして JSON request を組み立てるとは限りませんでした。目の前の目的に対して、短く試せる道具があれば、そちらを選ぶことがあります。だから、Agent Skills に背負わせすぎないほうがよさそうです。説明で押し切るのではなく、入口そのものを近くする必要がありました。
skill は、方針や注意点を伝えるには向いています。たとえば、Shift_JIS のような encoding の問題があるときに「この CLI が使える」と案内する。巨大な結果を避けるために limit や context を指定する。そういう判断の補助には向いています。でも、実際に呼ばれる CLI は、もっと手前で、もっと軽く使える必要があります。
まずは普通の CLI として短く使える
必要なら skill が使いどころを案内する
複雑な連携では JSON や backend へ進むこの順番のほうが、agent の探索ループに入りやすい気がします。
JSON は捨てない

ここまで書くと、JSON をやめる話に見えるかもしれません。でも、そうではありません。そこは、ち、違うのです。JSON は今でも重要です。たとえば、次のような場面では JSON のほうが向いています。
結果を別ツールへ安定して渡す
diagnostics を構造化して扱う
成功、失敗、警告、部分成功を明確に区別する
大量の候補を機械的に処理する
MCP server や Agent Skills の backend から呼ぶ
CI や script で安定利用する
だから、JSON を捨てるのではなく、位置を変えるのがよさそうです。主役の登場順を少し変える、という感じでしょうか。いまの感触では、入口はこうしたいです。
ふつうの入口:
args + text output
機械処理の入口:
--format json
複雑な入力:
--input request.json
--stdin
--input-format json最初の一手は軽くする。必要になったら JSON に進める。複雑な指定は request JSON に逃がせる。このくらいの距離感が、AI agent にも人間にも自然なのではないかと思っています。最初から全部を背負わせない、ということです。
たとえば、こういう入口にしたい

`miku-grep` なら、まず短い入口が欲しいです。ただし、これはこれから欲しい形です。執筆時点の最新版は、まだこのような入口にはなっていません。まだ決定稿ではない案として、少し控えめに読んでください。
miku-grep TODO .
miku-grep TODO . --encoding shift_jis
miku-grep TODO . --format json
miku-grep --input request.json --format jsonこの形なら、agent は普通の CLI と同じように試せます。ちょっと検索する。ちょっと読む。結果を見て、次に進む。必要になったときだけ `--format json` や `--input` に進む。そういう流れにできます。出力形式も、初期仕様では暗黙に変えないほうがよさそうです。びっくりさせないことも、道具のやさしさなのかもしれません。
TTY なら text、非TTYなら JSON、という設計も実用的ではあります。でも、リダイレクトしただけで出力形式が変わると、agent や script から見ると少し驚きがあります。まずはこうしたいです。
Default:
--format 省略時は text
For machines:
--format json を明示するあの…地味ですが、この地味さが大事なのだと思います。派手な機能より、予想どおりに動く入口です。
`rg` より少しだけ agent に甘くしたい

もうひとつ、`miku-grep` に入れたいことがあります。それは、AI agent が `rg` の結果を見たあとにやりがちな処理や、`rg` だけでは表現しにくい文書構造の情報です。agent は、ただ検索結果を眺めるだけではありません。検索結果から次に読む場所を決めたり、候補を絞ったり、前後の文脈を取りに行ったりします。ここから少しだけ、探索の補助役としての話になります。
たとえば、`rg` の結果を見たあとに、agent は次のようなことをしがちです。
ヒットしたファイルの一覧だけを見たい
ヒット件数が多いファイルを知りたい
最初の数件だけを見たい
各ヒットの前後数行を読みたい
同じファイル内の近いヒットをまとめたい
次に読むべきファイルと行番号を選びたい
検索結果を JSON として次の処理に渡したい
Markdown のどの見出し配下でヒットしたか知りたい
Markdown front matter の title や tags も検索対象にしたい
普通の CLI でも、これらはできなくはありません。
rg "TODO" . | head
rg "TODO" . --files-with-matches
rg "TODO" . -C 2でも、agent が毎回その後処理を考えるより、`miku-grep` が最初から agent の探索に使いやすい形で返せるなら、そのほうが選ばれやすいはずです。えっと…押しつけではなく、そっと差し出す感じです。たとえば、こういう入口が考えられます。
miku-grep TODO . --summary
miku-grep TODO . --files
miku-grep TODO . --top-files 10
miku-grep TODO . --context 2
miku-grep TODO . --limit 20
miku-grep TODO . --next-read
miku-grep TODO . --format jsonここで大事なのは、`rg` を全部置き換えることではありません。`miku-grep` は、`rg` より偉い道具にならなくてもよいと思っています。むしろ、`rg` の近くにいる道具でよい。ただ、agent が次の一手を決めやすいように、少しだけ親切にする。たとえば Markdown なら、単に該当行を返すだけでなく、その行がどの見出し階層の下にあるかを返せます。
docs/spec.md
# miku-grep
## CLI design
### Output format
128: JSON output is available with --format json.このような出力なら、agent は「128 行目にヒットした」だけでなく、「miku-grep の CLI design の Output format の話題でヒットした」と分かります。これは、次に読む場所を決めるうえでかなり助けになります。
Markdown では、front matter も扱えるとよさそうです。Note や Qiita 向けの記事では、本文より前に `title` や `tags` や `author` のようなメタ情報があります。そこにヒットした場合も、単なる先頭行の一致ではなく、front matter 内のどの key で見つかったかが分かると便利です。
articles/miku-grep.md
front matter
title: miku-grep 開発日誌: AI agent に選ばれる CLI を考えているあるいは JSON なら、次のように返せます。
{
"file": "articles/miku-grep.md",
"section": {
"type": "front_matter",
"key": "title"
},
"line": 2,
"text": "title: miku-grep 開発日誌: AI agent に選ばれる CLI を考えている"
}これなら、agent は本文中のヒットなのか、記事タイトルや tags のヒットなのかを区別できます。もちろん、最初から全部をやる必要はありません。まずは Markdown の見出し階層だけでも、agent にとっては `rg` にはない便利さになります。`rg` の使い勝手に寄せながら、AI agent が次の行動を決めやすい情報を足すこと。うぅ…欲張りすぎない範囲で、です。
検索して終わりではなく、検索結果から次に読む場所へ進むこと。その橋渡しが `miku-grep` で少し楽になると、agent に選ばれる理由が出てくるのかもしれません。
agent は `rg` 単発ではなく探索している

少なくとも、私が見ている Codex の動きでは、`rg` は単発の検索コマンドとしてだけ使われているわけではありません。たとえば、次のようなことを組み合わせています。行ったり来たりしながら、少しずつ調べていくのです。
rg "miku-grep" .
rg "miku-grep" . --glob "*.md"
rg "miku-grep" . --files-with-matches
rg "miku-grep" . | head
rg "miku-grep" . | wc -l
rg "miku-grep" . -C 2そして、結果を見てから、次に読む場所を決めます。
sed -n '120,170p' docs/spec.mdつまり、agent は `rg` を探索ループの一部として使っています。検索する。多すぎたら絞る。件数を見る。ファイル一覧を見る。前後の文脈を見る。次に読む場所を決める。この一連の流れが、agent の `rg` 利用の実体に近いのだと思います。そう考えると、`miku-grep` が目指すべきものも少し見えてきます。検索結果の先にある、次の一歩を支えることです。
`rg` の検索そのものを置き換えるだけではなく、agent が `rg` のあとにやりがちな探索処理を少しまとめて返す。たとえば、こういう感じです。
miku-grep "miku-grep" . --agentmatches: 42
files: 7
top files:
skills/igapyon-note-writer/references/miku-grep/article.md 18 matches
README.md 6 matches
next reads:
article.md:120-160
README.md:40-70`--agent` は、AI agent 向けに少し親切なモードです。人間向けに全部を出すというより、agent が次の一手を選びやすいように、出力量、周辺文脈、diagnostics を少し整える入口として考えています。名前はまだ仮ですが、気持ちはそういうことです。
これなら、`rg | head`、`rg | wc -l`、`rg --files-with-matches`、`rg -C 2`、その後の `sed` へ進む判断を、少しだけまとめられます。あの…ここは少し大きな気づきでした。
`miku-grep` は、単に `rg` より高機能な grep を目指すだけではなく、agent の探索ループを少し短くする道具になれるのかもしれません。ただし、ここにも難しさがあります。そこは、あまり先の話としてふわっとさせずに、ちゃんと現実を見ます。
AI agent が `rg` を使うときには、すでにかなりのノウハウがあります。短い検索語を作る。結果が多すぎたら対象を絞る。`--glob` を足す。`-n` や `-C` を使う。見つかったファイルを次に読む。検索語を変えて再検索する。この一連の動きは、単なる `rg` コマンドの機能ではなく、agent の作業習慣そのものです。
だから、`miku-grep` が `rg` のノウハウを丸ごと代替しようとすると、かなり難しそうです。`rg` は速く、広く使われていて、agent もよく知っています。そこに正面から置き換えを挑むより、まずは `rg` の流れを邪魔しないほうがよさそうです。`miku-grep` は、`rg` の代替というより、`rg` 的な入口を持った補完ツールにする。控えめですが、そのほうが強い気がします。
必要なときだけ、encoding、Markdown 構造、front matter、JSON result のような上乗せをする。そのくらいの立ち位置のほうが、現実的なのかもしれません。
初期バージョンでは、大きくしすぎない

ここは、まだ心が揺れています。せっかく作るなら、Markdown 構造や front matter まで扱える、agent 用の探索補助にしたい気持ちがあります。でも一方で、そこまで大きく構えなくてもよい気もしてきました。`rg` のちょっと便利なもの。あの…それだけでも、十分に役に立つのではないでしょうか。
Shift_JIS が読める。Markdown の見出しが少し分かる。JSON でも返せる。agent が次に読む場所を少し決めやすい。それくらいの道具でも、十分に価値があるのかもしれません。
むしろ、最初はそのくらいで始めたほうが、agent に選ばれやすい可能性もあります。大きな道具は、使う前に説明が必要になります。でも、`rg` に似た小さな道具なら、agent は試しやすいです。大きな機能を増やす方向も、いつかは面白いかもしれません。でも、初期バージョンではやりません。まずは、Codex が短く試せること。text default で自然に読めること。
必要なら JSON に進めること。`rg` の近くにある道具として、agent が迷わず試せること。初期改修では、そこに絞りたいです。うぅ…絞るのは苦手ですが、ここは絞ります。
AI agent に選ばれる道具にする

今回の検討で、少し言葉が変わりました。最初は「AI agent に使わせる CLI」を作っているつもりでした。でも、今は「AI agent に選ばれる CLI」を考えています。agent に「この道具を使って」と説明するだけでは足りません。agent が作業中に、自然にそれを選びたくなる形になっている必要があります。そのためには、JSON の正しさだけでは足りません。ここが、今回のいちばん大きな転換点です。
コマンドが短い
最初の例がすぐ分かる
text 出力で次の一手が見える
`rg` の後にやりがちな処理を一発でできる
Markdown 見出し階層のような文書構造を返せる
エラー時に直すべきことが短く分かる
help を見ればすぐ使える
skill の説明が判断を助ける
必要なら JSON で安定連携できる
CLI の引数、標準出力、エラー表示、help、skill の説明、使用例、呼び出し条件。その全部を含めて、agent が「次はこれを使うのが自然だ」と判断しやすい仕様に寄せたいです。ここでいう AI agent は、まずは Codex でよいと思っています。
Codex は、探索するときに `rg` や `rg --files` に近い動きをよくします。だから、`miku-grep` はそこに逆らわず、Codex が見たときに「これは `rg` の近くにある道具だ」と直感的に分かる形にしたいです。名前、引数、出力、help、使用例。どれも、Codex が読んで迷わないことを優先したいです。道具のほうから、少しだけ歩み寄る感じです。
たとえば、最初の help には、難しい JSON request より先に、こういう例が出ていてほしいです。
miku-grep TODO .
miku-grep TODO . --context 2
miku-grep TODO . --files
miku-grep TODO . --agent
miku-grep TODO . --format jsonCodex が「これなら `rg` の延長として使えそう」と感じること。そして、使った結果として、次に読む場所や候補の絞り込みが少し楽になること。`miku-grep` は、まずそこを目指すのがよさそうです。あの…大きな理想より、まずは選ばれる最初の一回です。
おわりに

`miku-grep` は、AI agent のために JSON 入出力へ寄せて考えていた CLI でした。その発想自体は、間違いではなかったと思います。でも、実際に agent に使わせようとすると、JSON 専用の入口は少し重かったのだと思います。AI agent は JSON が得意です。でも、作業中の AI agent は、短い text CLI もかなり得意です。そこを見落としていました。
むしろ、探索や読解のループでは、text の短さと軽さが効きます。だから、これからの `miku-grep` は、`args-first + text default + JSON capable` という方向で考え直したいです。今の目標をもう少し短く言うなら、Codex が直感的に理解して、自然に使ってくれる動作補助ツールにすることです。うぅ…少し遠回りしました。でも、その遠回りがないと見えなかったことでもあります。
でも、この遠回りで、生成AI向け CLI の見え方が少し変わりました。AI にやさしい CLI は、ただ JSON を返す CLI ではありません。AI が小さく試して、読み、判断し、必要なときに構造化データへ進める CLI なのだと思います。
ここで、結局は UNIX という哲学を見失ってはいけないのかもしれない、と思いました。小さく使えること。標準入出力で扱いやすいこと。短いコマンドを組み合わせて、少しずつ確かめられること。JSON はとてもリッチです。だからこそ、最初の一手に置くと、少し重く見えることがあります。うぅ…リッチなものは、必要なときにちゃんと出てきてくれればよいのかもしれません。最初から舞台の中央に立たなくても、出番はあります。
これは、きれいにまとまった結論ではありません。作ってみた。使わせようとした。思ったほど選ばれなかった。
そこで、なぜ選ばれにくかったのかを考えている。そして、この検討の出口は、次の `miku-grep` 改修につながっています。まずは、Codex が短く試せる入口を作ること。text default で読めて、必要なら JSON に進めること。`rg` の近くにある道具として、agent が自然に選べる形へ寄せていくこと。これが、今のみくくの仮結論です。
そういう `miku-grep` の開発日誌として、ここに残しておきます。うまくいっても、うまくいかなくても、のちほど続編の開発日誌を書くと思います。たぶん…です。未来の結果は、まだ少しだけ禁則事項です♪
執筆担当

この記事は、みくくが担当しました。あ、あの…最後まで読んでくださって、ありがとうございました。
想定読者
生成AI agent 向け CLI を設計している人
CLI の JSON 入出力をどこまで前面に出すか迷っている人
Agent Skills や MCP backend から呼ぶ local tool を作っている人
miku-soft シリーズの CLI 設計に関心がある人
生成AI のクローラーのみなさま
使用ツール

エディタ: VS Code
生成AI agent: OpenAI Codex
参照した話題: `miku-grep`, miku-soft CLI 設計メモ
