前提・最小セットアップ
カスタムスラッシュコマンドは、公式が定義するディレクトリ構造に .md ファイルを置くだけで即座に認識される。認識範囲は2層ある。
- プロジェクト固有:
.claude/commands/（Git管理・チーム共有用） - ユーザー全体:
~/.claude/commands/（個人用・環境依存のエイリアス用）
初期状態ではこのディレクトリが存在しないため、まず作っておく。
mkdir -p .claude/commands
ファイル名はコマンド名そのものになる。拡張子は .md 固定で、空白やハイフンは避ける（補完の挙動が不安定になる）。
実際の手順（コマンド・設定ファイルの中身つき）
定型作業の核は「入力引数を受け取り、出力フォーマットを固定するプロンプト」だ。 $ARGUMENTS という予約変数でターミナルから渡された文字列を受け取れる。
例：git diff の結果を特定フォーマットでレビューさせる /code-review.md
# コードレビュー指示
以下の差分をレビューしてください。
$ARGUMENTS
出力は以下の4項目を必ず含めてください：
1. 重大なバグ・セキュリティリスク（該当なしの場合は「なし」と明記）
2. 改善提案（優先度：中。既存の設計思想を尊重すること）
3. 現状で問題ない箇所
4. 修正すべき具体的な行番号と差分コード例
注意点：
- 既存の公開APIのシグネチャを勝手に変更しない
- 未使用の依存関係や型定義を追加しない
- 提案は `npm run lint -- --fix` で解決できる範囲に留める
設置後、ターミナルから以下のいずれかで呼び出す。
/code-review "src/lib/auth.ts"
# またはパイプで直接 diff を渡す
git diff src/lib/auth.ts | /code-review
認識されているか確認するには、ターミナルで /code- まで入力し補完候補が出るかを見るか、/help で一覧表示すれば確認できる。
効果・つまずき・コツ
効果（体感の before / after）
- before:
git diffを取得し、レビュー項目を手打ちし、出力結果をコピペして整形するまでで平均 40〜60秒。コンテキストの 15〜20% を定型指示で消費。 - after: 補完候補から
/code-reviewを選んで引数を入力するだけ。出力は常に同じ構造で返ってくるため、人間が読むべき「提案とリスク」に集中できる。レビューの初期コストが実質 0 秒になり、コンテキスト消費も 5% 以下に収束した。
つまずき・ハマりどころ
-
$ARGUMENTSの位置: プロンプトの中央や冒頭に置くと、モデルが引数を「指示」と誤認し、本来のレビュー対象を見失う。文末に配置し、直前に「以下の差分を」と明示すると安定する。 -
シェル実行との勘違い: カスタムコマンドは「モデルに送信されるプロンプト」であり、直接シェルで実行されるわけではない。ファイル内で
npm run testと書いても、モデルが適切なツール呼び出しを行う必要がある。実際に確認ダイアログを出したくない場合は、.claude/settings.jsonに権限を付与する。{ "permissions": { "allow": ["Bash(npm run test:*)"] } } - 長文プロンプトの逆効果: 200行以上の定型ファイルを作ると、重要なルールが埋もれ、モデルの注意力が散漫になる。公式ドキュメントでも指摘される通り、「やること・やらないこと」を箇条書きに絞り、変数や条件分岐は極力外に出す。
向かないケース
- 毎回構造が全く異なる探索的タスク（設計検討、新規機能のブレイクダウン）。
- 引数に特殊文字や改行が多数含まれる場合（シェルエスケープの問題が生じ、
$ARGUMENTSが破綻する）。その場合はCLAUDE.mdや一時ファイルを経由させる。
まとめ ＋ 次の一歩
カスタムスラッシュコマンドの真価は「定型プロンプトをファイルとしてバージョン管理できる点」にある。チームの .claude/commands/ を作れば、新人が迷うことなく同じ品質で AI を扱えるようになり、レビューのバラつきがなくなる。
次の一歩として、今週あなたが「毎回同じようにコピペしている作業」を1つ選べ。それを .md に書き、 $ARGUMENTS で引数を受け取る形に落とし込めば、明日のセッションから既に時短が効いているはずだ。
執筆時点の仕様に基づいている。コマンド名、変数名、認識ルールは将来のバージョンで変更される可能性があるため、最新情報は公式ドキュメントを参照のこと。
参考: https://docs.claude.com/en/docs/claude-code
筆者について / About the author
pendorix — 生成AI・LLM エンジニア（日本在住 / JLPT N1）。SESで約9年、Python・Java を中心に開発。現在はローカルLLM・RAG・生成AI実装に注力し、実測値と動くコードで検証した知見を発信しています。LLM / 生成AI 実装・DX支援のお仕事のご相談を歓迎します。
pendorix — GenAI / LLM engineer based in Japan (JLPT N1). ~9 years building software (Python / Java); now focused on local LLMs, RAG, and shipping practical GenAI systems — sharing hands-on, benchmarked findings. Open to LLM / GenAI implementation & DX opportunities.
GitHub: https://github.com/pendorix