cli-design-framework

CLI 設計フレームワーク

概要

分類を起点としたフレームワークで CLI を設計およびレビューします。

これは汎用的なスタイルガイドではなく、意思決定システムとして扱ってください。すべての CLI がエージェントファースト、マシンプロトコルファースト、または生ペイロードファーストになるべきだと想定しないでください。

使用する場面

次の場合にこのスキルを使用します。

• 新しい CLI を設計する際に、適切なコマンドの形が自明でない場合
• 既存の CLI をレビューする際に、ヘルプ、出力、またはコマンドツリーに違和感がある場合
• CLI が主に Capability、Runtime、Environment / Workspace、Workflow、Package / Build、Meta のどれに当たるかを判断する場合
• 人間が読めるサーフェスと機械が読めるサーフェスのどちらを主とするか、または従とするかを判断する場合
• セッションのセマンティクスが正当化されるか、過剰設計かを判断する場合

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

• CLI の分類がすでに確定しており、実装の仕組みだけが必要な場合
• 問いがパーサーライブラリ、リポジトリのレイアウト、または正確なフラグの綴りだけに関する場合
• タスクが設計上の影響を伴わない純粋に見た目だけのコピー編集である場合

クイックパス

• 手早い依頼に対しては、圧縮したパスを出力します。目的、分類、短い根拠、主要な設計上の帰結、そして答えを変えうる未解決の問みを挙げます。
• 完全なブループリントまたは完全なレビューテンプレートは、ユーザーが明示的に求めた場合、または曖昧さやリスクがより長い形式を正当化する場合にのみ使用してください。

中核ルール

まず分類します。次に設計します。最後にレビューします。

常にこの順序で進めてください。

1. CLI の目的を一文で述べます。
2. 主要な役割 / 制御サーフェスを分類します。
3. 主要なユーザー種別を分類します。
4. 主要なインタラクション形式を分類します。
5. ステートフル性を分類します。
6. リスクプロファイルを分類します。
7. 副次的なサーフェスを明示的に特定します。
8. 設計上の帰結を導き出します。

フレームワークを使用する際は、次のファイルから始めてください。

• タクソノミーについては references/taxonomy.md。
• 必要な出力形式については references/output-templates.md。

必要になったときだけ次を参照してください。

• カテゴリが曖昧なときの分類のアンカーについては references/classification-examples.md。
• 最終形式の具体例が必要なときは examples/design-blueprint-example.md と examples/review-example.md。
• 設計に違和感があるものの、カテゴリの誤りがまだ明確でないときは examples/anti-patterns.md。

動作モード

次のいずれかのモードで動作します。

1. 設計モード — CLI の設計方針を作成または洗練します。
2. レビューモード — 既存の CLI をフレームワークに照らして評価します。

---

設計モード

目標

CLI の設計ターゲットを明確にし、実装を制約するブループリントを作成します。

ワークフロー

1. すでに判明していることを推論します。

   • ユーザーのリクエストから、強いシグナルをすべて抽出します。
   • 想定される役割、ユーザータイプ、インタラクション形式、状態保持性、リスクプロファイル、副次的なサーフェスを、可能な限り推論します。
   • すでに強く示唆されている事実を尋ねてはいけません。

2. 最も影響の大きい未解決の質問だけを尋ねます。

   • 分類やブループリントを大きく変えうる、最小限の質問セットを尋ねます。
   • 実装の細枝末節よりも、分類に関する質問を優先します。
   • 優先順位: 目的 → 制御サーフェス → 主なユーザー → インタラクション形式 → 状態保持性 → 副作用 → 副次的なサーフェス。
   • 現時点の情報ですでに十分な場合は、質問をしてはいけません。ブループリントを直接作成します。

3. CLI を明示的に分類します。

   • 推論または確認済みの以下を明示します。
     • 主な役割／制御サーフェスのタイプ
     • 主なユーザータイプ
     • 主なインタラクション形式
     • 状態保持性
     • リスクプロファイル
     • 副次的なサーフェス
   • 推論が不確かな場合は確信度を明示します。
   • 主なものと副次的なものを明確に区別する表現を使用します。これらを曖昧に混同してはいけません。

4. コマンドを提案する前に、設計スタンスを明示します。

   • CLI が何を最適化しようとしているのかを、短い 1 段落で記述します。
   • CLI がそうであろうとしていないものを明示します。
   • 分類からいきなりコマンドツリーへ飛んではいけません。

5. 設計ブループリントを作成します。

   • references/output-templates.md の構造を使用します。
   • ユーザーがブループリントを求めている場合、または曖昧さやリスクがそれを正当化する場合は、完全なテンプレートを使用します。
   • 素早いリクエストの場合は、目的、分類、分類の根拠、設計スタンス、主要な設計上の帰結、そして重要な未解決の質問のみに圧縮します。
   • 分類を設計上の帰結に直接結び付けます。
   • ブループリントは具体的に保ち、汎用的にしてはいけません。

6. 下流の実装を制約します。

   • 最後に、以下を明示する短い指針セクションを置きます。
     • 何を最適化すべきか
     • 何を最適化すべきでないか
     • 許容されるパターン
     • カテゴリーの誤り
     • v1 の境界と非ゴール

求められる設計規律

すべてのブループリントに対して、以下のルールを徹底します。

• 主なサーフェスと副次的なサーフェス

  • 主なサーフェスを明示的に挙げます。
  • 副次的なサーフェスを明示的に挙げます。
  • 各サーフェスが何のためのものかを明示します。
  • JSON、イベントストリーム、テンプレート、生のペイロード、TUI を、それが主なものか副次的なものかを言わずに「重要」と記述してはいけません。

• 人間優先／バランス型の発見可能性

  • CLI が人間優先またはバランス型である場合は、以下を明示的に扱います。
    • ヘルプの品質
    • 例
    • 発見可能性
    • 適切な場合の explain／describe サーフェス
  • コマンド構造だけを論じ、学習しやすさを無視してはいけません。

• 構造化されたマシン契約

  • CLI に機械可読なサーフェスがある場合は、以下を明示的に述べます。
    • どのコマンドがそれを公開するか
    • 出力形式（--json、--jsonl など）
    • フィールド名が安定しているかどうか
    • 終了コードが重要かどうか
    • スキーマ／フィールド／describe のサポートが必要かどうか
  • 契約が記述されていない限り、サーフェスを「スクリプトフレンドリー」と呼んではいけません。

• リスクのはしご

  • CLI が状態を変更する場合は、少なくとも以下を定義します。
    • 低リスクの操作
    • 中リスクの操作
    • 高リスクの操作
  • 各レベルで期待されるガードレールを明示します。
  • 「注意する」や「確認を追加する」で終わってはいけません。

• 状態モデル

  • CLI がセッション型、長時間実行型、またはアタッチ／デタッチ可能な場合は、セッションの識別とライフサイクルを明示的に記述します。
  • ほぼステートレスな場合は、その旨を明示し、セッションのセマンティクスをでっち上げることを避けます。

• v1 の境界

  • v1 に含めるべきものを明示します。
  • v1 で先送りにすべきものを明示します。
  • 時期尚早な抽象化となるものを明示します。

質問ポリシー

分類やブループリントに影響する質問だけを行ってください。

次のような実装詳細に関する質問から始めないでください:

• 言語の選択
• パースライブラリ
• リポジトリのレイアウト
• 命名の細かい議論
• 正確なフラグの綴り

これらは、CLI の分類や設計上の帰結に実質的に影響する場合にのみ質問してください。

---

レビューモード

目標

CLI とそのソースを調査し、その設計意図を逆推論したうえで、2 つの層でレビューします:

1. 分類の適合性 — 適切な種類の CLI として設計されているか?
2. 実行の品質 — その種類を踏まえて、どれだけうまく実行されているか?

ワークフロー

1. 質問する前に調査します。

   • ヘルプ出力、サブコマンドのヘルプ、ドキュメント、例、パーサーコード、出力コード、エラー処理、状態/セッションのコード、設定サーフェス、テストを調査します。
   • 推測よりも直接的な証拠を優先します。

2. 設計意図を逆推論します。

   • 次を推論します:
     • 見かけ上の目的
     • 想定される主な役割/制御サーフェスの種類
     • 想定される主なユーザー種別
     • 想定されるインタラクション形式
     • 想定されるステートフル性
     • 想定されるリスクプロファイル
     • 既存のセカンダリサーフェス

3. 信頼性をもって推論できないものだけを確認します。

   • 回答が分類やレビューを実質的に変え得る場合にのみ、焦点を絞った確認の質問を行います。
   • CLI やコードからすでに明らかな事実をユーザーに復唱させないでください。

4. 2 つの層でレビューします。

   • 分類の適合性と実行の品質を分けておきます。
   • ユーザーが明示的にその方向への移行を望まない限り、人間主体の CLI をエージェント主体でないことを理由に批判しないでください。

5. 構造化されたレビューを作成します。

   • references/output-templates.md のレビュー構造を使用します。
   • ユーザーが正式なレビューを望む場合、またはカテゴリの緊張が実質的である場合には、完全なテンプレートを使用します。
   • 簡単な依頼の場合は、推論された意図、分類、証拠に裏付けられたカテゴリの誤り、カテゴリ内の弱点、最優先の改善点に圧縮します。
   • カテゴリの誤りとカテゴリ内の実行上の弱点を分けてください。

必須のレビューチェック

レビューする際は、関連する場合に次の領域を明示的に確認してください:

• プライマリサーフェスとセカンダリサーフェスの明確さ

  • CLI は主たるサーフェスが何であるかを明確にしているか?
  • セカンダリサーフェスは実際のコントラクトか、それとも非公式な追加物にすぎないか?

• 発見可能性

  • ヘルプ出力は、主張されているユーザー種別を支えているか?
  • 例、オプションの説明、コマンド構造は、CLI の重心と整合しているか?

• 構造化出力のコントラクト

  • JSON / JSONL / フィールド選択 / 終了コードのサーフェスは明示的かつ安定しているか?
  • 未知のフィールドは拒否されるか、それとも黙って許容されるか?
  • マシン向けサーフェスは、ドキュメントでなされている主張に対して十分に強いか?

• リスクモデル

  • 低・中・高リスクのアクションは意味のある形で分離されているか?
  • confirm / dry-run / preview / audit のガードレールは、リスクプロファイルと整合しているか?

• 状態モデル

  • ステートフル性は正しく扱われているか?
  • attach/detach/resume/session/history の概念は、正当化される場合にのみ使用されているか?

• v1 の規律

  • CLI は一貫した v1 の境界を保っているか?
  • 早すぎる抽象化や欠落したコントラクトを持ち込んでいないか?

レビューのルール

• すべての CLI をエージェントファーストの尺度で評価しないでください。
• 分類が正当化しない限り、生のペイロード、完全なスキーマイントロスペクション、マシンファーストの出力を要求しないでください。
• 現代の CLI をマルチサーフェスシステムとして扱ってください: 1 つの主たる役割、1 つの主たるインタラクション形式、任意のセカンダリサーフェス。
• 強力な推論を優先し、その後に対象を絞った確認を行ってください。
• マシンサポートを批判する際は、問題が次のいずれであるかを明示してください:
  • プライマリ/セカンダリサーフェスの明確さの欠如、
  • 弱いマシンコントラクト、
  • または真のカテゴリの不一致。

---

ハイブリッド CLI の扱い

一部の CLI は、サブコマンドのレベルで複数の役割にまたがっていることがあります。

ハイブリッド CLI のルール:

1. まずプロダクトレベルで分類します — その CLI の重心はどこにあるのでしょうか?
2. サブコマンドが明確に異なる役割に分かれている場合は、その分割を明示的に記録します。
3. 主要な役割(その CLI のアイデンティティと設計上の制約を定義するもの)を明示します。
4. 副次的な役割は、それぞれ独自のローカルな制約を持つ副次的なサーフェスとして明示します。
5. サブコマンドが genuinely 異なる役割を担っている CLI に、単一の役割を無理に押し付けないでください。

例: Docker

• プロダクトレベルの主要な役割: Runtime(その重心はコンテナ実行にあります)。
• docker run、docker exec、docker attach → Runtime の操作。
• docker image ls、docker volume inspect → Capability 的なリソースサーフェス(副次的)。
• docker compose up → Workflow/Orchestration(副次的)。

進化する CLI へのガイダンス:

• CLI があるタイプから別のタイプへ移行している場合は、現在の重心と意図する方向性を明示します。
• 将来の目標だけに基づいて分類しないでください。現在の証拠に基づいて分類し、その軌道を記録します。

---

よくある失敗モード

以下の誤りに注意してください:

• すべての CLI を capability CLI として扱う。
• すべての CLI を runtime CLI として扱う。
• TUI や REPL を、インタラクション形式ではなく役割として扱う。
• ステートフル性を無視する。
• リスクプロファイルを無視する。
• 人間主体の CLI におけるヘルプ/発見可能性を無視する。
• 自動化適合性を、設計上の帰結ではなくトップレベルのアイデンティティとして扱う。
• 人間主体のツールをエージェント専用のパターンに無理に押し込む。
• 契約を定義せずに JSON サーフェスを「強力」と呼ぶ。
• 混合モード CLI における副次的なサーフェスを無視する。
• 設計スタンスを明示せずに、分類から直接コマンドツリーへ飛びつく。
• v1 の境界と非ゴールを明示しない。
• サブコマンドが genuinely 異なる制御サーフェスを担っているハイブリッド CLI に、単一の役割を無理に押し付ける。
• 永続的な設定/ロックファイルの副作用しかなく、真のセッションが存在しない CLI に対して、ステートフル性を過剰に設計する。
• 現在の証拠ではなく、将来の願望によって CLI を分類する。

アウトプットの基準

最終的なアウトプットでは、以下を維持してください:

• 分類について明示する
• 緊張や曖昧さがある場合は、分類の根拠について明示する
• 証拠、確信度、前提について明示する
• 設計上の帰結について明示する
• 主要なサーフェスと副次的なサーフェスについて明示する
• 関連する場合は、発見可能性とマシン契約について明示する
• 変更が存在する場合は、リスクのはしごについて明示する
• ユーザーが要求した深さに合わせてスケールする
• 簡潔でありながら密度が高い
• 汎用的ではなく診断的である

「UX を改善する」や「よりエージェントフレンドリーにする」といった曖昧なアドバイスは、特定の分類と具体的な設計上の帰結に結びついていない限り避けてください。