Shell スクリプトのベストプラクティス (Community)

AI エージェントと LLM 向けに設計されたシェルスクリプティングの包括的なベストプラクティスガイド。9つのカテゴリに分かれた49のルールを含み、重大度に応じて優先順位付けされています（セーフティ、ポータビリティなどの重大事項から、スタイルなどの段階的な改善まで）。各ルールには詳細な説明、間違った実装と正しい実装を比較した実例、および具体的な影響メトリクスが含まれています。

適用するべき場面

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

• 新しい bash または POSIX シェルスクリプトを作成する
• セキュリティ脆弱性についてシェルスクリプトを検査する
• サイレント障害または予期しない動作をするスクリプトをデバッグする
• Linux、macOS、コンテナ間でスクリプトを移植する
• シェルスクリプトのパフォーマンスを最適化する
• シェルスクリプトを使用して CI/CD パイプラインを構築する

ルールカテゴリの優先順位

優先度	カテゴリ	影響	プレフィックス	ルール数
1	セーフティ & セキュリティ	CRITICAL	safety-	6
2	ポータビリティ	CRITICAL	port-	5
3	エラーハンドリング	HIGH	err-	8
4	変数 & データ	HIGH	var-	5
5	クォーティング & 展開	MEDIUM-HIGH	quote-	6
6	関数 & 構造	MEDIUM	func-	5
7	テスト & 条件分岐	MEDIUM	test-	5
8	パフォーマンス	LOW-MEDIUM	perf-	6
9	スタイル & フォーマット	LOW	style-	3

クイックリファレンス

1. セーフティ & セキュリティ (CRITICAL)

• safety-command-injection - ユーザー入力からのコマンドインジェクションを防ぐ
• safety-eval-avoidance - 動的コマンドに eval を使用しない
• safety-absolute-paths - 外部コマンドに絶対パスを使用する
• safety-temp-files - セキュアな一時ファイルを作成する
• safety-suid-forbidden - シェルスクリプトに SUID/SGID を使用しない
• safety-argument-injection - ダブルダッシュで引数インジェクションを防ぐ

2. ポータビリティ (CRITICAL)

• port-shebang-selection - ポータビリティのニーズに基づいて shebang を選択する
• port-avoid-bashisms - POSIX スクリプトで Bash 固有の機能を避ける
• port-printf-over-echo - ポータビリティのために echo の代わりに printf を使用する
• port-export-syntax - ポータブルな export 構文を使用する
• port-test-portability - ポータブルなテスト構造を使用する

3. エラーハンドリング (HIGH)

• err-strict-mode - エラー検出用にストリクトモードを使用する
• err-exit-codes - 意味のある終了コードを使用する
• err-trap-cleanup - 終了時のクリーンアップに trap を使用する
• err-stderr-messages - エラーメッセージを stderr に送信する
• err-pipefail - パイプラインエラーをキャッチするために pipefail を使用する
• err-check-commands - コマンド成功を明示的にチェックする
• err-shellcheck - 静的解析に ShellCheck を使用する
• err-debug-tracing - set -x と PS4 でデバッグトレーシングを使用する

4. 変数 & データ (HIGH)

• var-use-arrays - 文字列の代わりにリストに配列を使用する
• var-local-scope - 関数変数に local を使用する
• var-naming-conventions - 変数命名規則に従う
• var-readonly-constants - 定数に readonly を使用する
• var-default-values - デフォルト値にパラメータ展開を使用する

5. クォーティング & 展開 (MEDIUM-HIGH)

• quote-always-quote-variables - 変数展開を常にクォートする
• quote-dollar-at - 引数渡しに "$@" を使用する
• quote-command-substitution - コマンド代替をクォートする
• quote-brace-expansion - 変数の明確化にブレースを使用する
• quote-here-documents - 複数行文字列にヒアドキュメントを使用する
• quote-glob-safety - グローブ展開を明示的に制御する

6. 関数 & 構造 (MEDIUM)

• func-main-pattern - main() 関数パターンを使用する
• func-single-purpose - 単一目的の関数を作成する
• func-return-values - 戻り値を正しく使用する
• func-documentation - ヘッダーコメントで関数を文書化する
• func-avoid-aliases - エイリアスの代わりに関数を優先する

7. テスト & 条件分岐 (MEDIUM)

• test-double-brackets - bash でテストに [[ ]] を使用する
• test-arithmetic - 算術比較に (( )) を使用する
• test-explicit-empty - 明示的な空/非空文字列テストを使用する
• test-file-operators - 正しいファイルテスト演算子を使用する
• test-case-patterns - パターンマッチングに case を使用する

8. パフォーマンス (LOW-MEDIUM)

• perf-builtins-over-external - 外部コマンドより組み込みコマンドを使用する
• perf-avoid-subshells - 不要なサブシェルを避ける
• perf-process-substitution - 一時ファイルにプロセス代替を使用する
• perf-read-files - ファイルを効率的に読む
• perf-parameter-expansion - 文字列操作にパラメータ展開を使用する
• perf-batch-operations - ループの代わりにバッチ操作を行う

9. スタイル & フォーマット (LOW)

• style-indentation - 一貫性のあるインデントを使用する
• style-file-structure - 一貫したファイル構造に従う
• style-comments - 有用なコメントを書く

使い方

詳細な説明とコード例については、個別のリファレンスファイルを読んでください：

• セクション定義 - カテゴリ構造および影響レベル
• ルールテンプレート - 新しいルール追加用テンプレート

リファレンスファイル

ファイル	説明
AGENTS.md	すべてのルールを含む完全なコンパイルガイド
references/_sections.md	カテゴリ定義と順序付け
assets/templates/_template.md	新しいルール用テンプレート
metadata.json	バージョンおよびリファレンス情報

主要出典

• Google Shell Style Guide
• ShellCheck
• Greg's Wiki (wooledge.org)
• POSIX Shell Specification