AIエージェント向けCLIの構築：Googleのgws CLIからの設計原則

エージェントファーストのCLI設計が重要な理由

人間の開発者体験（DX）は発見可能性と許容性を最適化しますが、エージェントのDXには予測可能性と多層防御が必要です。この記事では、人間向けに設計されたCLIをエージェント用に後付けで改造することは効果的ではなく、Google Workspace向けのgws CLIを例に、初日からAIエージェントを主要な利用者として設計されたことを実証しています。

主要な設計原則

独自フラグよりも生のJSONペイロード: 人間は--title "My Doc"のようなシンプルなフラグを好みますが、エージェントは変換ロスなしでAPIスキーマに直接マッピングできるJSONペイロードの方が適しています。

比較例:

人間向け（10個のフラグ、フラットな名前空間）:
my-cli spreadsheet create --title "Q1 Budget" --locale "en_US" --timezone "America/Denver" --sheet-title "January" --sheet-type GRID --frozen-rows 1 --frozen-cols 2 --row-count 100 --col-count 10 --hidden false

エージェント向け（1つのJSONフラグ）:
gws sheets spreadsheets create --json '
{
  "properties": {"title": "Q1 Budget", "locale": "en_US", "timeZone": "America/Denver"},
  "sheets": [{"properties": {"title": "January", "sheetType": "GRID", "gridProperties": {"frozenRowCount": 1, "frozenColumnCount": 2, "rowCount": 100, "columnCount": 10}, "hidden": false}}]
}'

gws CLIはすべての入力に--paramsと--jsonフラグを使用し、完全なAPIペイロードを直接受け入れます。推奨されるアプローチは、別々のツールを維持するのではなく、同じバイナリ内で両方のパスをサポートすることです。

追加の考慮事項

この記事では、エージェントファーストCLIのための他の設計考慮事項を概説しています:

• スキーマイントロスペクション: エージェントが実行時にイントロスペクトできる自己記述型スキーマ
• コンテキストウィンドウの規律: エージェントのコンテキスト制限内に収まる出力の管理
• 入力強化: エージェントの幻覚に対する保護
• エージェントスキル: 単なるコマンドではなく、能力の提供
• マルチサーフェスサポート: MCP、拡張機能、環境変数との連携
• 安全対策: ドライランモードとレスポンスのサニタイズ

CLIは、AIエージェントが外部システムと相互作用するための最も摩擦の少ないインターフェースとなりつつあり、人間向けのインターフェースではなく、決定論的で機械可読な出力が必要とされています。