CLI Design

Unix エコシステムと良好に組み合わせることができる、堅牢で明確に通信し、 しっかりとした感覚のコマンドラインツールを構築します。

使用する場面

• 新しい CLI ツールを作成する、またはサブコマンドを追加する
• 出力フォーマット(人間向け、JSON、LLM 向け)を設計する
• エラーハンドリングと終了コードを実装する
• 認証、設定、またはプラグインシステムを追加する
• ユーザビリティの問題について CLI コードをレビューする

コア哲学

1. 人間中心で機械互換 -- 人間向けに設計し、その後に機械が出力を消費できることを確認する
2. 対話であって尋問ではない -- 各呼び出しは対話のターン。修正を提案し、次のステップを示す
3. 革新性よりも一貫性 -- 規約に従う(--help、-v、--output json、終了コード)
4. 必要十分な情報を伝える -- デフォルトで簡潔に、フラグで詳細表示
5. 堅牢さは感覚 -- 高速な起動、明確なフィードバック、ハング無し、謎めいたスタックトレース無し

ルール索引

ルールはドメインと影響度別に整理されています。 完全な詳細とサンプルについては、リンク先のリファレンスを参照してください。

#	ドメイン	ルール	影響度	リファレンス
1	コマンド	マルチリソース CLI には tool <noun> <verb> [flags] を使用	CRITICAL	command-structure
2	コマンド	サブコマンドのネストは最大 2 レベルまで	HIGH	command-structure
3	コマンド	位置指定引数よりもフラグを優先(自己説明的、順序非依存)	HIGH	command-structure
4	コマンド	すべてのフラグに長形式があり、一般的なフラグには短形式も付与	MEDIUM	command-structure
5	コマンド	グローバルフラグをサポート: --help、--version、--verbose、--output、--no-color、--quiet	CRITICAL	command-structure
6	出力	TTY を検出 -- ターミナルとパイプの出力を適応させる	CRITICAL	output-design
7	出力	stdout はデータ用、stderr はメッセージ/進捗/エラー用	CRITICAL	output-design
8	出力	--output json を安定したスキーマで サポート	CRITICAL	output-design
9	出力	エージェント向けの消費のため --output llm をサポート	HIGH	output-design
10	出力	スキャン性のために色を使用し、装飾ではなく; NO_COLOR を尊重	MEDIUM	output-design
11	出力	長時間操作のため stderr にスピナー/進捗を表示	HIGH	output-design
12	ヘルプ	引数なし実行時に簡潔なサマリーを表示; --help で完全なヘルプを表示	CRITICAL	help-system
13	ヘルプ	ヘルプテキストで例を最初に表示	HIGH	help-system
14	ヘルプ	タイプミスの修正提案とアクション後の次のステップを提案	HIGH	help-system
15	ヘルプ	bash、zsh、fish、powershell のシェル補完を提供	MEDIUM	help-system
16	エラー	すべてのエラーに答える: 何が起こったか、なぜか、何をすべきか	CRITICAL	error-handling
17	エラー	名前空間付きエラーコード(AUTH-003、NET-001)を使用	HIGH	error-handling
18	エラー	明確な終了コードマッピングを定義(0=成功、1=一般、2=使用法など)	HIGH	error-handling
19	エラー	生のスタックトレースは決して表示しない; デバッグファイルに記録	HIGH	error-handling
20	インタラクティブ	標準入力が TTY の場合のみ不足している引数をプロンプト; --no-input で失敗	HIGH	interactivity
21	インタラクティブ	破壊的なアクションを確認; --yes でバイパス可能にする	CRITICAL	interactivity
22	設定	すべてのプラットフォームで XDG Base Directory(~/.config/mycli/)に従う	HIGH	configuration
23	設定	優先順位: フラグ > 環境変数 > プロジェクト設定 > ユーザ設定 > デフォルト	HIGH	configuration
24	認証	フラグ、環境変数、保存済み認証情報、インタラクティブログイン経由のトークンをサポート	HIGH	authentication
25	拡張	プラグインに mycli-<name> 実行ファイルパターンを使用	MEDIUM	extensibility
26	パフォーマンス	100ms以下のコールドスタートを目指す; 必要になるまで処理を遅延	HIGH	performance
27	パフォーマンス	100ms以内に何か出力する; 応答性 > 生のスピード	HIGH	performance
28	配布	可能な限り単一の静的バイナリを配布	HIGH	distribution
29	配布	--version でバージョン、コミットハッシュ、ビルド日付をサポート	MEDIUM	distribution
30	テスト	完全な CLI 呼び出し(stdout、stderr、終了コード)を統合テストする	HIGH	testing
31	堅牢性	SIGINT(終了コード 130)、SIGTERM(終了コード 143)、SIGPIPE(静かに終了)を処理	HIGH	testing
32	堅牢性	入力を早期に検証し、状態変更前にベイルアウト	HIGH	error-handling
33	堅牢性	クラッシュのみ設計: 終了時のクリーンアップ要件を回避	MEDIUM	testing
34	セキュリティ	シークレットをフラグ経由で受け入れない(ps、シェル履歴に見える)	CRITICAL	configuration
35	将来	変更を加算的にする; 削除する前に廃止予定にする	HIGH	distribution

ワークフロー

CLI ツールを構築またはレビューする際:

1. 作業しているドメインの関連リファレンスファイルを読む
2. 影響度別にルールを適用 -- CRITICAL 優先、次に HIGH、次に MEDIUM
3. 出荷前にチェックリストを使用

その他のリファレンス

• Philosophy deep dive -- 拡張原則と根拠
• Pre-launch checklist -- 出荷前の検証チェックリスト