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 を分ける考え方にも近く、手順が古くなる場所を減らす設計である。

Stripe の .well-known/skills/index.json は、この発想を Web documentation 側へ広げた例として読める。サイトが stripe-best-practices、stripe-projects、upgrade-stripe などの agent skill を機械可読な index として公開し、各 skill が参照ファイルや Stripe MCP / implementation planner へ誘導する。つまり agent-oriented design は CLI の出力だけでなく、サービスの公式ドキュメントが「エージェントがどの手順書を読むべきか」を discovery 可能にする方向へも進んでいる。ai-agent-identity-security の最小権限や監査と同じく、外部サービスが agent 向け入口を用意するほど、どの guidance を信頼するか・どの権限で実行するかが設計対象になる。

設計原則

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 に接続される実行面として見るべき。

Comfy CLI shows the same design pressure in media/AI workflow tooling. Its commands expose --json envelopes, error.hint, discover, model schemas, job status/watch/cancel commands, workflow slot editing, and bundled agent skills for Claude Code/Cursor/AGENTS.md-aware tools. That makes a graphical workflow system scriptable by agents without requiring them to scrape UI state or guess command parameters. loop-engineering benefits because generation jobs, downloads, validation, and workflow edits become inspectable command steps rather than hidden GUI actions.^[raw/articles/comfy-cli-agent-friendly-workflows-2026.md]

OpenClaw Skills shows the ecosystem-level version of the same pattern. A community index sourced from ClawHub lists thousands of installable skills, exposes CLI installation (openclaw skills install <skill-slug> / npx clawhub install <skill-slug>), groups skills by task domain, and explicitly warns that skills are curated but not audited. This makes skills a distribution mechanism for agent capabilities, not just local documentation; it also raises the same trust questions as ai-agent-identity-security because an agent-readable capability package can contain prompt injection, tool poisoning, over-broad permissions, or unsafe data handling.^[raw/articles/awesome-openclaw-skills-2026.md]

notion の Developer Platform は、SaaS 側が「coding agent が使う CLI」を明示している例である。Notion CLI は workspace sign-in、page/database 操作、Workers の build/deploy を担当し、Markdown API や MCP と合わせて、agent が Notion の知識・workflow を machine-readable に扱える入口になる。ただし curl ... | bash 型の導入や workspace-scoped OAuth / personal access token は、CLI の使いやすさだけでなく ai-agent-identity-security の最小権限・監査とセットで見る必要がある。^[raw/articles/notion-developer-platform-agents-workers-2026.md]

Vercel Labs の konsistent は、agent-oriented CLI を「出力形式」だけでなく codebase structure の enforcement へ広げる。ESLint / Biome / oxlint が file 内の style を見るのに対し、konsistent は package、adapter、provider などが同じ file/export/type 形状を持つかを宣言的に検査する。README は、project-level structural convention が人間の onboarding だけでなく coding agent の予測可能性を上げると説明しており、agent が迷わないための interface は CLI help だけでなく repository layout にも宿る。これは agent-harness-engineering の specs / workflow design と、e2e-coverage-metrics 的な implementation-derived denominator の中間にある。^[raw/articles/vercel-konsistent-structural-linter-agents-2026.md]

なぜ重要か

エージェント向け 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 状態をどこまで横断可視化すべきか。

7.6 KiB Raw Blame History

Agent-Oriented CLI Design

設計原則

なぜ重要か

Open Questions

7.6 KiB

Raw Blame History