cli-for-agents

エージェントに使いやすい CLI 設計のベストプラクティス

人がプロンプトで入力する場合だけでなく、AI エージェントやスクリプトを対象としたコマンドラインインターフェースの設計・レビュー基準です。人間向けの CLI は、対話型プロンプト、最初に表示される大量のドキュメント、コピー＆ペーストできる例のないヘルプテキスト、修正方法が示されないエラーメッセージ、ドライランモードの欠如などによって、エージェントの利用を妨げることがよくあります。このスキルでは、影響範囲の大きさに応じてルールに優先順位を付けています。「エージェントがこの CLI をまったく使えない」（CRITICAL）から「エージェントがヘルプをもう一度読む必要がある」（MEDIUM）までを対象とします。

このスキルは、新しい CLI の構築時にも、既存の CLI がエージェントに使いやすいかレビューする際にも活用してください。

このスキルには、8 つのカテゴリにわたる45 個のルールが含まれています。

適用するタイミング

以下の場合に、これらのガイドラインを参照してください。

• あらゆるサブコマンドの --help テキストを作成するとき
• 新しいフラグ、引数、サブコマンドを設計するとき
• エラーメッセージや終了コードを作成するとき
• ドライランや確認が必要な破壊的操作を追加するとき
• 対話型プロンプトとフラグのみの入力方式のどちらを選ぶか決めるとき
• エージェントがコマンドを連結できるよう、成功時の出力を設計するとき
• 既存の CLI で、ヘッドレス環境での使いやすさが損なわれていないかレビューするとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	非対話型操作	CRITICAL	interact-
2	ヘルプテキストの設計	HIGH	help-
3	エラーメッセージ	HIGH	err-
4	破壊的操作の安全性	HIGH	safe-
5	入力処理	HIGH	input-
6	出力形式	MEDIUM-HIGH	output-
7	冪等性と再試行	MEDIUM-HIGH	idem-
8	コマンド構造	MEDIUM	struct-

注：help-examples-in-help は、HIGH の help- カテゴリに属しますが、CRITICAL と評価されています。具体的な問題である「例のないヘルプテキスト」があると、ほかのヘルプルールがすべて意味をなさなくなるためです。カテゴリのラベルは、最悪のケースではなく平均的な影響度を表します。

クイックリファレンス

1. 非対話型操作（CRITICAL）

• interact-flags-first — すべての入力をまずフラグで指定できるようにし、プロンプトは TTY の場合に限って代替手段として使用する
• interact-detect-tty — プロンプトを表示する前に isatty() を確認する
• interact-no-arrow-menus — 矢印キーで操作するメニューを、フラグで選択する方式に置き換える
• interact-no-input-flag — 非対話型モードを強制する --no-input をサポートする
• interact-no-timed-prompts — 時間制限のあるプロンプトや、任意のキー入力を求める画面を使用しない
• interact-no-hang-on-stdin — TTY が接続されている場合、標準入力で処理を停止しない

2. ヘルプテキストの設計（HIGH）

• help-examples-in-help — すべての --help に、コピー＆ペーストできる例を含める
• help-per-subcommand — すべてのサブコマンドが、それぞれ独自の --help を提供する
• help-no-flag-required — 引数なしで実行された場合にヘルプを表示する
• help-layered-discovery — トップレベルのヘルプを、操作の手引きとなる索引にする
• help-flag-summary — すべてのフラグについて、短縮形と長形式の両方を記載する
• help-suggest-next-steps — ヘルプと成功時の出力で、次に実行するコマンドを提案する

3. エラーメッセージ（HIGH）

• err-exit-fast-on-missing-required — 必須フラグが指定されていない場合は、すぐに終了します
• err-actionable-fix — すべてのエラーメッセージに具体的な修正方法を含めます
• err-stderr-not-stdout — エラーは stdout ではなく stderr に出力します
• err-non-zero-exit-codes — 異なる失敗には、それぞれ異なるゼロ以外の終了コードを使用します
• err-include-example-invocation — エラーには正しい実行例を含めます
• err-no-stack-traces-by-default — スタックトレースは --debug モードでのみ表示します

4. 破壊的操作の安全性（HIGH）

• safe-dry-run-flag — すべての破壊的なコマンドに --dry-run を用意します
• safe-force-bypass-flag — 確認をスキップするための --yes ／ --force を用意します
• safe-confirm-by-typing-name — 元に戻せない操作では、リソース名の入力を必須にします
• safe-no-prompts-with-no-input — --no-input が設定されている場合は、決してプロンプトを表示しません
• safe-idempotent-cleanup — 削除対象がすでに存在しない場合は、正常終了します
• safe-crash-only-recovery — 複数ステップのコマンドは、クラッシュ後の復旧のみで対応できるよう設計します

5. 入力処理（HIGH）

• input-accept-stdin-dash — stdin と stdout のファイル名として - を受け付けます
• input-flags-over-positional — 位置引数より名前付きフラグを優先します
• input-stdin-for-secrets — シークレットは stdin またはファイルから受け付け、フラグの値としては受け付けません
• input-env-var-fallback — 一般的なフラグを環境変数でも受け付けます
• input-no-prompt-fallback — フラグが指定されていない場合に、プロンプトへフォールバックしません

6. 出力形式（MEDIUM-HIGH）

• output-json-flag — 安定した機械可読形式の出力を得るために --json を用意します
• output-ndjson-streaming — 大量の結果は NDJSON としてストリーミングします
• output-bounded-by-default — --limit と --all を使い、デフォルトの出力量に上限を設けます
• output-machine-ids-on-success — 成功時には「完了しました」だけでなく、後続処理に渡せる値を返します
• output-respect-no-color — NO_COLOR が設定されている場合、または非 TTY の場合は、ANSI カラーを無効にします
• output-no-decorative-only — 状態を伝える手段として、装飾的な出力のみに頼らないようにします
• output-one-record-per-line — grep しやすい人間向けの出力では、1 行につき 1 レコードにします

7. 冪等性と再試行（MEDIUM-HIGH）

• idem-retry-safe — 同じコマンドを 2 回実行しても安全になるようにします
• idem-create-or-skip — 作成コマンドは、対象がすでに存在する場合にスキップします
• idem-stable-output-on-skip — 操作を実行した場合もスキップした場合も、同じ形式の出力を返します
• idem-state-reconciliation — 差分を適用する方式より、「状態を確保する」セマンティクスを優先します
• idem-stable-identifiers — ID を自動生成するのではなく、ユーザー指定の名前を受け付けます

8. コマンド構造（中）

• struct-resource-verb — リソースと動詞を組み合わせた一貫性のあるコマンド形式を使用する
• struct-flag-order-independent — サブコマンドとの位置関係にかかわらず、フラグを解析する
• struct-no-hidden-subcommand-catchall — 不明なサブコマンドに対する包括的なハンドラーを避ける
• struct-standard-flag-names — 標準的なフラグ名（--help、--version、--verbose、--quiet）を使用する

使用方法

新しい CLI を構築する場合

CRITICAL から始めて、順に確認してください。最初の 2 つのカテゴリ（interact- と help-）は必須です。ここに含まれるルールに 1 つでも違反すると、ほかの部分がどれほど優れていても、エージェントは CLI を使用できません。その後、err-、safe-、input- の順に確認してください。実際の利用で最も問題が発生しやすいのはこのカテゴリです。output-、idem-、struct- は、呼び出しを重ねるほど効果が積み重なる仕上げの項目です。

既存の CLI をレビューする場合

次のチェックリストを優先順位の高い順に確認してください。

1. 非対話型の実行経路 — すべてのサブコマンドを --no-input 付き、または </dev/null を指定して実行し、ハングするものがないか確認する
2. 階層化されたヘルプ — mycli --help はサブコマンドのみを一覧表示しますか。それともすべての情報を出力しますか。
3. --help に記載された使用例 — すべてのサブコマンドのヘルプは、実行可能な Examples セクションで終わる必要があります
4. 実行コマンドを含むエラーメッセージ — すべてのエラーで、呼び出し元にどのフラグを追加すべきか正確に伝えていますか。
5. stdin／パイプラインの仕様 — 出力を入力にパイプできますか。- は stdin を意味しますか。
6. 終了コード — 使用方法のエラー（2）、実行時エラー（1）、一時的なエラー（69）は区別されていますか。
7. ドライラン — 破壊的なコマンドにはすべて --dry-run（または同等の機能）がありますか。
8. 確認の省略 — 破壊的なコマンドにはすべて --yes／--force がありますか。
9. 一貫したコマンド構造 — service list、deploy list、config list はすべて存在し、同じ方法で動作しますか。
10. 構造化された成功時の出力 — deploy は、エージェントが次に使用できる deploy_id を返しますか。

個別ルール

詳しい説明とコード例については、個別のリファレンスファイルを参照してください。

• セクション定義 — カテゴリ構造と影響レベル
• ルールテンプレート — 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報