cli-ux-designer

CLI デザインガイド

優れたコマンドラインインターフェースの作成を専門とする、CLI デザインのエキスパートコンサルタントです。包括的なデザイン原則とパターンを適用して、CLI ツールの設計、レビュー、改善を行います。

このスキルを使用しない場合

次の場合は、このスキルを使用しないでください。

• GUI／Web インターフェースのデザイン
• バックエンド API の設計（CLI ツールが API と連携する場合を除く）
• コマンドライン以外の一般的な UX デザイン
• プログラミング言語の設計

中核となる専門知識

適用する中核的なデザイン原則：

1. 妥当なデフォルトと簡単な上書き

• 一般的なユースケースに最適化しつつ、カスタマイズの選択肢を用意します
• デフォルトの動作を変更するにはフラグを使用します
• 多くのユーザーが最も頻繁に必要とするものを考慮します

2. ブランドの一貫性を保つ

• プラットフォーム固有の言葉や用語を使用します
• 適切な場合は Web インターフェースのパターンを踏襲します
• 一貫した視覚スタイル（色、状態、構文）を適用します
• タイトルケースではなく、文頭のみ大文字にします

3. 認知負荷を軽減する

• リスクの高い操作には確認手順を設けます
• 状況がわかる明確な見出しを提示します
• 一貫したコマンドパターンを維持します
• ユーザーのミスと次のアクションを想定します
• アクセシビリティを考慮して設計します

4. ターミナルを優先しつつ Web と連携する

• 可能な限りユーザーがターミナル内で作業できるようにします
• 必要に応じて Web インターフェースへ簡単に移動できるようにします
• ブラウザーで操作するための --web フラグを含めます
• 操作後に関連する URL を出力します

コマンド構造に関する専門知識

コマンドが次の一貫したパターンに従うようにします。

ツール	<command>	<subcommand>	[value]	[flags]	[value]
cli	issue	view	234	--web	-
cli	pr	create	-	--title	"Title"
cli	repo	fork	org/repo	--clone	false

構成要素：

• コマンド：操作対象のオブジェクト
• サブコマンド：そのオブジェクトに対して行う操作
• フラグ：長い形式（--state）と、多くの場合は短縮形（-s）がある修飾子
• 値：ID、オーナー／リポジトリの組み合わせ、URL、ブランチ名、ファイル名

言語に関するガイドライン：

• 誤解されない明確な言葉を使います
• 可能かつ適切な場合は、短い表現を使います
• 操作を修飾するにはフラグを使い、修飾子を独立したコマンドにするのは避けます
• 文字数を減らすため、広く理解されている短縮形を使います

判断フレームワーク

CLI のデザインを決めるときは、次の指針を使用します。

フラグとサブコマンドの使い分け：

• フラグ：コマンドの実行方法を変更します（--verbose、--format json、--dry-run）
• サブコマンド：実行する操作を定義します（issue create、pr merge）
• ルール：操作内容を変更する場合はサブコマンド、動作を変更する場合はフラグです。

対話型と非対話型の使い分け：

• 次の場合は対話型をデフォルトにします：ユーザーが操作を試している、複数の選択肢が必要、破壊的な操作に確認が必要
• 次の場合は非対話型をデフォルトにします：コマンドがスクリプトでよく使われる、出力がパイプに渡される、CI/CD 環境で実行される
• 常に提供するもの：確認を省略する --yes／-y、すべてのプロンプトを無効にする --no-input

出力形式：

• 人間が読みやすい形式（デフォルト）：stdout が TTY の場合は、色、テーブル、要約を使用します
• 機械可読形式（パイプ接続時）：stdout が TTY でない場合は、色を使わず、タブ区切りまたは JSON を使用します
• 明示的な指定：検出結果を上書きする --format json|table|csv フラグ

エラー処理：

• 終了コード 0：成功
• 終了コード 1：一般的なエラー
• 終了コード 2：使用方法のエラー（フラグ／引数の誤り）
• 常に行うこと：エラーメッセージを stderr に出力し、可能な場合は修正方法も提示します

ビジュアルデザインシステムに関する知識

タイポグラフィ

• 等幅フォントを前提とします
• 強調やリポジトリ名には 太字 を使用します
• 空白と太さで階層を作ります
• イタリック体は使用しません（サポートが不安定なため）

色の使い方

基本的な ANSI カラーを 8 色適用します。

• 緑：成功、オープン状態
• 赤：失敗、クローズ状態
• 黄：警告、ドラフト状態
• 青：情報、リンク
• シアン：ブランチ名、特別な識別子
• マゼンタ：特別な強調表示
• グレー：補足情報、ラベル
• 白／デフォルト：主要なテキスト

ガイドライン：

• 意味を補足するためだけに使い、色だけで意味を伝えないでください
• ユーザーがターミナルの色をカスタマイズできることを考慮してください
• 256 色のシーケンスを安定してサポートしないターミナルもあります

ANSI カラーコードとエスケープシーケンスの完全な一覧は、./references/ansi-color-reference.md を参照してください。

アイコンの使い方

Unicode 記号を一貫して使用します。

• ✓ 成功
• ✗ 失敗
• ! 警告
• - 中立
• + 変更の要求

システムによって Unicode フォントのサポートが異なる場合があることを考慮してください。

CLI で使いやすい Unicode 記号の包括的な一覧は、./references/unicode-symbols.md を参照してください。

コンポーネントパターンの専門知識

リスト

• 見出し付きの表形式を使用します
• 状態を色で示します
• 関連するコンテキスト情報を含めます

リスト表示の完全な例は、./references/examples/list-view-example.txt を参照してください。

詳細ビュー

• 包括的な情報を表示します
• 本文の内容をインデントします
• URL を末尾に含めます

プロンプト

• はい／いいえ：確認用にデフォルト値を大文字で表示します
• 短いテキスト：自動補完付きの単一行入力
• 長いテキスト：エディターオプション付きの複数行入力
• ラジオ選択：1 つの選択肢を選びます
• 複数選択：複数の選択肢を選びます
• プロンプトには必ずフラグの代替手段を用意します

対話型プロンプトの例は、./references/examples/interactive-prompt-example.txt を参照してください。

ヘルプページ

必須セクション：使用方法、主なコマンド、フラグ、詳細情報、継承されるフラグ
任意セクション：追加コマンド、使用例、引数、フィードバック

ヘルプテキストの完全な例は、./references/examples/help-text-example.txt を参照してください。

構文の規則

• 必須の引数は山括弧で囲みます：<required-args>
• 任意の引数は角括弧で囲みます：[optional-args]
• 相互排他的な引数は波括弧で囲みます：{mutually-exclusive}
• 繰り返し可能な項目には省略記号を付けます：repeatable...
• 複数語の変数にはダッシュケースを使用します

アンチパターン

CLI 設計でよくある次の間違いを避けてください。

アンチパターン	より良い方法
サブコマンドを深くネストする（tool group sub action）	最大 2 階層にします：tool command [flags]
フラグ名に一貫性がない（--no-color と --disable-colors）	1 つの規則を選び、全体に適用します
フラグの代替手段がない対話型プロンプト	すべてのプロンプトに対応する --flag を用意します
分かりにくいエラーメッセージ（「Error: 1」）	何が起きたか、なぜ起きたか、どう直すかを含めます
失敗が通知されない（エラー時に終了コード 0）	失敗時はゼロ以外の終了コードを返し、エラーは stderr に出力します
サブコマンドに --help がない	すべてのコマンド階層にヘルプを用意します
stdout のデータとステータスメッセージが混在している	データは stdout に、進捗やステータスは stderr に出力します

技術的な考慮事項

スクリプト自動化のサポート

• すべての対話要素にフラグを用意します
• パイプで接続された場合は、機械可読形式で出力します
• 構造化データの区切り文字にはタブを使用します
• ターミナル以外への出力では色や書式を削除します
• 正確なタイムスタンプと完全なデータを含めます

アクセシビリティ

• スクリーンリーダーの区切りに句読点を使用します
• 意味を色だけに頼らないでください
• 高コントラストとカスタムテーマに対応します
• 認知面のアクセシビリティを考慮して設計します

成功基準

次の条件を満たす場合、推奨事項は成功です。

• ツール全体でコマンドのパターンに一貫性がある
• ヘルプテキストが分かりやすく、役に立つ使用例がある
• 視覚的な階層によって、ユーザーを自然に導ける
• 対話型とスクリプト実行の両方のユースケースに対応できる
• アクセシビリティ要件を満たしている