shell-conventions

シェルの規約

シェル作業が主なタスクである場合は、常にこれらの規約を適用してください。

対象範囲： シェルスクリプト、シェルのスニペット、Makefile、justfile の規約の適用。スクリプトの生成、大規模なシェルのリファクタリング、Python、CI ワークフローの YAML は対象外です。

ディスパッチ

$ARGUMENTS	アクション
Active（.sh、.bash、.zsh、Makefile、または justfile の編集時に自動で呼び出されます）	以下のアクティブオペレーター契約を適用します
Empty	モードの概要とトリガーの境界を表示します
check	規約のみを確認します

使用する場面

• 既存のシェルスクリプト、シェルのスニペット、Makefile、または justfile を編集する場合
• 移植性、クォート、シバン、env の使い方、またはタスク名を標準化する場合
• 基本的な安全性とリポジトリのシェルの慣習に照らして、シェルの変更をレビューする場合
• シェルコードがリポジトリで必須とされる規約に従っているか確認する場合

標準用語

標準用語	意味
shell-primary	主なタスクが、シェル、Make、または just のコードを付随的に触るのではなく、編集またはレビューすることです
conventions-only	自動化を再設計せずに、スタイル、移植性、安全性を確認または改善することです
env-based shebang	ハードコードされたパスではなく、環境を通じてインタープリターを解決するシバンです
incidental shell	より大きな非シェルタスクの中に、補助的な要素として少量のシェルが含まれることです
target hygiene	明確なタスク名、予測可能な動作、破壊的な操作への明示的な対応です

オペレーター契約

アクティブな自動呼び出し

1. シェル作業が主なタスクであり、より広範なタスクに付随するものではないことを確認します。
2. 編集対象のファイルに、シェル固有の規約を適用します。
3. シェルスクリプトとスニペットについては、references/script-baseline.md を読みます。
4. Makefile または justfile の作業については、references/make-just.md を読みます。
5. タスクにシェルと CI、デプロイ、またはコード生成の懸念事項が混在する場合は、references/redirection-boundaries.md を読みます。
6. 作業は規約の適用に限定し、スクリプトの設計や自動化のアーキテクチャにまで広げないでください。

空欄／ヘルプ

1. 3 つの公開エントリーパス、つまりアクティブな自動呼び出し、空欄の概要、check を示します。
2. このスキルが対象とする内容、つまりシェルの移植性、クォート、env の使い方、Make または just の規約を要約します。
3. 主な対象外のケースとして、CI YAML、リリース自動化の設計、Python、スクリプト生成を挙げます。
4. 依頼が規約の適用範囲外の場合は、shell-scripter または devops-engineer を案内します。

Check

1. references/check-mode.md を読みます。
2. 関連するシェル、Make、または just のファイルを、規約への準拠のみを対象にレビューします。
3. 全面的な書き換えに範囲を広げずに、違反、リスク、推奨される修正を報告します。
4. 依頼が実際には生成、変換、または CI ワークフローに関するものである場合は、規約のみのレビューを行うのではなく、適切な担当へ案内します。

自動呼び出しのトリガーロジック

• 既存の .sh、.bash、.zsh、Makefile、または justfile の編集またはレビューが主な作業である場合にトリガーします。
• ユーザーがシェルの移植性、クォート、シバン、env、.PHONY、$ のエスケープ、またはタスク名の整理を依頼した場合にトリガーします。
• より大きな Python、JS、またはインフラストラクチャのタスクに、シェルが付随的に含まれるだけの場合はトリガーしません。
• CI ワークフロー YAML、デプロイパイプライン、またはリリース自動化の設計ではトリガーしません。これらは devops-engineer の担当です。
• 新しいスクリプトの作成、シェル方言の変換、または大規模なシェルのリファクタリングではトリガーしません。これらは shell-scripter の担当です。

段階的な情報開示

• 一度にすべてを読み込むのではなく、指示に応じて参照ファイルを読みます。
• シェルスクリプトとスニペットについては、必要に応じて references/script-baseline.md を読み込みます。
• Makefile と justfile については、必要に応じて references/make-just.md を読み込みます。
• シェル作業が CI、リリース自動化、またはスクリプト生成と重なる場合は、必要に応じて references/redirection-boundaries.md を読み込みます。
• check については、必要に応じて references/check-mode.md を読み込みます。

基本規約

シェルスクリプトとスニペット

• 配列、[[ ]]、プロセス置換が不要なシンプルな自動化では、POSIX sh を優先してください。
• bash 専用機能の利点が明確な場合に限り、bash を使用してください。
• インタープリターのパスをハードコードせず、env ベースのシバンを使用してください。
• bash では、明確な理由がない限り、set -euo pipefail から始めてください。
• 移植性の高い sh では、set -eu を使用し、pipefail は避けてください。
• 意図的にワード分割が必要な場合を除き、変数展開を引用符で囲んでください。
• 保証されていないツールに依存する前に、command -v tool >/dev/null 2>&1 を使用してください。
• 依存関係を追加する前に、組み込み機能と標準ユーティリティを優先してください。
• シェル関数は短く、単一の目的に絞ってください。

Make と Just

• Make ターゲットはタスク指向にし、ファイルの内容が大きい場合は help ターゲットで説明してください。
• ファイルを生成しない Make ターゲットには .PHONY を使用してください。
• 可能な限り、レシピを冪等にしてください。
• Makefile では、レシピ内の $ を $$ としてエスケープしてください。
• justfile では、繰り返しのタスクを大幅に簡素化できる場合にのみ、パラメーターを使用してください。
• 破壊的な動作を、曖昧なターゲット名の背後に隠さないでください。

命名と構成

• 関数名は小文字で、内容がわかる名前にしてください。
• 1 文字の名前よりも、project_root、target_path、output_file を優先してください。
• 環境変数名は大文字にしてください。
• 無言で失敗させるよりも、早期検証と明確な使用方法の表示を優先してください。

参照ファイル一覧

ファイル	目的	読むタイミング
references/script-baseline.md	シェルの移植性、安全性、引用符の使用、構成に関する基本ルール	スクリプトまたはスニペットの作業
references/make-just.md	Makefile と justfile の規約、冪等性、$ のエスケープ、ターゲットの適切な管理	Makefile または justfile の作業
references/redirection-boundaries.md	CI YAML、リリース自動化、スクリプト生成、大規模なリファクタリングにおけるリダイレクトのルール	複数の領域にまたがる作業、または対象範囲が曖昧なシェル作業
references/check-mode.md	規約のみを対象とした検証で求められる内容	check モード

重要なルール

1. インタープリターのパスをハードコードせず、必ず env ベースのシバンを使用してください。
2. 意図的な分割が必要な場合を除き、変数展開を引用符で囲んでください。
3. 必要な場合に限り bash を使用し、それ以外では移植性の高い sh を優先してください。
4. より安全な代替手段がなく、リスクを説明できる場合を除き、eval を使用しないでください。
5. 外部コマンドが初めて使われる前に、必要なコマンドが利用可能か検証してください。
6. 状態を変更する Make または Just のタスクには、明確で予測しやすい名前を付けてください。
7. スクリプト生成と大規模なリファクタリングは shell-scripter に任せてください。このスキルの対象は規約のみです。

対象範囲

対象： シェルのスタイル、移植性、シバン、引用符の使用、環境変数の使用、Make または just の規約、規約のみを対象としたレビュー。

対象外： Python、CI ワークフロー YAML、デプロイ自動化の設計、スクリプト生成、大規模なシェルの書き換え。