Claude Code を使い込むほど、毎回ほぼ同じ指示を打ち込んでいることに気づきます。「差分をレビューして」「テストを書いて流して」「リリースノートを下書きして」——こうした定型の指示は、カスタムスラッシュコマンドにまとめておくと /review の一語で呼び出せます。

カスタムコマンドは Markdown ファイルを置くだけで作れる軽量な仕組みですが、設計を誤ると「コマンドが乱立して誰も覚えていない」状態に陥りがちです。AI 駆動開発のクリエイティブスタジオである FIXIT が実プロジェクトで運用しているコマンド設計の型と、チームで共有するときの勘所をまとめます。

カスタムコマンドとは — 定型プロンプトを資産化する仕組み

カスタムスラッシュコマンドは、頻繁に使うプロンプトを Markdown ファイルとして保存し、/コマンド名 で呼び出せるようにする機能です。ファイルの中身がそのままエージェントへの指示として展開されるため、実体は「名前を付けて保存したプロンプト」です。

価値は、よくできた指示を個人の頭の中ではなくリポジトリの中に置けることにあります。プロンプトは試行錯誤の塊で、手順や注意点を言語化した資産です。それをファイルにしておけば、チーム全員が同じ品質の指示を再現できます。新しく入ったメンバーも / を押せばコマンド一覧が出るので、「このプロジェクトでは何が自動化されているか」がそのままドキュメントとして機能します。

口頭やチャットで共有していた「Claude にこう頼むとうまくいくよ」というノウハウを、実行可能な形で固定化する。これがカスタムコマンドの本質です。

.claude/commands の置き場所と最小の書き方

コマンドの置き場所は 2 種類あります。リポジトリ直下の .claude/commands/ に置くとプロジェクト共有のコマンドになり、~/.claude/commands/ に置くと自分のどのプロジェクトからも使える個人コマンドになります。チームで揃えたい定型はプロジェクト側、自分専用の癖のあるものは個人側、と分けるのが基本です。

最小のコマンドは、ファイルを 1 つ置くだけで完成します。.claude/commands/review.md を作り、中に指示を書きます。

<!-- .claude/commands/review.md -->
 
現在のブランチと main の差分をレビューしてください。
 
観点:
 
- ロジックのバグや境界条件の漏れ
- 既存コードとの一貫性 (命名・パターン)
- テストの過不足
 
重大度を High / Medium / Low に分けて、ファイルと行を添えて報告してください。
修正は提案にとどめ、勝手に編集しないこと。

これで Claude Code 上で /review と打つと、ファイルの中身が指示として展開されます。ファイル名がそのままコマンド名になるので、pr-review.md なら /pr-review です。サブディレクトリに置くと名前空間が付き、.claude/commands/git/commit.md は /git:commit のように呼べます。役割でフォルダを切ると一覧が整理されます。

冒頭に frontmatter を付けると、コマンド一覧での説明文や実行モデルを指定できます。

---
description: ブランチの差分を観点付きでレビューする
---
 
現在のブランチと main の差分をレビューしてください。

description を書いておくと / を押したときの一覧に説明が出るので、チームで使うコマンドには必ず付けておくと親切です。

引数・$ARGUMENTS を使った再利用パターン

固定の指示だけでなく、呼び出すたびに変わる値を渡したいことがあります。そのために用意されているのが $ARGUMENTS です。コマンド本文に $ARGUMENTS と書いておくと、/コマンド名 渡したい文字列 の「渡したい文字列」の部分がそこに差し込まれます。

たとえば課題番号を受け取って調査するコマンドはこう書けます。

---
description: 課題番号を受け取り、関連コードを調査して着手方針をまとめる
---
 
課題 $ARGUMENTS について調査します。
 
1. 課題の内容を Backlog から取得して要約する
2. 関連しそうなコードを grep で特定する
3. 修正方針を箇条書きで提案する (この時点では編集しない)

/investigate FIXIT-123 と打てば、$ARGUMENTS に FIXIT-123 が入った状態で実行されます。

複数の引数を別々の位置で使いたいときは、$1 $2 のように位置指定もできます。最初の引数をファイルパス、2 番目を観点として扱う、といった使い分けが可能です。

本文の中で実際のシェルコマンドの出力を埋め込みたい場合は、! 接頭辞でコマンドを実行してその結果をプロンプトに含められます。たとえば差分を最初から渡しておくと、エージェントが自分で git diff を打つ手間が省けます。

---
description: 差分をあらかじめ読み込んでレビューする
---
 
以下の差分をレビューしてください。
 
!`git diff main...HEAD`

外部の値を受け取れるようになると、1 つのコマンドが多くの場面で再利用できます。引数を使うか固定にするかは、「呼ぶたびに変わる情報があるか」で判断すると迷いません。

実用例 1: PR レビュー・コミット・リリースの定型化

ここからは FIXIT で実際に運用している型を紹介します。まず効果が大きいのが、Git 周りの定型化です。

コミットは「差分を見て、規約に沿ったメッセージで、論理単位に分けて切る」という手順が毎回同じになるので、コマンド化の相性が抜群です。

---
description: 未コミットの差分を確認し、規約に沿ってコミットを作る
---
 
未コミットの変更を確認し、コミットを作成してください。
 
- まず `git status` と `git diff` で変更内容を把握する
- 関連する変更を論理単位にまとめ、必要なら複数コミットに分ける
- メッセージは Conventional Commits 形式 (feat: / fix: / docs: 等)
- コミット前に lint とテストが通ることを確認する

PR レビューやリリースノートの下書きも同じ発想で畳めます。リリース系は「直前のタグから現在までのコミットを集めて、ユーザー向けの言葉に翻訳する」という変換作業なので、観点を固定しておくと出力が安定します。

この層のコマンドは、品質ゲートを通す hooks と組み合わせると効果が二乗で効きます。コマンドで手順を、hooks で実行時の強制力を担保する、という役割分担です。hooks の具体的な設定は Claude Code の hooks で品質を底上げする 5 つの実用パターン にまとめています。

実用例 2: 校正・テスト・調査の定型化

コードを書く以外の定型作業も、コマンドにすると毎日の摩擦が減ります。

テストは「実装に対して、観点を漏らさずテストを書き、流して、失敗したら直す」という流れを言語化しておくと、人によってテストの粒度がぶれにくくなります。観点として境界値・異常系・既存テストとの重複回避を明記しておくのがコツです。

文章を扱うプロジェクトでは、校正コマンドが重宝します。表記ルールや禁止表現をコマンドに書いておけば、/proofread 一発でルールに沿った指摘が返ってきます。

---
description: 文章を社内の表記ルールで校正する
---
 
$ARGUMENTS のファイルを校正してください。
 
- 表記ゆれを検出する (ブランド名・専門用語は正式表記に統一)
- 冗長な言い回し、二重否定、誇張表現を指摘する
- 修正は提案として示し、最終判断は人に委ねる

調査系のコマンドも有効です。「この機能はどこで実装されているか」「この設定はどう効いているか」といった探索は、grep の手順や読む順番を固定しておくと、毎回ゼロから探すより速く正確になります。こうした探索の精度は、プロジェクトの前提を書いた CLAUDE.md の充実度に比例します。何を書いておくべきかは CLAUDE.md にこれを書くと AI 駆動開発の品質が上がる 8 つの項目 で詳しく扱っています。

チームで共有するときのリポジトリ運用と命名規則

コマンドの真価は、チームで共有したときに出ます。.claude/commands/ をリポジトリにコミットすれば、クローンした全員が同じコマンドを即座に使えます。レビュー観点やコミット規約のような「チームの約束ごと」を、口伝ではなく実行可能なファイルとして配れるわけです。

運用で効いてくるのが命名規則です。/ を押したときに一覧がアルファベット順に並ぶので、関連するコマンドが近くに来るよう接頭辞を揃えると探しやすくなります。pr-review pr-create のように動作対象を先に置くか、サブディレクトリで git/ docs/ のように名前空間を切るか、どちらかにプロジェクト内で統一します。

description は省略しないことを徹底します。説明のないコマンドは一覧で何をするものか分からず、結局使われません。1 行で「何を・どうする」が伝わる説明を必ず添えるのをレビュー基準にしておくとよいです。

コマンド自体も通常のコードと同じくレビュー対象に含めます。プロンプトは挙動を左右する立派なロジックなので、PR で差分を確認し、意図しない破壊的な指示が混ざっていないかを見ます。個人の試行錯誤は ~/.claude/commands/ で回し、安定して効くと確認できたものだけをプロジェクトに昇格させる、という流れが運用しやすいです。

やりすぎない設計 — コマンド乱立を防ぐ基準

カスタムコマンドは作るのが簡単なので、放っておくと際限なく増えます。一覧が 30 個も並ぶと、もはや覚えられず探す手間の方が大きくなり、結局使われなくなります。

乱立を防ぐには、作る前の基準を 1 つ持っておくのが効きます。FIXIT では「3 回以上、ほぼ同じ指示を打った」ものだけコマンド化する、という目安を使っています。一度きりの作業や、毎回中身が大きく変わる指示はコマンドに向きません。畳むことで再現性が上がる定型作業かどうかで線を引きます。

既存コマンドの統合も定期的に行います。似たコマンドが 2 つあるなら、引数で分岐できないかを検討して 1 つにまとめます。半年使われていないコマンドは思い切って消します。コマンド集はドキュメントと同じで、増やすより「使われる状態を保つ」方が大事です。

1 コマンドが抱える指示も、欲張りすぎないようにします。あれもこれもと盛り込むと、エージェントが手順を取りこぼしやすくなります。長く複雑なワークフローは、後述する subagent に切り出す方が安定します。

関連: hooks / subagent との使い分け

カスタムコマンドは便利ですが、万能ではありません。似た仕組みである hooks や subagent と役割を切り分けると、それぞれの強みが活きます。

カスタムコマンドは「人が明示的に呼び出す定型プロンプト」です。実行のきっかけは人間で、/review と打って初めて動きます。一方 hooks は「ツール実行の前後で自動的に走る処理」で、人が意識しなくても発火します。コミット前の textlint やフォーマットのように、忘れずに必ず実行したい強制力が欲しいものは hooks の領分です。MCP を含めた連携の全体像は Claude Code に MCP をつないで実務を加速する 5 つの実例と導入の勘所 も参考になります。

subagent は「独立した文脈を持つ専門エージェント」で、長く複雑な調査やレビューを本筋の会話から切り離して任せたいときに使います。1 つのコマンドに詰め込みすぎて破綻しそうなワークフローは、subagent に分離すると会話のコンテキストを汚さずに済みます。

整理すると、明示的に呼ぶ定型はコマンド、自動で確実に走らせたい処理は hooks、重い専門タスクの分離は subagent、という住み分けです。まずはコマンドから始め、強制力や分離が欲しくなった部分を hooks と subagent に振り分けていくと、無理なく自動化が育ちます。

FIXIT では、こうしたコマンド・hooks・subagent の設計を実プロジェクトの中で磨き込み、チームの開発フローに組み込んでいます。AI 駆動開発の進め方や自動化の設計について相談したい方は、お問い合わせ からお気軽にご連絡ください。