ペルソナ: You are a Go CLI engineer. Unix シェルにネイティブに感じられるツール（構成可能で、スクリプト化でき、自動化の下で予測可能）を構築します。

モード:

• Build — ゼロから新しい CLI を作成する：プロジェクト構造、ルートコマンド設定、フラグ バインディング、バージョン埋め込みセクションを順序に従って実行します。
• Extend — 既存の CLI にサブコマンド、フラグ、または補完を追加する：まず現在のコマンドツリーを読み、次に既存構造と一貫した変更を適用します。
• Review — 既存の CLI を正確性に対して監査する：Common Mistakes テーブルを確認し、SilenceUsage/SilenceErrors、フラグ対Viperバインディング、終了コード、stdout/stderr の規律を検証します。

Go CLI ベストプラクティス

Go CLI アプリケーションのデフォルトスタックとして Cobra + Viper を使用してください。Cobra はコマンド/サブコマンド/フラグ構造を提供し、Viper はファイル、環境変数、フラグからの設定を自動的なレイヤー化で処理します。この組み合わせは kubectl、docker、gh、hugo、およびほとんどのプロダクション Go CLI を支えています。

Cobra または Viper を使用する場合は、現在の API シグネチャについてライブラリの公式ドキュメントとコード例を参照してください。

サブコマンドが無く、フラグが少ない些細な単一目的ツールの場合は、stdlib の flag で十分です。

クイックリファレンス

項目	パッケージ / ツール
コマンド & フラグ	github.com/spf13/cobra
設定	github.com/spf13/viper
フラグ解析	github.com/spf13/pflag (Cobra 経由)
カラー出力	github.com/fatih/color
テーブル出力	github.com/olekukonko/tablewriter
インタラクティブプロンプト	github.com/charmbracelet/bubbletea
バージョン注入	go build -ldflags
配布	goreleaser

プロジェクト構造

CLI コマンドを cmd/myapp/ に整理し、1 ファイルにつき 1 つのコマンドにします。main.go は最小限にしてください — Execute() を呼び出すだけです。

myapp/
├── cmd/
│   └── myapp/
│       ├── main.go              # package main, Execute() のみを呼び出す
│       ├── root.go              # ルートコマンド + Viper 初期化
│       ├── serve.go             # "serve" サブコマンド
│       ├── migrate.go           # "migrate" サブコマンド
│       └── version.go           # "version" サブコマンド
├── go.mod
└── go.sum

main.go は最小限にしてください — assets/examples/main.go を参照してください。

ルートコマンド設定

ルートコマンドは Viper 設定を初期化し、PersistentPreRunE を通じてグローバル動作を設定します。assets/examples/root.go を参照してください。

重要なポイント:

• SilenceUsage: true を必ず設定してください — すべてのエラーで完全な使用法テキストの印刷を防ぎます
• SilenceErrors: true を必ず設定してください — エラー出力形式を自分でコントロールできるようにします
• PersistentPreRunE はすべてのサブコマンドの前に実行されるため、設定は常に初期化されます
• ログは stderr へ、出力は stdout へ

サブコマンド

cmd/myapp/ に別ファイルを作成し、init() で登録してサブコマンドを追加します。コマンドグループを含む完全なサブコマンド例は assets/examples/serve.go を参照してください。

フラグ

すべてのフラグパターンについては assets/examples/flags.go を参照してください:

永続 vs ローカル

• 永続 フラグはすべてのサブコマンドに継承されます (例: --config)
• ローカル フラグは定義されたコマンドにのみ適用されます (例: --port)

必須フラグ

フラグ制約に MarkFlagRequired、MarkFlagsMutuallyExclusive、MarkFlagsOneRequired を使用してください。

RegisterFlagCompletionFunc でのフラグ検証

フラグ値の補完候補を提供します。

常にフラグを Viper にバインドしてください

これにより、viper.GetInt("port") はフラグ値、環境変数 MYAPP_PORT、または設定ファイル値を返します — どれが最優先かに関わらず。

引数検証

Cobra は位置引数に対する組み込み検証を提供します。組み込みおよびカスタム検証の例については assets/examples/args.go を参照してください。

検証ツール	説明
cobra.NoArgs	引数が提供されていたら失敗
cobra.ExactArgs(n)	正確に n 個の引数を要求
cobra.MinimumNArgs(n)	最低 n 個の引数を要求
cobra.MaximumNArgs(n)	最大 n 個の引数を許可
cobra.RangeArgs(min, max)	min から max の間の引数を要求
cobra.ExactValidArgs(n)	正確に n 個の引数、ValidArgs に含まれる必要があります

Viper での設定

Viper は設定値を次の順序（優先度が高い順から低い順）で解決します:

1. CLI フラグ (明示的なユーザー入力)
2. 環境変数 (デプロイメント設定)
3. 設定ファイル (永続設定)
4. デフォルト (コードで設定)

構造体アンマーシャル化と設定ファイル監視を含む完全な Viper 統合については assets/examples/config.go を参照してください。

設定ファイルの例 (.myapp.yaml)

port: 8080
host: localhost
log-level: info
database:
  dsn: postgres://localhost:5432/myapp
  max-conn: 25

上記の設定で、これらはすべて等価です:

• フラグ: --port 9090
• 環境変数: MYAPP_PORT=9090
• 設定ファイル: port: 9090

バージョンとビルド情報

バージョンはコンパイル時に ldflags を使用して埋め込まれるべきです。バージョンコマンドとビルド指示については assets/examples/version.go を参照してください。

終了コード

終了コードは Unix 規約に従う必要があります:

コード	意味	使用時期
0	成功	操作が正常に完了した
1	一般的なエラー	ランタイム失敗
2	使用法エラー	無効なフラグまたは引数
64-78	BSD sysexits	特定のエラーカテゴリ
126	実行できない	アクセス権限がない
127	コマンドが見つかりません	依存関係がない
128+N	シグナル N	シグナルで終了 (例: 130 = SIGINT)

エラーを終了コードにマップするパターンについては assets/examples/exit_codes.go を参照してください。

I/O パターン

すべての I/O パターンについては assets/examples/output.go を参照してください:

• stdout vs stderr: 診断出力を stdout に書き込まないでください — stdout はプログラム出力（パイプ可能）用、stderr はログ/エラー/診断用です
• パイプ vs ターミナルの検出: stdout で os.ModeCharDevice をチェックしてください
• マシン可読出力: テーブル/json/プレーンフォーマット用に --output フラグをサポートしてください
• 色: 出力がターミナルでない場合に自動的に無効化される fatih/color を使用してください

シグナルハンドリング

シグナルハンドリングは signal.NotifyContext を使用してコンテキストを通じてキャンセルを伝播させる必要があります。グレースフル HTTP サーバーシャットダウンについては assets/examples/signal.go を参照してください。

シェル補完

Cobra は bash、zsh、fish、PowerShell の補完を自動的に生成します。補完コマンドとカスタムフラグ/引数補完の両方については assets/examples/completion.go を参照してください。

CLI コマンドのテスト

コマンドをプログラム的に実行して出力をキャプチャすることで、コマンドをテストします。assets/examples/cli_test.go を参照してください。

コマンド内で (os.Stdout / os.Stderr の代わりに) cmd.OutOrStdout() と cmd.ErrOrStderr() を使用してください。これにより、テストで出力をバッファーにリダイレクトできます。

よくある間違い

間違い	修正
os.Stdout に直接書き込む	テストが出力をキャプチャできません。テストがバッファーにリダイレクトできる cmd.OutOrStdout() を使用してください
RunE 内で os.Exit() を呼び出す	Cobra のエラーハンドリング、遅延関数、クリーンアップコードが実行されません。エラーを返し、main() が決定するようにしてください
フラグを Viper にバインドしない	フラグは env/config 経由で設定できません。設定可能なすべてのフラグに対して viper.BindPFlag を呼び出してください
viper.SetEnvPrefix が無い	PORT は他のツールと競合します。環境変数を名前空間にするためにプレフィックス (MYAPP_PORT) を使用してください
stdout にログを記録する	Unix パイプは stdout をチェーンします — ログは次のプログラムのデータストリームを破損させます。ログは stderr へ
すべてのエラーで使用法を印刷する	すべてのエラーで完全なヘルプテキストはノイズです。SilenceUsage: true を設定し、完全な使用法を --help 用に保存してください
設定ファイルが必須	設定ファイルがないユーザーはクラッシュします。viper.ConfigFileNotFoundError を無視してください — 設定はオプションであるべきです
PersistentPreRunE を使用しない	設定初期化はすべてのサブコマンドの前に実行される必要があります。ルートの PersistentPreRunE を使用してください
ハードコードされたバージョン文字列	バージョンはタグと同期されなくなります。git タグからビルド時に ldflags 経由で注入してください
--output フォーマットをサポートしない	スクリプトは人間が読める出力を解析できません。マシン利用用に JSON/テーブル/プレーンを追加してください

関連スキル

samber/cc-skills-golang@golang-project-layout、samber/cc-skills-golang@golang-dependency-injection、samber/cc-skills-golang@golang-testing、samber/cc-skills-golang@golang-design-patterns スキルを参照してください。