AIエージェントのためのCLIデザインパターン：誤解と実践的アプローチ

CLIインターフェースプロトコルの明確化

第1部からの最大の誤解は、「CLI」がLLMにLinuxターミナルを与えることを意味すると考えられていたことです。CLIは実際にはインターフェースプロトコルであり、テキストコマンド入力→テキスト結果出力です。実装は2つの方法で行うことができます：

• シェルのPATH内のバイナリまたはスクリプトとして — 実際のシェルで実行されるCLIツールになる
• コード内のコマンドパーサーとして — LLMがrun(command="weather --city Tokyo")を出力したとき、文字列を解析し、シェルを介さずにアプリケーションコード内で直接実行する

重要なのは、LLMにCLIを使用しているように感じさせることです。著者のシステムでは、ほとんどのコマンドはOSに触れることはありません — それらはコマンドルーターによってディスパッチされるGo関数です。実際のOSを真に必要とするコマンド（スクリプトの実行、パッケージのインストール）のみが、分離されたマイクロVMに送られます。エージェントは、どのレイヤーがコマンドを処理するかを知らず、気にもしません。

エージェントに適したCLI設計原則

2つの核となる哲学

哲学1：Unixスタイルのヘルプ設計

• tool --help → トップレベルコマンドのリスト
• tool <command> --help → そのサブコマンドの具体的なパラメータと使用方法

これにより、エージェントは事前にすべてのドキュメントをコンテキストに詰め込むことなく、必要に応じて機能を発見できます。

哲学2：ヒント思考

すべての応答 — 特にエラー — には、不必要な探索を減らすガイダンスを含めるべきです。

悪い例：

> cat photo.png [error] binary file

良い例：

> cat photo.png [error] cat: バイナリファイルが検出されました (image/png, 182KB)。使用法：see photo.png (画像を表示) または：cat -b photo.png (base64エンコード)

これが重要な理由：無効な探索はトークンを浪費します。マルチターン会話では、この浪費は蓄積されます — すべての失敗した試みはコンテキストに残り、その後のすべてのターンで注意と推論リソースを消費します。単一の役立つヒントが、会話の残りの部分でかなりのトークンを節約できます。

安全なCLI設計

CLIコマンドに危険または不可逆的な操作が含まれる場合、ツール自体が安全機構を提供すべきです。

ドライラン / 変更プレビュー — ミスの防止

エージェントの権限内で、元に戻すのが難しい結果をもたらす操作の場合。目標は、エージェント（または人間）がコミットする前に何が起こるかを確認できるようにすることです。

> dns update --zone example.com --record A --value 1.2.3.4 ⚠ ドライラン：example.comのAレコード：5.6.7.8 → 1.2.3.4 伝播：〜300秒。即座に元に戻すことはできません。実行するには：--confirmを追加

プレビューは、現在の状態とそれが何に変更されるかを明確に示すべきです。エージェントは--confirmで確認します。

人間による承認 — エージェントの自律性を超える操作

人間の判断または承認を必要とする操作の場合 — エージェントがどれほど自信を持っていても、これらを単独で完了することはできません。

アプローチ1：ブロッキングプッシュ承認

> pay --amount 500 --to vendor --reason "第2四半期の事務用品" ⏳ 承認が必要です。通知がデバイスに送信されました。応答を待機中... ✓ 承認されました。500ドルの支払いが完了しました。 [exit:0 | 7.2s]

Appleのデバイスログイン確認のように — CLIは完全なコンテキスト（金額、受取人、理由）を人間のデバイスに直接プッシュ通知として送信します。CLIは人間が承認または拒否するまでブロックし、結果をエージェントに返します。

アプローチ2：確認コード / 2FA

> transfer --from savings --to checking --amount 10000 ⚠ この操作には2FA確認が必要です。理由：口座間で10,000ドルを送金。コードが認証アプリに送信されました。再実行：--otp <code>