スラッシュコマンドは「プロンプトを使い回す仕組み」だと思われがちだが、`allowed-tools`と`argument-hint`を真面目に使うと、AIに渡す権限を最小化しつつドキュメントを兼ねた実行可能仕様書になる。今回は`commands/`配下に並ぶ`.md`ファイルの設計原則を整理する。
まず引数。位置引数は`$1`から`$9`、全部まとめたいときは`$ARGUMENTS`。落とし穴は未指定時の扱いで、`$1`は空文字列として展開されるので、プロンプト側で`{{#if $1}}`相当の分岐は書けない。代わりにfrontmatterの`argument-hint: <pr-number> [base-branch]`で使用者に求める形を明示し、必須引数が抜けていればAI側にバリデーションさせるほうが素直だ。`argument-hint`はタブ補完にも出るので、チームメンバーが`/review <TAB>`で思い出せる効果もある。
frontmatterの`allowed-tools`は最小権限の核。たとえばPRレビューコマンドなら`Bash(git diff:*), Bash(gh pr view:*), Read`だけに絞る。`Bash(git:*)`のようにワイルドカードを広げるとpushまで許してしまうので、サブコマンド単位で書くのが原則だ。`WebFetch(domain:github.com)`のようにドメインを指定するとネットワーク面も締まる。
プログレッシブディスクロージャの考え方は、コマンド本文を「要約→手順→失敗時のリカバリ」の順で並べること。AIは上から読むので、最初の2〜3行で意図が伝わらないと迷走する。`## 目的`→`## 手順`→`## 例外処理`の三段構成に統一すると、50個あるコマンドでも読解コストが下がる。
model指定も地味に効く。軽いフォーマッタ系は`model: claude-haiku-4-6`、設計相談は`model: claude-opus-4-7`と書き分けることで、コストを4〜6倍圧縮できた。frontmatterの`description`は`/help`一覧に出るので、30文字以内で動詞始まりにするのがチーム規約。
落とし穴をひとつ共有すると、`$ARGUMENTS`にパイプやバッククォートを含む文字列が渡ると、後段の`Bash()`ツールが意図しないコマンドを組み立てる恐れがある。コマンド本文で`$ARGUMENTS`を直接シェルに流さず、一度AIに引数の妥当性を検査させる一段を挟むほうが安全だ。