cli-design
コマンドラインツールを人間中心の設計で構築するためのガイドです。適切なコマンド構造、出力フォーマット、エラーハンドリング、設定、拡張性を備えた使いやすいCLIツールの開発に活用できます。CLIツールの構築、サブコマンドの追加、CLI出力の設計、CLIのエラー処理、またはCLIコードのUX問題のレビューが必要な場合に使用してください。
description の原文を見る
Guide for building delightful, human-first command-line tools with proper command structure, output formatting, error handling, configuration, and extensibility. Use when creating CLI tools, adding subcommands, designing CLI output, handling errors in CLIs, or reviewing CLI code for UX issues.
SKILL.md 本文
CLI Design
Unix エコシステムと良好に組み合わせることができる、堅牢で明確に通信し、 しっかりとした感覚のコマンドラインツールを構築します。
使用する場面
- 新しい CLI ツールを作成する、またはサブコマンドを追加する
- 出力フォーマット(人間向け、JSON、LLM 向け)を設計する
- エラーハンドリングと終了コードを実装する
- 認証、設定、またはプラグインシステムを追加する
- ユーザビリティの問題について CLI コードをレビューする
コア哲学
- 人間中心で機械互換 -- 人間向けに設計し、その後に機械が出力を消費できることを確認する
- 対話であって尋問ではない -- 各呼び出しは対話のターン。修正を提案し、次のステップを示す
- 革新性よりも一貫性 -- 規約に従う(
--help、-v、--output json、終了コード) - 必要十分な情報を伝える -- デフォルトで簡潔に、フラグで詳細表示
- 堅牢さは感覚 -- 高速な起動、明確なフィードバック、ハング無し、謎めいたスタックトレース無し
ルール索引
ルールはドメインと影響度別に整理されています。 完全な詳細とサンプルについては、リンク先のリファレンスを参照してください。
| # | ドメイン | ルール | 影響度 | リファレンス |
|---|---|---|---|---|
| 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 ツールを構築またはレビューする際:
- 作業しているドメインの関連リファレンスファイルを読む
- 影響度別にルールを適用 -- CRITICAL 優先、次に HIGH、次に MEDIUM
- 出荷前に
チェックリストを使用
その他のリファレンス
Philosophy deep dive-- 拡張原則と根拠Pre-launch checklist-- 出荷前の検証チェックリスト
ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ
詳細情報
- 作者
- magarcia
- リポジトリ
- magarcia/pylon-sync
- ライセンス
- MIT
- 最終更新
- 2026/4/13
Source: https://github.com/magarcia/pylon-sync / ライセンス: MIT
関連スキル
doubt-driven-development
重要な判断はすべて、本番環境への展開前に新しい視点から対抗的レビューを実施します。速度より正確性が重要な場合、不慣れなコードを扱う場合、本番環境・セキュリティに関わるロジック・取り消し不可の操作など影響度が高い場合、または後でバグを修正するよりも今検証する方が効率的な場合に活用してください。
apprun-skills
TypeScriptを使用したAppRunアプリケーションのMVU設計に関する総合的なガイダンスが得られます。コンポーネントパターン、イベントハンドリング、状態管理（非同期ジェネレータを含む）、パラメータと保護機能を備えたルーティング・ナビゲーション、vistestを使用したテストに対応しています。AppRunコンポーネントの設計・レビュー、ルートの配線、状態フローの管理、AppRunテストの作成時に活用してください。
desloppify
コードベースのヘルスチェックと技術負債の追跡ツールです。コード品質、技術負債、デッドコード、大規模ファイル、ゴッドクラス、重複関数、コードスメル、命名規則の問題、インポートサイクル、結合度の問題についてユーザーが質問した場合に使用してください。また、ヘルススコアの確認、次の改善項目の提案、クリーンアップ計画の作成をリクエストされた際にも対応します。29言語に対応しています。
debugging-and-error-recovery
テストが失敗したり、ビルドが壊れたり、動作が期待と異なったり、予期しないエラーが発生したりした場合に、体系的な根本原因デバッグをガイドします。推測ではなく、根本原因を見つけて修正するための体系的なアプローチが必要な場合に使用してください。
test-driven-development
テスト駆動開発により実装を進めます。ロジックの実装、バグの修正、動作の変更など、あらゆる場面で活用できます。コードが正常に動作することを証明する必要がある場合、バグ報告を受けた場合、既存機能を修正する予定がある場合に使用してください。
incremental-implementation
変更を段階的に実施します。複数のファイルに影響する機能や変更を実装する場合に使用してください。大量のコードを一度に書こうとしている場合や、タスクが一度では完結できないほど大きい場合に活用します。