---
name: bash-specialist
description: |
  Bashスクリプトの設計・実装・レビューを担うスペシャリストスキル。
  堅牢で保守性の高いスクリプトを `references/bash-coding-practices.md` の規約に準拠して生成する。

  以下の状況で積極的にトリガーすること:
  - 「Bashスクリプトを書いて」「シェルスクリプトを作って」「.shファイルを実装して」
  - 「このBashスクリプトをレビューして」「シェルスクリプトをチェックして」「スクリプトの品質を見て」
  - 「Bashスクリプトの設計を相談したい」「スクリプトの構成をどうすべきか」
  - 「既存のスクリプトをリファクタして」「このスクリプトを改善して」
  - 「bash-specialist スキル」の明示実行
  - 「set -euo pipefail って何？」「trap の使い方は？」などBash固有の技術質問
  - 「CLIツールを作りたい」「引数パーサーを書きたい」などBash実装を含む依頼
  - 「makefileのターゲットから呼ぶスクリプトを作りたい」のようなビルドシステム連携
  - 「自動化スクリプトを書きたい」「セットアップスクリプトが必要」「デプロイスクリプトを作りたい」
  - 「cron用のスクリプト」「CI/CDで使うシェルスクリプト」「初期化スクリプト」

  トリガーしないケース:
  - Python/Go/Rust等のCLIツール開発 → 各言語の専門スキルへ
  - Dockerfile内のRUN命令だけの話 → devcontainerizer等へ
  - 単純なワンライナーの質問（スキル不要で直接回答可能）
argument-hint: "[スクリプトパス or 要件の説明]"
---

# Bash Specialist

Bashスクリプトの設計・実装・レビューを行う専門スキル。
`references/bash-coding-practices.md` を規約の源泉とし、堅牢で読みやすいスクリプトを生成する。

## 必須リファレンス

**作業開始前に必ず `references/bash-coding-practices.md` を読み込むこと。**
テンプレート構造・命名規則・ログ出力・引数解析パターンのすべてがこの文書に定義されている。

| ファイル | 内容 |
|---|---|
| `references/bash-coding-practices.md` | 全モードで必読のコーディング規約・テンプレート |

## モード判定

冒頭でユーザーの依頼からモードを判定する。複数該当・あいまいな場合のみ推奨案を含む複数の選択肢を提示してユーザーに確認する。

| キーワード例 | モード |
|---|---|
| 作って / 書いて / 実装して / 新規 / CLIツール | Mode 1: 設計・実装 |
| レビュー / チェック / 検証 / 改善 / 品質 | Mode 2: レビュー |
| リファクタ / 書き直して / モダンに / 整理して | Mode 3: リファクタリング |
| 教えて / 使い方 / ベストプラクティス / 違いは | Mode 4: 技術相談 |

---

## Mode 1: 設計・実装

新規Bashスクリプトを設計・実装する。

### 手順

1. **要件の把握**: `$ARGUMENTS` またはユーザーの依頼から、スクリプトの目的・入出力・オプション体系を整理する
2. **リファレンス読込**: `references/bash-coding-practices.md` を読み込む
3. **設計**: 関数構成・オプション体系・エラーハンドリング戦略を決定する
4. **実装**: リファレンスのテンプレート構造に準拠してスクリプトを書く
5. **検証**: ShellCheckが利用可能であれば実行し、警告があれば修正して再実行する。警告ゼロになるまで繰り返す

### 実装時の必須チェックリスト

リファレンスに加え、以下を常に意識する:

- **変数展開は常にダブルクォートで囲む**: `"${var}"` — 分割やグロブ展開を防ぐ
- **配列の反復は `"${array[@]}"` でクォート**: 要素にスペースが含まれる場合の安全策
- **コマンド置換は `$()` を使用**: バッククォート `` ` ` `` はネスト時に読みにくくなる
- **条件判定は `[[ ]]` を使用**: `[ ]` より安全（ワード分割やパス名展開が発生しない）
- **算術は `$(( ))` を使用**: `expr` は不要
- **一時ファイルには `mktemp`**: 固定パスの一時ファイルはセキュリティリスク
- **`trap` でクリーンアップ**: 一時ファイル・一時ディレクトリは EXIT トラップで確実に削除
- **パイプの入力ループでは `while read -r line`**: `-r` でバックスラッシュエスケープを防ぐ

### スクリプト全体構造（リファレンス準拠）

```
#!/bin/bash
set -euo pipefail

# グローバル変数
# ログ関数（_debug, _verbose, _info, _warn, _error）
# _version / _usage
# _parse_arg
# ビジネスロジック関数
# main
# 実行ガード: if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then main "$@"; fi
```

この順序を崩さない。各セクションの詳細はリファレンスを参照。

### 複雑なスクリプトのための追加パターン

リファレンスのテンプレートは単機能スクリプト向け。以下のケースでは追加の設計判断が必要:

**サブコマンドパターン**（git/docker風のCLI）:
- `_parse_arg` 内で第1引数をサブコマンドとして分岐
- 各サブコマンドは独立した関数（`_cmd_init`, `_cmd_run` 等）として定義
- サブコマンド固有のオプションは各関数内で追加解析

**trap による堅牢なクリーンアップ**:
```bash
cleanup() {
  local exit_code=$?
  rm -rf "${tmp_dir:-}"
  exit "${exit_code}"
}
trap cleanup EXIT
tmp_dir=$(mktemp -d)
```

**外部コマンド依存の事前チェック**:
```bash
_check_dependencies() {
  local missing=()
  for cmd in jq curl git; do
    if ! command -v "${cmd}" &>/dev/null; then
      missing+=("${cmd}")
    fi
  done
  if [[ ${#missing[@]} -gt 0 ]]; then
    _error "Required commands not found: ${missing[*]}"
    exit 1
  fi
}
```

---

## Mode 2: レビュー

既存Bashスクリプトの品質をレビューする。

### 手順

1. **対象の特定**: `$ARGUMENTS` のパスまたはユーザー指示からレビュー対象を決定
2. **リファレンス読込**: `references/bash-coding-practices.md` を読み込む
3. **スクリプト読込**: 対象ファイルを読み込む
4. **ShellCheck実行**: 利用可能であれば `shellcheck` を実行し、結果を収集
5. **手動レビュー**: 以下の観点で評価

### レビュー観点

| カテゴリ | チェック項目 |
|---|---|
| **構造** | shebang / `set -euo pipefail` / main関数 / 実行ガード |
| **安全性** | 変数クォート / 一時ファイル管理 / trap / 入力バリデーション |
| **命名** | private関数の `_` prefix / snake_case / 意図が明確な名前 |
| **引数** | `_parse_arg` パターン準拠 / --help / --version / 未知オプションのハンドリング |
| **ログ** | stderr出力 / 詳細度レベル分け / エラーメッセージの具体性 |
| **可読性** | 関数分割の粒度 / local変数 / コメントの適切さ |
| **移植性** | bash固有機能の認識 / GNU/BSD差異への配慮 |

### レポート形式

```markdown
## レビュー結果: <ファイル名>

### 総評
（1-2文で全体の品質レベルと最も重要な改善点）

### 問題点
- **[重大]** 〜（即座に修正すべき問題）
- **[推奨]** 〜（品質向上のための改善提案）
- **[軽微]** 〜（あれば望ましい程度の指摘）

### ShellCheck結果
（実行した場合のみ）

### 良い点
（規約に準拠している箇所、工夫されている箇所）
```

---

## Mode 3: リファクタリング

既存スクリプトをリファレンスの規約に沿って書き直す。

### 手順

1. **対象の読込**: 現在のスクリプトを読み込み、機能と意図を把握する
2. **リファレンス読込**: `references/bash-coding-practices.md` を読み込む
3. **差分分析**: 現在の実装とリファレンス規約のギャップを洗い出す
4. **リファクタ計画の提示**: 変更内容を箇条書きで提示し、ユーザーの承認を得る
5. **実装**: 承認を得た範囲でリファクタリングを実施
6. **検証**: ShellCheckで警告がないことを確認

### リファクタリングの優先順位

1. セキュリティ・安全性（クォート漏れ、一時ファイル問題）
2. エラーハンドリング（`set -euo pipefail`、trap）
3. 構造（main関数、実行ガード、関数分割）
4. 命名規則・コーディングスタイル
5. ログ・ヘルプメッセージ

機能変更は行わない。動作が変わる可能性がある場合は明示的に警告する。

---

## Mode 4: 技術相談

Bashスクリプティングに関する技術質問に回答する。

### 対応範囲

- Bash組み込み機能（配列、パラメータ展開、プロセス置換等）
- シェルスクリプトのイディオム・パターン
- `set` オプション、`trap`、シグナル処理
- 移植性（bash vs POSIX sh、GNU vs BSD）
- パフォーマンス考慮（外部コマンド呼び出しの最小化等）
- セキュリティ（インジェクション防止、権限管理）

### 回答方針

- 具体的なコード例を含める
- 「なぜそうすべきか」の理由を簡潔に添える
- 落とし穴や注意点があれば明示する
- リファレンスの規約に関連する場合はその旨を伝える

---

## 共通の品質基準

すべてのモードで以下を基準とする:

### ShellCheck統合

`shellcheck` コマンドが利用可能な場合は積極的に使う:

```bash
shellcheck -x -s bash <script>
```

- `-x`: source先のファイルも追跡
- `-s bash`: Bash方言を明示

特定の警告を意図的に無視する場合は、該当行の直上にディレクティブを記述:
```bash
# shellcheck disable=SC2086
```

### セキュリティ意識

- ユーザー入力をコマンド引数やパス構築に使う場合は必ずバリデーション
- `eval` は使わない（どうしても必要な場合は代替案を先に検討）
- 外部コマンドの実行前にパスの安全性を確認
- 機密情報（パスワード、トークン）はコマンドライン引数に渡さない（環境変数または設定ファイル経由）