エージェントネイティブCLIの設計：AI時代のための10の原則

何十年もの間、コマンドラインインターフェース（CLI）は端末にいる人間を主なユーザーとして設計されてきました。視覚的な整列、ANSIカラー、対話的プロンプトといった、人間には直感的な要素を最適化してきましたが、これらはしばしばAIエージェントの障壁となります。エージェントがますますAPIの主要な利用者になるにつれ、設計哲学は変わらなければなりません。

Trevin Chow は最近、「エージェントネイティブCLI」のフレームワークを提案しました。これは彼自身の取り組みと、Cloudflare や HeyGen といった企業の実装に基づくものです。核心となる主張はシンプルです：エージェント向けに設計すれば、結果として得られる厳格さと一貫性が人間にも利益をもたらす、ということです。

Tier 1: エージェントを壊さない

第一層の原則は防御的設計に焦点を当てます。これらはエージェントがハングしたり、無限ループに陥ったり、黙って失敗したりしないようにするための基本要件です。

1. デフォルトで非対話的

エージェントは「本当に実行しますか？ [y/N]」といったプロンプトに答えることができません。コマンドが入力待ちでハングした場合、エージェントは単に停止します。

  • The Standard: プロンプトが出る可能性のあるすべてのコマンドは --no-input または --yes フラグを持つ必要があります。
  • Optimization: Cloudflare は破壊的なバイパスに --force を標準化し、予測可能な語彙を維持するために --skip-confirmations を明示的に禁止しています。

2. 構造化された解析可能な出力

人間はテーブルが好きですが、エージェントは確実に抽出できるデータを必要とします。

  • The Standard: データを返すすべてのコマンドに --json フラグを提供します。
  • Optimization: 厳格な一貫性を保ちます。--format=json と --output json を混在させないでください。データは stdout、診断情報は stderr を使用します。

3. 教える・列挙するエラー

「invalid visibility」のようなエラーはエージェントにとって行き止まりです。「--visibility は public, private, unlisted のいずれかである必要があります」というエラーであれば、エージェントは1回のリトライで自己修正できます。

  • The Standard: 列挙型やスキーマに対する入力が拒否された場合、エラーメッセージに有効な値の集合を直接示します。

4. 安全なリトライと明示的な変更境界

エージェントは頻繁にリトライします。冪等性がなければ、リトライされた「create」コマンドは重複したリソースを生み出します。

  • The Standard: 冪等性トークンまたは自然キーを使用します。
  • Optimization: 重要な操作には --dry-run を実装し、破壊的なアクションは明示的でデフォルトでないフラグが必要であることを保証します。

5. 制限された応答

無制限の出力はトークンを浪費し、エージェントのコンテキストウィンドウを超えてしまう可能性があります。

  • The Standard: すべてのリスト系コマンドでページネーション、制限、フィルタリングを実装します。
  • Optimization: エージェントに次のクエリを絞り込む方法を明示的に教えるトランケーションメッセージを提供します（例："add --limit=N to see more"）。

Tier 2: エージェントを強化する

CLI が安定したら、次の目標は使用頻度が高まるにつれてより有用にすることです。この層は手動コーディングよりもコード生成やスキーマで実装するのが最適なことが多いです。

6. クロスCLI語彙の一貫性

エージェントは CLI の動作について一般化されたモデルを構築します。多くのツールが get を使用しているのに、あなたのツールが info を使用していると、エージェントはそれを把握するためにトークンとリトライを消費します。

  • The Standard: コミュニティの慣例に従います（例：get、list、create、update、delete）。
  • Optimization: スキーマ層で機械的に強制し、人間のレビューによって生じる「スイスチーズ」的な一貫性の欠如を防ぎます。

7. 三層インスペクション

段階的なヘルプ探索だけではエージェントには不十分です。ツールの機能を機械可読なマップとして提供する必要があります。

  • Layer 1: 人間向けの標準 --help。
  • Layer 2: agent-context — CLI の全体構造を記述したバージョン管理された機械可読 JSON。
  • Layer 3: スキルマニフェスト（例：SKILL.md）— エージェントに操作を複雑なワークフローに組み合わせる方法を教える長文プローズ。

8. 非同期対応実行

エージェントに非同期ジョブ用のポーリングループを書かせることはトークンを大量に消費し、エラーが起きやすくなります。

  • The Standard: 完了までブロックする --wait フラグを提供します。
  • Optimization: ローカルジョブ台帳（例：~/.cli/jobs.jsonl）を維持し、エージェントがポーリング途中で切断された場合でも、次回の呼び出しで新しいジョブを開始せずに進行中のジョブを復元できるようにします。

9. プロファイルによる永続的アイデンティティ

ステートレスな CLI はエージェントに毎回同じ設定フラグを再指定させます。

  • The Standard: 設定を束ねるプロファイルシステム（profile save、profile use）を実装します。
  • Optimization: agent-context に利用可能なプロファイルを表示し、エージェントが設定ファイルを解析せずに既存のアイデンティティを発見できるようにします。

10. 双方向 I/O

エージェントは生成されたビデオやログなどのアーティファクトを特定の宛先に移動する必要があることが多いです。

  • The Standard: stdout、file:<path>、webhook:<url> をサポートする --deliver フラグを実装します。
  • Optimization: エージェントが摩擦（例：「このフラグはドキュメントにあるが拒否された」）をメンテナに直接報告できる feedback コマンドを含めます。

議論：エージェントネイティブ vs. Unixネイティブ

すべての開発者が「エージェントネイティブ」というラベルに同意しているわけではありません。これらの原則は単に「良い CLI 設計」であり、昔から守るべきだったと主張する人もいます。

"もし jq を使ったことがあるなら、--json が非常に価値あるものだと誰かに教えてもらう必要はありません… これはコマンドラインインターフェースをインターフェースとして真剣に捉えているだけです。AI とはほとんど関係がなく、端にあるだけです。"

他方では、エージェント向けに過度にエンジニアリングし、人間の使いやすさを犠牲にすることに警鐘を鳴らす声もあり、エージェントは十分に良い「LLM 用マニュアルページ」があれば、乱雑な CLI でも対処できると示唆しています。

哲学的な分裂があっても、実務的な結果は同じです。予測可能で構造化され、一貫した CLI は、炭素でできたユーザーであれシリコンでできたユーザーであれ、すべての利用者にとって優れています。

Sources