---
source_url: "https://zenn.dev/chot/articles/dca4889fa27d27"
ingested: 2026-06-30
sha256: 61ba17cb1e95b943c26f777987b2778df6cd0c9c050c4a03ddcbbd6ba6b52c53
discovered_from:
  platform: discord
  channel_id: "1028287639918497822"
  channel_name: "chat"
  message_id: "1521485941267763221"
  author_id: "890908900520505354"
  posted_at: "2026-06-30T12:01:56.240000000Z"
  message_excerpt: "https://zenn.dev/chot/articles/dca4889fa27d27"
---

# はじめて AI エージェント向けの CLI ツールを作ってみて気づいたこと

最近、Claude Code から使うことを前提にした小さな CLI ツールを Go でつくりました。
きっかけは「過去に似た実装がないか、複数のリポジトリを横断して探したい」という場面がちょこちょこ出てきたことです。
GitHub を毎回探しに行くのが地味に大変だったので、自然言語で投げたら良い感じに探してくれるとうれし〜と思ったのがはじまりでした。
で、実際につくってみると人間向けの CLI とは違う設計判断があり面白いな〜と思ったので、気づいたことをまとめてみます。
## 
1. Skill の内容は CLI への参照だけに留めて、使い方は CLI に同梱する
Claude Code 用に Skill を書くとき、ツールの説明をこんな感じで Skill ファイルに書きたくなります。
`---
name: super-cli-tool
description: ...
---
super-cli-tool は以下のように使います
- `super-cli-tool search <query>` で検索
- `--limit N` で件数指定
- `super-cli-tool read <id>` で詳細取得
- 結果の JSON は results[] に入っていて...
`
これだと、CLI 側の更新によって情報が古くなる場合があります。
Skill はリポジトリに含めてコミットされる可能性もあるので、今度はどうメンテするかを考える必要が出てきますね。
結論として、「使い方は CLI に同梱して、Skill はこの CLI ツールの存在と使い方の見方のみにする」のが賢いかも！と個人的には思いました。
ヘルプの見方を載せるだけでも十分ですが、`agent-browser` のように、CLI 側に「AI エージェント向けの詳細ガイドを出すサブコマンド」を生やすとより良さそうです。
`$ super-cli-tool skill
# super-cli-tool AI エージェント向け使い方ガイド
あなたは Claude Code セッション内で動くアシスタント。
複数のデータソースから「過去に似た実装事例があるか」を super-cli-tool で調べる。
## 基本フロー
1. クエリを英語化（必要に応じて複数試行）
- "サムネ helper" → "thumbnail" "thumbnail helper" "thumbnail renderer"
2. super-cli-tool search "<query>" --limit 5
- 結果 JSON の results[].id / title / snippet を読む
- 詳細が必要な候補だけ super-cli-tool read "<id>" で取得する
...
`
Skill ファイル本体に書くのは「このツールがあるよ、詳細は `super-cli-tool skill` を読んでね」という内容だけです。
`---
name: super-cli-tool
description: 複数のデータソースを横断検索する CLI。過去の実装事例や関連情報を探したいときに使う。
---
super-cli-tool CLI が使えます。 詳しい使い方は `super-cli-tool skill` を実行して読んでください。
`
この形にすると、CLI のバージョンアップで使い方が自動的に同期されるので、Skill 側を直す必要がほぼなくなります。
CLI 側に寄るのが良い感じですね。
description は Skill の選択に使われるので、丁寧目に書くとなおよしです。
## 
2. JSON 出力をデフォルトにする + 結果に「AI エージェントが判断に使う情報」を埋め込む
たとえば GitHub CLI だと、テキスト出力がデフォルトで `--json` はオプション扱いです。
`# デフォルトはテキスト
gh repo list
# JSON が欲しいときだけ明示する
gh repo list --json name,url
`
人間が使うならこれが自然ですが、AI エージェントに使ってもらうことを前提にすると、逆の方が便利でした。
加えて、結果には「AI エージェントが次のアクションを決める材料」を一緒に埋めておくのがポイントでした。
`{
"query": "...",
"file_results": [
{
"id": "example-1",
"title": "FooBar の実装例",
"path": "src/foo/bar.tsx",
"snippet": "export const FooBar = ...",
"source_url": "https://github.com/.../src/foo/bar.tsx",
"last_updated_at": "2026-05-28"
}
],
"synced_at": "2026-06-26T15:49:13+09:00",
"is_stale": false
}
`
- 
`synced_at`: いつ同期されたか
- 
`is_stale`: 7 日以上経っていたら `true`（Skill 側で、古かったら「sync した方がいいですよ」と促してねって書いてます）
- 
`source_url`: ユーザーに回答するときにそのまま貼れるリンク
「これを見たエージェントが次に何をするか」を見据えて、必要な情報を先に渡しておくという感じです。
## 
3. エラーメッセージに「次のコマンド」を書く
CLI ツールに限らず AI エージェントに見せるエラーメッセージには、具体的な次のアクションを書くようにしています。
人間なら以下のメッセージでも「インデックスを作り直せばよさそう」と察しがつきます。
`[super-cli-tool ERROR] index is missing or outdated
`
なんですが AI エージェントだと、ここから「じゃあどのコマンドを叩けばいいのか」を毎回推測することになります。
なので、直し方のコマンドまでそのまま書いてあげると、推測のステップを 1 つ減らせてやさしいかなと思います。
`[super-cli-tool ERROR] index is missing or outdated
→ run `super-cli-tool sync` to rebuild the index
`
Claude Opus などのフロンティアモデルではなく、小さいモデルに使わせてみて改善を重ねると、LLM にやさしいツールが作れるのでおすすめです。
特に広く公開しないものだとエラーメッセージは適当にしてしまいがちなんですが、たとえ人間が使う場合でも丁寧である分には困らないのでこれからはちゃんと書こうと思いました…。
## 
4. 重い処理と軽い処理を分ける
AI エージェント向けの CLI では、1 つのコマンドで全部を返そうとするより、軽い確認と重い取得を分けた方が扱いやすいなと思いました。
検索系の CLI ならこんな感じです。
- 
search: ローカルのインデックスを検索して、候補だけ返す
- 
read: 必要になったファイルや詳細情報だけ取得する
最初から本文や詳細データを全部返すと、遅くなるうえに出力も大きくなります。
AI エージェントにとっても読む情報が増えすぎて、どこを見ればいいのか判断しづらくなりがちです。
一方で、「まず search で候補を絞る → 必要なものだけ read する」という形にしておくと、各コマンドの責務がシンプルになります。
AI エージェントはこういう小さなステップの繰り返しが得意なので、CLI 側が 1 ショットで完璧な答えを返さなくても意外となんとかなります。
むしろ、段階的に探索できる余地を残しておく方が良さそうでした。
## 
5. フラグは増やさず、なるべくデフォルトで完結するように
最初は `sync --discover` `--sources a,b` `--owner my-org` と、複数のフラグを用意していました。
ただ、AI エージェントに使わせる前提だと、毎回細かいオプションを選ばせるより、よく使う設定をデフォルトに寄せた方が安定しました。
`# 必要なデータを同期する
super-cli-tool sync
# 強制的に同期し直す
super-cli-tool sync --full
`
フラグが多いとヘルプの出力も長くなって、その分トークンも消費します。
選択肢が少ない方が AI エージェントも判断に迷わないので、オプションはミニマムに保つのが良さそうです。
オプションをモリモリ増やしたくなる気持ちを抑えるのが難しいところです。
## 
さいごに
「AI エージェント専用とはいえ、賢いし人間向けと同じでええやろ〜」と思っていたのですが、実際につくってみると意外とうまくいかないことがありました。
人間向けに作るときとは違う設計判断がいくつも出てきて、なかなか面白かったです。
AI エージェントがつよくなってきた今、こういった CLI ツールをつくる機会もふえていきそうですね 🤖