agent-friendly-cli は何をしますか？
新規作成、改造、レビュー時に使用するコマンドラインインターフェース（CLI）とそのスキル。特にAIエージェントが安定して呼び出しつつ、人間も通常使用できるCLI向け。コマンド面の設計、非対話モード、JSON出力契約、終了コード階層、ドライラン、冪等性、認証セキュリティ、CLI/スクリプト/スキル/エージェントの責務階層、トランザクション型オーケストレーション、リスク承認、終状態検証、および受け入れ方法をカバー。
設計原則
1. コマンド面の設計
- サブコマンドは明確で階層化され、直感的であること。
- 長いオプションと短いオプションの両方を提供すること。
--helpは必須かつ完全であること。
2. 非対話モード
- 環境変数
CIまたは--non-interactiveフラグで強制可能。 - プロンプトを表示せず、すべての入力をオプションまたは環境変数で受け付ける。
3. JSON出力契約
--jsonまたは--output jsonオプションで構造化JSONを出力する。- エラーの場合もJSONでエラー情報を返す。
4. 終了コード階層
| 終了コード | 意味 |
|---|---|
| 0 | 成功 |
| 1 | 一般的なエラー |
| 2 | 誤った使用法 |
| 3 | 設定エラー |
| 4 | 認証エラー |
| 5 | レート制限超過 |
| 6 | 冪等性違反 |
5. ドライラン
--dry-runまたは--dry-runオプションで実際の変更を行わずに実行内容を表示する。- 出力は人間が読める形式またはJSON。
6. 冪等性
- 同じ入力に対して同じ状態を生成すること。
- すでに目的の状態にある場合は何もしない（成功として終了コード0を返す）。
7. 認証セキュリティ
- 認証情報は環境変数、設定ファイル、または
--tokenオプションで提供する。 - パスワードやトークンをコマンドライン引数に平文で表示しない。
8. 責務階層
- CLI: ユーザー入力の解析と表示。
- スクリプト: ビジネスロジックの実行。
- スキル: AIエージェントへのインターフェース定義。
- エージェント: 目標達成のための判断と実行。
9. トランザクション型オーケストレーション
- 複数ステップの操作は原子的に実行されること。
- 失敗時にはロールバックまたは補償アクションを提供すること。
10. リスク承認
- 破壊的操作の前に確認を求めること。
--yesまたは--forceオプションで確認をスキップ可能。
11. 終状態検証
- 操作完了後にシステム状態を検証すること。
- 期待される状態と実際の状態を比較し、差異を報告すること。
12. 受け入れ方法
- 自動テストスイートに以下を含めること：
- 正常系テスト
- 異常系テスト
- 冪等性テスト
- ドライランテスト
- JSON出力テスト
- 終了コードテスト
使用例
# ドライラン
my-cli deploy --dry-run --json
# 非対話モード
my-cli create --name example --non-interactive
# 冪等な削除
my-cli delete --id 123 --force