add

2026-06-30 22:22:00 +09:00
parent 9ad671521d
commit 87eacd39b2
66 changed files with 10280 additions and 105 deletions
@@ -0,0 +1,35 @@
+---
+title: Agent-Oriented CLI Design
+created: 2026-06-30
+updated: 2026-06-30
+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]
+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 を分ける考え方にも近く、手順が古くなる場所を減らす設計である。
+
+## 設計原則
+
+- **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 状態をどこまで横断可視化すべきか。