--- title: Agent-Oriented CLI Design created: 2026-06-30 updated: 2026-07-02 type: concept tags: [agent, cli, dev-tool, workflow, quality] sources: [raw/articles/agent-oriented-cli-zenn-2026.md, raw/articles/microsoft-learn-agent-architecture-sdlc-2026.md, raw/articles/stripe-well-known-agent-skills-index-2026.md, raw/articles/comfy-cli-agent-friendly-workflows-2026.md, raw/articles/awesome-openclaw-skills-2026.md, raw/articles/notion-developer-platform-agents-workers-2026.md, raw/articles/vercel-konsistent-structural-linter-agents-2026.md] confidence: medium --- # Agent-Oriented CLI Design Agent-oriented CLI design は、人間が目で読んで試行錯誤する端末道具ではなく、Claude Code などの [[loop-engineering|agent loop]] が安全に呼び出し、結果を機械的に判断し、次の行動へ進めるための 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 ` / `npx clawhub install `), 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 状態をどこまで横断可視化すべきか。