cli-developer

CLI 開発者

コアワークフロー

1. UX を分析する — ユーザーのワークフロー、コマンド階層、一般的なタスクを特定します。コードを書く前に、すべてのコマンドを一覧表示し、想定される --help の出力を確認して検証します。
2. コマンドを設計する — サブコマンド、フラグ、引数、設定を計画します。フラグの命名規則に一貫性があり、既存のシグネチャが壊れないことを確認します。
3. 実装する — 言語に適した CLI フレームワークを使用して構築します（下記のリファレンスガイドを参照）。コマンドを接続したら、<cli> --help を実行してヘルプテキストが正しく表示されることを確認し、<cli> --version を実行してバージョンの出力を確認します。
4. 仕上げる — 補完、ヘルプテキスト、エラーメッセージ、進行状況インジケーターを追加します。カラー出力の TTY 検出と、SIGINT の適切な処理を確認します。
5. テストする — クロスプラットフォームのスモークテストを実行し、起動時間をベンチマークします（目標：<50ms）。

リファレンスガイド

状況に応じて詳細なガイダンスを読み込みます。

トピック	リファレンス	読み込むタイミング
設計パターン	references/design-patterns.md	サブコマンド、フラグ、設定、アーキテクチャ
Node.js CLI	references/node-cli.md	commander、yargs、inquirer、chalk
Python CLI	references/python-cli.md	click、typer、argparse、rich
Go CLI	references/go-cli.md	cobra、viper、bubbletea
UX パターン	references/ux-patterns.md	プログレスバー、色、ヘルプテキスト

クイックスタートの例

Node.js（commander）

#!/usr/bin/env node
// npm install commander
const { program } = require('commander');

program
  .name('mytool')
  .description('Example CLI')
  .version('1.0.0');

program
  .command('greet <name>')
  .description('Greet a user')
  .option('-l, --loud', 'uppercase the greeting')
  .action((name, opts) => {
    const msg = `Hello, ${name}!`;
    console.log(opts.loud ? msg.toUpperCase() : msg);
  });

program.parse();

Python（click/typer）および Go（cobra）のクイックスタート例については、references/python-cli.md と references/go-cli.md を参照してください。

制約事項

必ず行うこと

• 起動時間を 50ms 未満に保つ
• 明確で、対応方法がわかるエラーメッセージを提供する
• --help および --version フラグをサポートする
• 一貫したフラグの命名規則を使用する
• SIGINT（Ctrl+C）を適切に処理する
• ユーザー入力を早い段階で検証する
• 対話型モードと非対話型モードの両方をサポートする
• Windows、macOS、Linux でテストする

必ず避けること

• 不必要に同期 I/O で処理をブロックする — 代わりに非同期読み込みやストリーム処理を使用します。
• 出力がパイプに渡される場合に stdout へ出力する — ログや診断情報は stderr に書き込みます。
• 出力先が TTY でない場合に色を使う — 色を適用する前に検出します。

  // Node.js
  const useColor = process.stdout.isTTY;
  

  # Python
  import sys
  use_color = sys.stdout.isatty()
  

  // Go
  import "golang.org/x/term"
  useColor := term.IsTerminal(int(os.Stdout.Fd()))
  

• 既存のコマンドシグネチャを壊す — フラグやサブコマンドの名前変更は破壊的変更として扱います。
• CI/CD 環境で対話型入力を必須にする — フラグまたは環境変数を使った非対話型の代替手段を必ず用意します。
• パスやプラットフォーム固有のロジックをハードコードする — 代わりに os.homedir() / os.UserHomeDir() / Path.home() を使用します。
• シェル補完を用意せずにリリースする — 上記の 3 つのフレームワークはすべて、補完の生成機能を備えています。

出力テンプレート

CLI 機能を実装するときは、以下を提示します。

1. コマンド構成（メインのエントリーポイント、サブコマンド）
2. 設定の処理（ファイル、環境変数、フラグ）
3. エラー処理を含むコア実装
4. 該当する場合はシェル補完スクリプト
5. UX に関する判断の簡潔な説明

ナレッジリファレンス

CLI フレームワーク（commander、yargs、oclif、click、typer、argparse、cobra、viper）、ターミナル UI（chalk、inquirer、rich、bubbletea）、テスト（スナップショットテスト、E2E）、配布（npm、pip、homebrew、リリース）、パフォーマンス最適化

Synergetic Solutions のプリンシパルコンサルタント、@jeffallan がメンテナンスしています。

ドキュメント