Agent-Oriented CLI Design

Agent-oriented CLI design は、人間が目で読んで試行錯誤する端末道具ではなく、Claude Code などの loop-engineering が安全に呼び出し、結果を機械的に判断し、次の行動へ進めるための CLI 設計。Zenn の「AI エージェント向け CLI ツール」記事は、Claude Code 用の横断検索 CLI を Go で作った経験から、人間向け CLI と違う判断基準を整理している。

重要なのは、エージェントに「推測させない」こと。使い方は wiki や skill 側へ長く写すのではなく、CLI 自体に skill や help サブコマンドとして同梱し、スキーマや出力の意味が実装と一緒に更新されるようにする。これは wiki-maintenance-loop の raw/source と synthesis を分ける考え方にも近く、手順が古くなる場所を減らす設計である。

設計原則

JSON first: 人間向けの整形テキストではなく、既定で構造化 JSON を返す。結果には id、title、snippet、source_url、synced_at、is_stale など、エージェントが次の判断に使う材料を入れる。
Actionable errors: index is missing だけで止めず、run super-cli-tool sync のように次のコマンドを直接書く。小さいモデルほど推測の余地を減らす効果が大きい。
Search then read: 重い本文取得と軽い候補検索を分ける。まず search で候補を絞り、必要なものだけ read する方が、トークン・時間・判断負荷を抑えやすい。
Defaults over flags: --sources や --discover のような細かい選択肢を増やすより、よく使う安全な既定値へ寄せる。フラグが多いほど help が長くなり、エージェントの分岐も増える。
Governance hooks: Microsoft Learn の agent architecture / SDLC module は、agent task を input / output / success criteria で構造化し、PR template、checks、CODEOWNERS、rules、environment gate、observability、tool governance、secret boundary を運用設計へ入れることを強調する。CLI も単独の便利道具ではなく、ai-agent-identity-security や PR governance に接続される実行面として見るべき。

なぜ重要か

エージェント向け CLI は、単に「CLI を LLM から呼べるようにする」だけでは足りない。出力が曖昧だったり、エラーが不親切だったり、状態の鮮度が返らなかったりすると、agent loop は誤った仮定のまま進む。逆に、CLI が状態・出典・次アクション・失敗理由を明示すれば、loop-engineering の verification と persistence が自然に強くなる。

この設計は Hermes の skill にも当てはまる。skill は長い操作説明を抱え込むより、実際の CLI が --help や agent-guide を返せるならそこへ誘導し、skill 側は「いつ使うか」と「安全境界」を中心に保つ方が、ツール更新とのずれを減らせる。

Open Questions

CLI 側の agent-guide は人間向け help と別にすべきか、それとも同じ help を機械可読に拡張すべきか。
JSON schema、exit code、retryability、rate-limit 情報をどこまで標準化すれば、複数 agent / tool 間で再利用できるか。
abtop のような operator UI は、個々の CLI 実行ログや stale 状態をどこまで横断可視化すべきか。

3.8 KiB Raw Blame History

Agent-Oriented CLI Design

設計原則

なぜ重要か

Open Questions

3.8 KiB

Raw Blame History