unix-cli

UNIX/POSIX 標準 CLI のベストプラクティス

AI エージェントと LLM 向けに設計された、UNIX の慣習に従うコマンドラインツールを構築するための包括的なガイドラインです。重要度の高いもの（引数の処理、終了コード、出力ストリーム）から段階的なもの（設定と環境）まで、8 つのカテゴリにわたる 44 のルールが含まれています。

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• 任意の言語で新しい CLI ツールを作成するとき
• コマンドライン引数やフラグを解析するとき
• stdout と stderr のどちらに出力するかを決めるとき
• 適切な終了コードを選ぶとき
• SIGINT や SIGTERM などのシグナルを処理するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	引数とフラグの設計	CRITICAL	args-
2	終了コード	CRITICAL	exit-
3	出力ストリーム	CRITICAL	output-
4	エラー処理	HIGH	error-
5	I/O と合成	HIGH	io-
6	ヘルプとドキュメント	MEDIUM-HIGH	help-
7	シグナルと堅牢性	MEDIUM	signal-
8	設定と環境	MEDIUM	config-

クイックリファレンス

1. 引数とフラグの設計（CRITICAL）

• args-use-getopt - 標準的な引数解析ライブラリを使用する
• args-provide-long-options - すべての短いオプションに長いオプションを用意する
• args-support-double-dash - オプションを終了するためのダブルダッシュをサポートする
• args-require-help-version - --help と --version オプションを実装する
• args-prefer-flags-over-positional - 位置引数よりフラグを優先する
• args-use-standard-flag-names - 標準的なフラグ名を使用する
• args-never-read-secrets-from-flags - コマンドラインフラグから秘密情報を読み取らない
• args-support-option-bundling - オプションの連結をサポートする

2. 終了コード（CRITICAL）

• exit-zero-for-success - 成功の場合にのみゼロを返す
• exit-use-standard-codes - 標準の終了コードを使用する
• exit-signal-codes - シグナルによる終了には 128+N を使用する
• exit-partial-success - 部分的な成功を一貫して処理する
• exit-distinguish-error-types - 異なる終了コードでエラーの種類を区別する

3. 出力ストリーム（CRITICAL）

• output-stdout-for-data - データは stdout のみに書き込む
• output-stderr-for-errors - エラーと診断情報は stderr に書き込む
• output-detect-tty - 人間向けの出力では TTY を検出する
• output-provide-machine-format - 機械可読な出力形式を用意する
• output-line-based-text - テキストストリームでは行単位の出力を使用する
• output-respect-no-color - NO_COLOR 環境変数に従う

4. エラー処理（HIGH）

• error-include-program-name - エラーメッセージにプログラム名を含める
• error-actionable-messages - 実行可能な対処を示すエラーメッセージにする
• error-use-strerror - システムエラーには strerror を使用する
• error-avoid-stack-traces - ユーザー向けのエラーでスタックトレースを避ける
• error-validate-early - 入力を早期に検証し、問題があれば速やかに終了する

5. 入出力と構成（HIGH）

• io-support-stdin - 標準入力からの読み取りをサポートする
• io-write-to-stdout - デフォルトで標準出力に出力する
• io-be-stateless - ステートレスな操作を設計する
• io-handle-binary-safely - バイナリデータを安全に扱う
• io-atomic-writes - アトミックなファイル書き込みを使用する
• io-handle-multiple-files - 複数の入力ファイルを一貫して扱う

6. ヘルプとドキュメント（MEDIUM-HIGH）

• help-show-usage-on-error - 引数エラー時に簡潔な使用方法を表示する
• help-structure-help-output - ヘルプ出力を一貫した形式にする
• help-show-defaults - ヘルプにデフォルト値を表示する
• help-include-examples - ヘルプに実用的な例を含める
• help-version-format - バージョン出力を正しくフォーマットする

7. シグナルと堅牢性（MEDIUM）

• signal-handle-sigint - SIGINT を適切に処理する
• signal-handle-sigterm - クリーンなシャットダウンのために SIGTERM を処理する
• signal-handle-sigpipe - パイプ切断時の SIGPIPE を処理する
• signal-cleanup-on-second-interrupt - 2 回目の割り込みではクリーンアップを省略する

8. 設定と環境（MEDIUM）

• config-follow-xdg - XDG Base Directory Specification に従う
• config-precedence-order - 正しい優先順位で設定を適用する
• config-env-naming - 一貫性のある環境変数の命名を使用する
• config-never-store-secrets - 設定ファイルや環境変数にシークレットを保存しない
• config-respect-standard-vars - 標準の環境変数を尊重する

使い方

詳しい説明とコード例については、個々のリファレンスファイルをお読みください。

• セクションの定義 - カテゴリー構成と影響度
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報