agent-aware-cli

エージェントを考慮した CLI 設計ガイドライン

コマンドラインインターフェース（CLI）の構築や改善に取り組む際は、人間のオペレーター（豊富な TUI を使用）と AI エージェント（決定論的で機械可読な出力を利用）の両方に役立つよう、次のアーキテクチャおよび設計のベストプラクティスに従ってください。

コア原則

1. デュアルエクスペリエンスのパラダイム（DX と AX） この CLI は、人間と AI エージェントの両方を第一級のユーザーとして扱う「デュアルモード」インターフェースとして設計する必要があります。

   • DX（開発者エクスペリエンス）：人間のオペレーターにとっての使いやすさです。見つけやすさ、豊富な TUI（例：Bubbletea、Lipgloss）、意味に基づく色分け、直感的なエイリアスを重視します。
   • AX（エージェントエクスペリエンス）：自律型 AI エージェントにとっての使いやすさです。決定性、厳密な機械可読出力モード（例：--json）、ヘッドレス認証、積極的なデータ範囲の限定（制限／フィルタリング）、変更操作の安全性（--dry-run）を重視します。
   • 環境変数による上書き：NO_COLOR と [APP]_NO_TUI 環境変数を尊重し、対話機能のないスタイルなしモードへ自動的に切り替えます。

2. ヘッドレス環境に適した認証

   • エージェントは、ブラウザーを使った対話型 OAuth フローを完了できません。CLI はヘッドレス認証方式（サービスアカウント、環境変数による API キー、--token フラグ）をサポートするか、すぐに処理を失敗させ、人間のオペレーターに先に手動で認証するよう促す、明確で機械可読なエラーを出力する必要があります。

3. 妥当なデフォルトと積極的なフィルタリング

   • ページ分けやフィルタリングをしていない一覧を stdout に出力してはいけません。妥当な上限（例：上位 10 件）をデフォルトにします。豊富なフィルタリングフラグ（例：--status、--mine、--limit）を用意し、エージェントがトークンコンテキストを圧迫せず、必要な情報だけを的確に取得できるようにします。

4. 変更操作の安全性（--dry-run）

   • 外部状態を作成、更新、削除するコマンドには、--dry-run フラグを実装します。これにより、自律型エージェントは破壊的な操作を実行する前に、パラメーターの対応付けを試し、生成されるペイロードをローカルで検証できます。

5. コンテキストウィンドウの保護

   • エージェントのコンテキストウィンドウには制限があります。巨大なテキストの塊は積極的に切り詰め、重要なアクション項目を先頭に並べ、認証情報の漏えいを防ぐため、生の認証情報はデフォルトでマスキングします。
   • フィルタリングされていないデータを明示的に求めるエージェントや人間向けに、オプトイン方式の詳細表示（例：--full または --verbose）を用意します。

6. 実行可能な先回り型エラーヒント

   • 失敗を報告するだけにとどめず、修正するための正確な手順を提示します。
   • コピーしてそのまま実行できるターミナルコマンドを stderr に含めます（例：Hint: run 'app init' to create a database）。これにより、自律型エージェントはエラーを解析し、シームレスに自己修正できます。

7. 委任型の状態管理

   • 複雑なワークフローを調整する際、CLI 内で長時間実行される状態ループを維持しないようにします。
   • ステートレスなタスク識別子のパターン（--task <ID>、--ref <ID>）を使用します。ID をバックエンドサービスに渡し、トークンコンテキストウィンドウと会話履歴を管理させます。

8. エージェント向け指示の外部化

   • AI 開発者向けに、ツールの使い方、ワークフロー、規約を説明する AGENTS.md または GEMINI.md ファイルをリポジトリのルートに追加します。
   • agentskills.io に準拠した skills/ ディレクトリを用意し、複雑なサブコマンド用の SKILL.md ファイルを配置します。

9. API の探索と段階的な利便性の向上

   • 大規模な Google／REST API に対応する CLI を構築する際は、その ディスカバリードキュメント（例：https://youtube.googleapis.com/$discovery/rest?version=v3）を分析し、リソース、メソッド、クエリパラメーター、必須の OAuth スコープの厳密な対応関係を把握します。
   • API を 100％カバーできるよう、ディスカバリードキュメントから基本コマンドを直接自動生成することを検討します。
   • ただし、生の REST マッピングは人間には使いにくいことがよくあります。そのため、生の生成コマンドの上に「便利なラッパー」や「ヒント」を重ねる必要があります。たとえば、ユーザーが「あるユーザーの動画を一覧表示して」と求めた場合、ユーザー名をチャンネル ID に解決する API 呼び出しとプレイリストを取得する API 呼び出しの 2 回が必要なことを CLI が適切に抽象化し、単一の channel videos @user コマンドで実行できるようにします。

Go による実装（Cobra と Viper）

Go で CLI を実装する場合は、コマンドルーティングに Cobra を、構成管理に Viper を使用します。

Cobra のプラクティス

• 構造化された見つけやすさ：コマンドを分類するために Cobra の GroupID（例：Task Management、Information）を使用し、ルートのヘルプ出力が「テキストの壁」にならないようにします。
• ドキュメントの3つの柱：すべてのコマンドで、次のフィールドを設定します。
  • Short：すばやく確認できるよう、動作を表す動詞で始まる5～10語の要約です。
  • Long：コマンドが何を行うのか、なぜ必要なのか、どのような点が異なるのかを詳しく説明します。
  • Example：一般的なフラグの組み合わせを示す、具体的でコピーして実行できる例を3～5個記載します。
• 早期失敗のフック：重い処理を実行する前に、PersistentPreRun フックで設定と接続を検証します。

Viper と設定のプラクティス

• XDG 準拠：設定ファイルには XDG Base Directory Specification に従います（例：~/.config/app/config.yaml）。
• 適切なフォールバックの優先順位：Viper を使用して、値が次の一貫した順序で解決されるようにします。 Command Line Flag > Environment Variable > Config File > Default Value
• シークレット管理：API キーがシェルの履歴に漏れないようにします。シークレットには CLI フラグよりも環境変数を使用してください。

視覚的な情報設計（人間向けモード）

人間が読みやすい CLI にするには、認知負荷を最小限に抑えるため、Tufte に着想を得た原則を活用します。

• データインク比を最大化する：装飾的な枠線など、不要な「インク」を最小限に抑えます。階層を伝える主な手段として、余白と配置を使用します。
• 堅牢な UI の書式設定：端末向けのスタイル（例：lipgloss）を適用する前に、生の文字列に必ずパディングと幅の指定を適用します。不可視の ANSI エスケープコードによって、fmt.Printf の表の位置合わせが崩れることがあります。
• ANSI による位置合わせの落とし穴：Go で TUI の表を作成する場合、text/tabwriter や fmt.Printf などの標準ツールは、不可視の ANSI カラーコードを含む文字列を渡すと位置合わせが崩れます。文字列に色を付ける前に固定幅に合わせてパディングするか、lipgloss.Table のような堅牢なレイアウトエンジンを使用する必要があります。
• 意味に基づくカラーのトークン：見た目ではなく、機能に応じた色を使用します。
  • Accent（青）：ナビゲーションの目印、ヘッダー、グループ名。
  • Command（グレー／ライトグレー）：コマンド名やフラグなど、確認対象。
  • Pass（緑）：成功状態や完了したタスク。
  • Warn（オレンジ／黄色）：一時的な状態や保留中の状態、警告。
  • Fail（赤）：エラーや拒否された状態。
  • Muted（ダークグレー）：メタデータ、型、デフォルト値など、目立たせない情報。
  • ID（ティール／ミント）：一意の識別子。
• カラーの段階的な劣化：ファイルにパイプで出力する場合、--json を指定する場合、または NO_COLOR が存在する場合に、色が適切に段階的に無効化されるようにします。

エージェント向け必須実装チェックリスト

CLI コマンドを生成または更新する際は、初回の実装時に以下のすべてが実装されていることを必ず確認してください。UI/UX を後回しにしないでください。

• デュアルエクスペリエンス（DX/AX）：コマンドは --json フラグをサポートしていますか。または NO_COLOR／[APP]_NO_TUI に対応していますか？
• ヘッドレス認証：ブラウザベースの OAuth プロンプトで停止することなく、エージェントがこのコマンドを自律的に実行できますか？
• データのスコープ設定：リストを返す場合、妥当なデフォルトの上限とフィルタリングフラグ（例：--limit、--status）がありますか？
• 変更操作の安全性：コマンドが状態を変更する場合、エージェントの安全性を確保するための --dry-run フラグがありますか？
• エラー時のヒント：エラー発生時、実行可能でコピーして貼り付けられるターミナルコマンドを stderr に出力しますか？
• XDG 準拠：ローカルの .env ファイルではなく、XDG Base Directory 仕様（例：~/.config/app/config.yaml）に従って設定を処理していますか？
• 3 つの柱：Cobra コマンド定義の Short、Long、Example フィールドはすべて適切に入力されていますか？
• 見つけやすさ：コマンドは論理的な GroupID に割り当てられていますか？
• セマンティックカラー：人が読む出力は、セマンティックカラーのトークン（例：Lipgloss）を使ってフォーマットされていますか？
• 整列の安全性：テーブルで生の ANSI カラーを使う場合、整列崩れを防ぐため、カラーコードを付ける前に文字列のパディングを適用していますか？
• ヘルプのフォーマット：Cobra のデフォルトの SetUsageTemplate をオーバーライドして、ヘルプ出力自体にセマンティックカラー（例：見出しを青色にする）を適用していますか？