AI friendlyなCLIの作り方

2026年、CLIの設計思想は「人間ユーザー向け」から「AIエージェントも一級ユーザーとして扱う」方向にシフトしている。複数の記事で共通する原則をまとめる。

出力形式: 非対話環境では構造化/機械可読に切り替える

  • stdoutがTTYでない場合、自動的にJSON(またはMarkdown)出力に切り替える。エージェントに--output jsonを毎回明示させない。
  • データはstdout、進捗・警告はstderrに分離する。エージェントはstdoutしか読まない前提で設計する。
  • 人間向けの表・色付き出力とエージェント向け出力を両立させる場合は、フラグで切り替え可能にし、人間向けをデフォルトにする。
  • JSONかMarkdownかは議論が分かれる。JSONは厳密なパース向き、MarkdownはLLMがテキストとしてそのまま読める分トークン効率が良いとする主張もある。

対話プロンプトを排除する

確認プロンプト・スピナー・段階的ウィザードはエージェントの実行を止めてしまう。--yes/--skip-interactiveのような非対話フラグを用意する。ただし危険な操作(本番環境の変更等)を無警戒に自動承認させるのは危険で、dry-run・冪等性・2段階確認などを組み合わせた設計が必要になる。詳細は非対話型確認プロトコルを参照。

エラー・終了コードを機械可読にする

  • 終了コードを意味ごとに分類する(例: 0=成功, 2=認証エラー, 3=入力検証エラー, 4=確認必須)。エージェントは終了コードだけで次のアクションを決めることが多い。
  • エラーは「何が失敗したか」と「どう直せば良いか(remediation)」をセットで構造化する。
  {"error": "Not logged in.", "code": 2, "remediation": "Run 'arcjet auth login'"}
  • ファジー補正(「もしかして: xyz」のような曖昧な提案)は人間には親切だが、エージェントには害になる。存在しないコマンドは厳密に失敗させる。

入力検証をネットワーク呼び出し前に行う

エージェントは幻覚で不正な形式のID・制御文字などを渡してくることがある。API/ネットワークを叩く前にローカルでバリデーションし、早期に失敗させる。

認証を非対話・環境変数ベースにする

ブラウザ経由のOAuthフローだけでなく、FOO_TOKENのような環境変数での認証をサポートし、CI/サンドボックス環境でも動作するようにする。

コマンド・フラグ・出力フィールドは「一度確定したら壊さない契約」として扱う

エージェントは過去に成功したコマンドパターンをキャッシュ・再利用する。破壊的変更はエージェントの成功率を大きく落とすため、APIの後方互換性と同じ厳格さで扱う。

--helpとドキュメントをエージェント向けに充実させる

  • エージェントはツールを初めて使う際に--helpを実行することが多い(Claude Codeなど)。各コマンド・フラグに簡潔な説明と実例(usage shape)を含める。
  • より深い投資としては、スキーマや--describe的なコマンドでランタイムに全コマンド仕様を自己記述させる、Agent Pluginsのようなパッケージ仕様に沿ってMCPサーバーとして機能を公開する、Markdown形式の軽量な「スキル」ドキュメント(50行程度)を添付する、といった手法がある。

冗長さを削ってトークンを節約する

人間には親切な詳細な出力も、エージェントにとってはコンテキストウィンドウを圧迫するノイズになる。--quietのような静音モードを用意し、必要な情報だけを返す。

考えたこと

複数の記事が共通して強調しているのは「AIエージェント向けの設計は結局、人間にとっても良い設計になる」という点。予測可能な終了コード、明確なエラーメッセージ、非対話フラグはCI/CDでも有用であり、人間向けとエージェント向けの設計は対立するものではなく、後者が前者を底上げする形になっている。

#cli #ai-agent #llm

出典

🔗 リンクされているノート

作成日時: 2026-08-27 16:31 / 更新日時: 2026-08-27 16:34