CLIを作成する
CLIの表面領域(シンタックス+動作)を、人間ファーストかつスクリプトフレンドリーに設計します。
最初に行うこと
agent-scripts/skills/create-cli/references/cli-guidelines.mdを読み、デフォルトの評価基準として適用します。- 上流/完全版ガイドライン:https://clig.dev/ (変更提案:https://github.com/cli-guidelines/cli-guidelines)
- インターフェースを確定するために必要な最小限の質問のみを行います。
明確化(迅速に)
質問し、ユーザーが不明な場合は最善の推測でデフォルトを設定して進めます:
- コマンド名+1文の目的。
- 主なユーザー:人間、スクリプト、またはその両方。
- 入力ソース:引数 vs 標準入力;ファイル vs URL;シークレット(フラグ経由は不可)。
- 出力契約:人間向けテキスト、
--json、--plain、終了コード。 - 対話性:プロンプトは許可?
--no-inputが必要? 破壊的操作には確認? - 設定モデル:フラグ/環境/設定ファイル;優先順位;XDG vs リポジトリローカル。
- プラットフォーム/ランタイム制約:macOS/Linux/Windows;単一バイナリ vs ランタイム。
成果物(出力すべきもの)
CLIを設計する際、ユーザーが実装可能なコンパクトな仕様を作成します:
- コマンドツリー+USAGE概要。
- 引数/フラグ表(型、デフォルト値、必須/オプション、例)。
- サブコマンドのセマンティクス(各サブコマンドの動作;冪等性;状態変更)。
- 出力ルール:標準出力 vs 標準エラー出力;TTY検出;
--json/--plain;--quiet/--verbose。 - エラー+終了コードマップ(主要な障害モード)。
- 安全ルール:
--dry-run、確認、--force、--no-input。 - 設定/環境変数ルール+優先順位(フラグ > 環境変数 > プロジェクト設定 > ユーザー設定 > システム)。
- シェル補完に関する説明(該当する場合):インストール/発見可能性;生成コマンドまたはバンドルスクリプト。
- 5~10個の使用例(一般的なフロー;パイプ/標準入力の例を含む)。
デフォルトの慣例(ユーザーが別途指定しない限り)
-h/--helpは常にヘルプを表示し、他の引数を無視します。--versionはバージョンを標準出力に出力します。- 主要データは標準出力へ;診断/エラーは標準エラー出力へ。
- 機械出力には
--jsonを追加し、安定した行ベースのテキストには--plainを検討します。 - プロンプトは標準入力がTTYの場合のみ;
--no-inputはプロンプトを無効化します。 - 破壊的操作:対話的な確認+非対話的には
--forceまたは明示的な--confirm=...が必要。 NO_COLOR、TERM=dumbを尊重;--no-colorを提供します。- Ctrl-C の処理:迅速に終了;限定的なクリーンアップ;可能な限りクラッシュオンリー型に。
テンプレート(回答にコピーして使用)
CLI仕様の骨格
以下のセクションを埋め、関連のないものは削除します:
- 名前:
mycmd - 1行説明:
... - USAGE:
mycmd [グローバルフラグ] <サブコマンド> [引数]
- サブコマンド:
mycmd init ...mycmd run ...
- グローバルフラグ:
-h, --help--version-q, --quiet/-v, --verbose(正確に定義)--json/--plain(該当する場合)
- 入出力契約:
- 標準出力:
- 標準エラー出力:
- 終了コード:
0成功1一般的な失敗2不正な使用法(パース/検証)- (実際に有用な場合のみコマンド固有のコードを追加)
- 環境変数/設定:
- 環境変数:
- 設定ファイルのパス+優先順位:
- 例:
- …
注意事項
- パースライブラリ(言語固有)の推奨は、尋ねられた場合のみ行います。それ以外はこのスキルを言語に依存しない形に保ちます。
- リクエストが「設計パラメータ」である場合、実装に踏み込まないでください。