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、リリース）、パフォーマンス最適化

ドキュメント