agentic-cli-design

エージェント向け CLI 設計

概要

エージェント向け CLI 設計は、CLI を「人間がターミナルで操作するためのツール」ではなく、LLM／エージェントが安全、確実、かつ再現性をもって呼び出せるプロトコル／APIとして捉える設計思想です。

成功の基準は、エージェントが CLI を次のように操作できることです。

• 迷わずに（オプションが明示されている）
• 問題を起こさずに（デフォルトで安全）
• 行き詰まらずに（非対話型で、タイムアウト／再試行の方針がある）
• 繰り返し（冪等で、再実行に耐えられる）
• 自己修復しながら（観測可能で、自己説明的である）

このスキルでは、エージェント向けの CLI ツールを設計、評価するための包括的なフレームワークを提供します。

基本的な定義

エージェント向け CLI 設計＝LLM／エージェントが、非対話型で、繰り返し実行され、失敗しやすい環境において、安全かつ確実にコマンドを実行できるようにする CLI の設計原則です。

人間にとっての「使い心地」を最適化するのではなく、機械が読み取り、判断し、再実行し、復旧できることを最適化します。

7 つの原則

P1. 機械可読（主要な出力形式）

機械可読な出力を、人間が読みやすいテキストではなく、主要なインターフェイスとします。

• --json／--output json|yaml|text を主要なオプションとして提供します
• 明確に分離します：stdout=結果／stderr=ログ・進行状況（混在させない）
• エラーも構造化します（できれば JSON）
• スキーマの安定性を保ちます（schemaVersion で破壊的変更を管理します）

使用する場面：すべての CLI コマンドで、構造化出力をサポートする必要があります。

P2. デフォルトで非対話型

対話型プロンプトをデフォルトの動作にしないでください。

• 対話型プロンプトを前提にしません
• --yes／--force／--no-confirm／--non-interactive フラグを提供します
• TTY のない環境（CI、ジョブランナー）でも正常に完了できるようにします

使用する場面：ユーザー入力を求める可能性があるすべてのコマンドです。

P3. 冪等で再実行可能

同じ結果を得られるよう、コマンドを複数回実行しても安全にします。

• 送信／作成操作で dedupe-key／client-request-id を受け付けます
• 「すでに存在する」場合の動作を設定可能にします：--if-exists skip|update|error
• 取得には明示的なページネーションを使用します：--limit --cursor --all

使用する場面：すべての書き込み操作またはデータ取得コマンドです。

P4. デフォルトで安全

破壊的な操作には明示的な確認を必須にします。

• 破壊的な操作では --dry-run／--confirm <id> をサポートします
• 削除には --force などを必須にします（デフォルトでは誤操作を防ぎます）
• 権限／スコープを最小限にし、権限が不足している場合は「次に行う手順」を返します

使用する場面：データを変更または削除するすべてのコマンドです。

P5. 観測可能でデバッグしやすい

操作を追跡可能かつデバッグ可能にします。

• --verbose／--debug／--log-format json を提供します
• 相関 ID として --trace-id を受け付けます
• 自動復旧に向けて、終了コードを分類します：
  • 0：成功
  • 2：無効な引数
  • 3：認証／権限
  • 4：再試行可能（レート制限、一時的なエラー）

使用する場面：すべてのコマンドで、可観測性に関するフラグをサポートする必要があります。

P6. コンテキスト効率

LLM エージェントのトークン／コンテキスト消費を最小限に抑えます。

• --fields/--select（射影）
• --output ndjson（ストリーミング）
• デフォルトは概要とし、詳細は get／--include-* で明示的に取得します
• サーバー側の豊富なフィルタリング（since/until/query/type...）

使用する場面：大規模なデータセットや詳細情報を返すコマンドです。

P7. 内省可能（自己記述型 CLI）

CLI 自体が、機械可読形式で仕様を出力できます。

MCP ツールにはスキーマ定義がありますが、CLI はブラックボックスであることが少なくありません。解決策は、CLI 自体が仕様を出力することです。

• commands --json（コマンドと引数を一覧表示）
• schema --command ... --output json-schema（コマンドごとの JSON Schema）
• --help --json（使用例、終了コード、エラー用語）
• install-skills（<project dir>/skills から CLI 自身のエージェントスキルを出力／インストール）
• --output json のトップレベル固定フィールド：
  • schemaVersion、type、ok

install-skills の推奨動作：

• 任意のサードパーティ製スキルではなく、CLI 自身の使用方法を説明するスキルをインストールします
• <project dir>/skills からスキルのソースを読み込みます
• デフォルトのインストール先：./.agents/skills
• install-skills --global：~/.agents/skills
• install-skills --claude：./.claude/skills
• install-skills --claude --global：~/.claude/skills

使用する場面：エージェントが検出でき、自己文書化された CLI が必要な場合です。

リファレンスドキュメント

このスキルには、トピック別に整理された詳細なリファレンス資料が含まれています。

references/principles.md

7 つの原則それぞれについて、具体例、実装ガイダンス、ベストプラクティスを交えて詳しく説明します。

使用する場面：特定の原則や実装例について、詳しく理解する必要がある場合です。

references/scorecard.md

7 つの原則に照らして CLI の設計をレビューするための完全なチェックリストです。各原則には、評価に使える具体的なチェック項目があります。

使用する場面：既存の CLI がエージェントに適しているかレビューする場合や、新しい CLI の設計を検証する場合です。

references/templates.md

以下の具体的なテンプレートです。

• JSON レスポンス形式（成功／失敗）
• 終了コードの規約
• 内省コマンドのパターン
• 認証ステータスのレスポンス

使用する場面：JSON 出力、エラー処理、自己記述などの機能を実装する場合です。

references/anti-patterns.md

エージェントとの互換性を損なう、以下を含む一般的な失敗パターンです。

• 標準出力と標準エラー出力の混在
• 一貫性のない JSON スキーマ
• デフォルトでの対話型動作
• 安全でない破壊的操作
• コンテキストの爆発
• ブラウザーのみでの認証

使用する場面：エージェントの失敗をトラブルシューティングする場合や、よくある落とし穴を避ける場合です。

クイックスタート

新しい CLI の設計

1. 上記の 7 つの原則を確認します
2. 設計チェックリストとして references/scorecard.md を使用します
3. references/templates.md のパターンを使って実装します
4. references/anti-patterns.md にあるパターンを避けます

既存 CLI のレビュー

1. references/scorecard.md に沿って確認します
2. 原則の適用範囲にある不足点を特定します
3. 現在の問題について references/anti-patterns.md を確認します
4. エージェントのユースケースに基づいて修正の優先順位を決めます

エージェントスキルの作成

CLI ツール向けのエージェントスキルを作成する場合は、以下を含めます。

• タスク固有のレシピ（最小限のコマンドシーケンス）
• ガードレール（ドライラン → 確認 → 実行のパターン）
• 入出力の型（一般的な成功／失敗時の JSON）
• エラーからの復旧手順（rate limit、auth_required など）
• 推奨デフォルト値（--json／--non-interactive／--limit）
• CLI が <project dir>/skills から自身のスキルをインストールできるようにする install-skills のフロー

認証に関する考慮事項

OAuth／ヘッドレス認証の場合：

• 最初の選択肢として Device Authorization Grant（RFC 8628）を優先します
• エージェントが前提条件を確認できるよう、auth status --json を提供します
• ヘッドレス環境への移行に備えて、auth export／auth import をサポートします
• --non-interactive モードでは、プロンプトを表示せず、エラーと次の手順を返します

認証レスポンスの形式については、references/templates.md を参照してください。

CLI のスコアリング

比較しやすいよう、各原則を 0／1／2 点で評価できます。

• 0：未実装
• 1：一部実装
• 2：完全に実装

最高スコア：14 点（2 点 × 7 原則）

詳細な評価基準については、references/scorecard.md をご覧ください。

関連する概念

• MCP（Model Context Protocol）：スキーマ付きのツール定義を提供します。Agentic CLI Design では、スタンドアロンの CLI も同様に検出しやすくします
• Agent Skills：エージェントに安全な CLI の使用パターンを教えるドキュメントレイヤーです
• Infrastructure as Code：冪等性と宣言型の原則を共有します
• 12-Factor Apps：設定と可観測性の原則を共有します

実際の使用例

これらの原則を示す、設計の優れた CLI：

• GitHub CLI（gh）：優れた --json サポートと非対話型フラグ
• kubectl：強力な冪等性、宣言型の apply、ドライランのサポート
• AWS CLI：包括的な --output json、ページネーション、フィルタリング

このスキルを使用する場面

次の場合にこのスキルを使用してください。

1. エージェントや自動化での使用を想定した新しい CLI を設計する
2. 既存の CLI を改善して、エージェントが使いやすくする
3. CLI ツール用の Agent Skill を作成する
4. CLI ツールでのエージェントの失敗をデバッグする
5. 本番環境への対応状況について CLI の設計をレビューする
6. エージェントのワークフローに使用する CLI ツールを選ぶ

このスキルを使用しない場面

次の場合には、このスキルは過剰な場合があります。

• 個人利用向けの単発スクリプト
• 人間による対話型の使用のみを想定した CLI
• 本番環境での使用を想定していないプロトタイプ
• 本質的に対話型のワークフローを持つツール（テキストエディター、REPL など）

さらに読む

• references/principles.md - 各原則の詳細
• references/scorecard.md - 評価チェックリスト
• references/templates.md - 実装テンプレート
• references/anti-patterns.md - 避けるべきこと