Claude Codeのカスタムコマンドとは、よく使う定型プロンプトを/コマンド名という短いスラッシュコマンドで呼び出せる仕組みです。毎回同じ長い指示を打ち直す手間を、たった1回のコマンド入力に置き換えられます。
作り方はとてもシンプルです。決められたフォルダにMarkdownファイルを1つ置くだけで、プログラミング知識は要りません。テキストファイルが作れる人なら、誰でも今日から作れます。
この記事では、カスタムコマンドの仕組みと配置先という基礎から、最初の1つを作る手順、そのまま使える実用例6選、$ARGUMENTSによる引数、YAML frontmatterや!・@プレフィックスといった一歩進んだ書き方、そして運用のコツまでを一通り解説します。まだClaude Code自体を導入していない場合は、先にClaude Codeとは何かとその始め方を確認しておくとスムーズです。
Claude Codeのカスタムコマンドとは｜仕組みと配置先の基本
まずはカスタムコマンドの正体と、ファイルをどこに置けば良いのかという基礎を固めます。ここを理解すれば、あとの手順は驚くほど簡単に感じられます。
カスタムコマンド＝定型プロンプトのMarkdownファイル
Claude Codeのカスタムコマンドの実体は、Claudeへの指示（プロンプト）を書いた1枚のMarkdownファイルです。特別な設定ファイルやプラグインではありません。
仕組みの中心はたった1つのルールです。.claude/commands/というフォルダにMarkdownファイルを置くと、そのファイル名がそのままコマンド名になるのです。たとえばreview.mdを置けば/reviewで呼び出せます。
つまり、いつもチャット欄に貼り付けている長い指示文をファイルに保存しておくだけで、それが再利用可能なコマンドに変わります。この手軽さが、カスタムコマンド最大の魅力です。
プロジェクト単位とユーザー単位の2つのスコープ
ファイルの置き場所には2種類あり、それぞれ呼び出せる範囲（スコープ）が異なります。この使い分けが、カスタムコマンドを実務で活かす鍵になります。
1つ目はプロジェクト単位です。プロジェクトのルートにある.claude/commands/に置いたコマンドは、そのプロジェクト内でのみ有効になります。Gitで管理すれば、リポジトリに参加するメンバー全員が同じコマンドを共有できます。
2つ目はユーザー単位です。ホームディレクトリの~/.claude/commands/に置いたコマンドは、そのマシン上のあらゆるプロジェクトから呼び出せます。個人的にどこでも使いたいお気に入りのプロンプトは、こちらに置くのが向いています。
両者は共存でき、プロジェクト固有の作業はプロジェクト単位、汎用的な作業はユーザー単位、と役割を分けて運用します。違いを表にまとめます。
| 比較項目 | プロジェクト単位 | ユーザー単位 |
|---|---|---|
| 配置先 | [プロジェクトルート]/.claude/commands/ | ~/.claude/commands/ |
| 有効な範囲 | そのプロジェクト内のみ | マシン上の全プロジェクト |
| 共有 | Git管理でチーム全員に共有できる | 基本は自分の端末のみ |
| 向いている用途 | プロジェクト固有のルールや規約に沿った作業 | どこでも使う汎用的な定型作業 |
呼び出し方はどちらも/コマンド名で共通です。名前が重複した場合などに区別したいときは、プロジェクト単位を/project:コマンド名、ユーザー単位を/user:コマンド名と明示的に指定できます。
命名規則｜ファイル名がコマンド名になる
前述のとおり、コマンド名はファイル名そのものです。test-gen.mdなら/test-genになるため、ファイル名を決めることがコマンド名を決めることと同義になります。
命名では、英小文字とハイフンでつなぐ形式が扱いやすくおすすめです。日本語のファイル名も動作しますが、ターミナルで入力しやすい半角英字にしておくと呼び出しが快適になります。
名前はreviewやcommit-msgのように、動作が一目で分かる動詞ベースにするのがコツです。また.claude/commands/git/のようにサブフォルダを作ると、/git:commit-msgという形で名前空間としてグループ化できます。
Claude Codeカスタムコマンドの作り方｜最初の1つを作る手順
ここからは実際に手を動かします。コードレビューを実行する/reviewコマンドを例に、最初の1つを作る手順を番号順に追います。
手順1〜4：ディレクトリ作成からコマンド実行まで
手順1：コマンド用のディレクトリを作成する。プロジェクトのルートで、次のコマンドを実行してフォルダを用意します。-pを付けているので、途中のフォルダがなくてもまとめて作られます。
mkdir -p .claude/commands手順2：Markdownファイルを新規作成する。コマンド名にしたい名前で、拡張子.mdのファイルを作ります。ここではreview.mdにします。
touch .claude/commands/review.mdもちろん、VS Codeなどのエディタで直接ファイルを新規作成しても構いません。要は.claude/commands/の中にreview.mdがあればよいのです。
手順3：ファイルにClaudeへの指示を書く。作成したreview.mdを開き、いつもレビューを頼むときの指示を書き込みます。中身は普通の文章で問題ありません。
あなたはシニアエンジニアです。直近の変更差分をレビューしてください。
観点は次のとおりです。
- バグや例外処理の漏れがないか
- 命名やコードの可読性に改善余地がないか
- パフォーマンス上の懸念がないか
- セキュリティ上のリスクがないか
指摘は重要度の高い順に並べ、修正案のコード例も添えてください。手順4：Claude Codeでコマンドを実行する。Claude Codeを起動し、チャット欄に/reviewと入力します。するとreview.mdに書いた指示がそのままプロンプトとして送られ、レビューが始まります。
これで最初のカスタムコマンドは完成です。以降は/reviewと打つだけで、毎回同じ観点のレビューを呼び出せます。
うまく呼び出せないときの確認ポイント
/を入力してもコマンドが候補に出てこないときは、次の3点を確認します。多くはこのいずれかで解決します。
- 配置先が
.claude/commands/になっているか（.claude/command/など単数形やスペルミスに注意） - 拡張子が
.mdになっているか（.txtでは認識されない） - ファイルを追加した後にClaude Codeを再読み込み・再起動したか
特に多いのは、プロジェクトのルート以外の場所でフォルダを作ってしまうケースです。作業中のプロジェクトの一番上の階層に.claudeフォルダがあるか、いま一度確認してください。
そのまま使える実用カスタムコマンド例6選
ここでは、コピーして.claude/commands/に置けばすぐ使える実用例を6つ紹介します。いずれも「用途・ファイルの中身・ポイント」の順にまとめました。自分の好みに合わせて指示文を書き換えれば、そのまま定番コマンドになります。
1. コードレビュー（/review）
変更したコードを客観的な観点で見てもらうコマンドです。前章で作ったものをベースに、指摘の粒度を指定して精度を上げます。
直近の変更をレビューしてください。
チェック観点:
- ロジックの誤りやエッジケースの考慮漏れ
- 命名・可読性・重複コードの有無
- エラーハンドリングの適切さ
- テストが必要な箇所
重要度（高・中・低）を付け、それぞれに修正案を添えてください。ポイントは、チェック観点を箇条書きで固定することです。毎回同じ基準でレビューされるため、レビューの質が安定します。
2. テストコード生成（/test-gen）
実装に対するテストコードの下書きを作らせるコマンドです。テストの書き始めの負担を大きく減らせます。
対象のコードに対するユニットテストを生成してください。
要件:
- 正常系だけでなく、境界値と異常系も網羅する
- テストケースごとに、何を検証しているかコメントを付ける
- プロジェクトで使われているテストフレームワークの記法に合わせる
まずテスト観点を一覧で示し、その後にテストコードを出力してください。ポイントは、いきなりコードを書かせず「テスト観点の一覧」を先に出させることです。観点を確認してから実装させると、抜け漏れに気づきやすくなります。
3. リファクタリング提案（/refactor）
動いてはいるが読みにくいコードの改善案を出させるコマンドです。いきなり書き換えさせず、提案から始めるのが安全です。
対象コードのリファクタリング案を提案してください。
方針:
- 外部から見た振る舞いは変えない
- 命名の改善、関数の分割、重複の除去を優先する
- 変更の理由を一つずつ説明する
まず改善ポイントの一覧を示し、承認を得てから修正を適用してください。ポイントは「承認を得てから修正を適用」と明記することです。意図しない大規模な書き換えを防ぎ、変更を自分でコントロールできます。
4. コミットメッセージ生成（/commit-msg）
ステージ済みの変更から、コミットメッセージを提案させるコマンドです。ここで少し先取りして、!を使ってシェルコマンドの結果を読み込ませています。!の詳しい仕組みは後半で解説します。
次のステージ済みの差分を読み、コミットメッセージを提案してください。
!git diff --cached
出力ルール:
- Conventional Commits形式（feat, fix, docs, refactor など）
- 1行目は50文字以内の要約
- 必要なら本文で変更理由を簡潔に補足するポイントは、行頭の!git diff --cachedによって、ステージした差分の実物がプロンプトに自動で埋め込まれる点です。差分を手でコピーする必要がなく、いつでも実際の変更に基づいたメッセージが得られます。
5. ドキュメント・READMEの下書き生成（/doc）
コードやプロジェクト構成から、READMEやドキュメントの下書きを作らせるコマンドです。ゼロから書く負担を減らせます。
このプロジェクトのREADMEの下書きを作成してください。
含める項目:
- プロジェクトの概要（何をするものか）
- セットアップ手順
- 基本的な使い方の例
- ディレクトリ構成の説明
読み手は、このプロジェクトに初めて触れる開発者を想定してください。ポイントは、読み手を「初めて触れる開発者」と明示することです。前提知識を省略しすぎない、親切な説明が生成されやすくなります。
6. 命名の相談・変数名提案（/naming）
関数名や変数名に迷ったときに、候補を複数出させる相談用コマンドです。小さな悩みほど、こうした軽いコマンドが役立ちます。
これから伝える役割に対して、適切な名前の候補を提案してください。
条件:
- 候補を3〜5個挙げる
- それぞれのニュアンスの違いを一言で説明する
- 英語として自然で、一般的な命名慣習に沿ったものにする
対象の役割: ポイントは、最後に役割を書き足す余白を残しておくことです。/namingを実行した後に「ユーザーのログイン状態を保持する変数」などと続ければ、その場で候補が返ってきます。
この「役割を後から渡す」使い方は、次章の引数を使えばさらにスマートに書けます。
引数で動的にする｜$ARGUMENTSの使い方
ここまでのコマンドは、毎回まったく同じ指示を送るものでした。$ARGUMENTSを使うと、実行するたびに値を渡して動作を変えられる、より柔軟なコマンドになります。
$ARGUMENTSの基本
仕組みは単純です。コマンド名の後ろに書いた文字列が、Markdownファイル内の$ARGUMENTSという部分に自動で代入されます。
たとえば/file-review src/App.tsxと実行すると、$ARGUMENTSがsrc/App.tsxに置き換わります。引数を使う前と後で、ファイルの書き方がどう変わるかを見てみます。
Before（引数なし）：対象を毎回文章で書き足す必要があります。
指定されたファイルをレビューしてください。After（引数あり）：$ARGUMENTSを埋め込むと、対象をコマンドと同じ行で渡せます。
次のファイルをレビューしてください: $ARGUMENTS
観点はバグ・可読性・エラーハンドリングの3点です。
重要度順に指摘し、修正案を添えてください。このファイルをfile-review.mdとして保存すれば、/file-review src/App.tsxのように対象を切り替えながら何度でも使い回せます。
引数付きコマンドの実用例
引数は、名前や対象を都度指定したい場面で特に効果を発揮します。例として、コンポーネントの雛形を生成する/create-pageコマンドを作ります。
「$ARGUMENTS」という名前のReactコンポーネントの雛形を作成してください。
要件:
- 関数コンポーネントとして実装する
- TypeScriptで型を定義する
- ファイル名は $ARGUMENTS.tsx とする
- 最低限のpropsの型定義とexportを含めるこれをcreate-page.mdとして保存し、/create-page ContactFormと実行すれば、ContactFormという名前のコンポーネント雛形が生成されます。$ARGUMENTSは同じファイル内で何度でも参照できるため、ファイル名とコンポーネント名の両方に一度で反映されます。
高度な書き方｜YAML frontmatterと!・@プレフィックス
ここからが、カスタムコマンドを一段上のレベルで使うための書き方です。コマンドに設定を持たせるYAML frontmatterと、外部の情報を自動で取り込む!・@の2つのプレフィックスを解説します。
YAML frontmatterでコマンドを定義する
YAML frontmatterとは、Markdownファイルの先頭に---で囲んで書くメタデータのことです。ここにコマンドの説明や設定を書くと、コマンドの挙動をより細かく制御できます。
よく使う項目は2つです。descriptionはコマンドの説明で、/を入力したときのコマンド一覧に表示され、どのコマンドが何をするのか見分けやすくなります。allowed-toolsはそのコマンドが使えるツールを限定する設定で、安全性を高めます。
frontmatterを付けた完全なreview.mdの例が次です。
---
description: 直近の変更をレビューする
allowed-tools: Read, Grep, Glob
---
直近の変更をレビューしてください。
観点はバグ・可読性・エラーハンドリングの3点です。
重要度順に指摘し、修正案を添えてください。この例ではallowed-toolsで読み取り系のツール（Read・Grep・Glob）のみを許可しています。レビューはコードを読む作業なので、ファイルの書き換えツールを渡さないことで、意図しない変更を防げます。
frontmatterは必須ではなく、書かなければ制限のない標準的なコマンドとして動きます。まずはdescriptionだけでも付けておくと、コマンドが増えたときに管理しやすくなります。
!接頭辞｜Bashコマンドの実行結果を埋め込む
!接頭辞は、行頭に!を付けてシェルコマンドを書くと、その実行結果をプロンプトの一部として自動で埋め込む仕組みです。手でコマンドを実行して結果を貼り付ける手間がなくなります。
先ほどのコミットメッセージ生成を、frontmatterと組み合わせた完成版にします。
---
description: ステージ済みの差分からコミットメッセージを生成する
allowed-tools: Bash(git diff:*)
---
次のステージ済みの差分を読み、コミットメッセージを提案してください。
!git diff --cached
出力ルール:
- Conventional Commits形式（feat, fix, docs, refactor など）
- 1行目は50文字以内の要約
- 必要なら本文で変更理由を簡潔に補足するここで重要なのが、allowed-toolsとの関係です。!はシェルコマンドを実行するため、Bashツールの実行許可が必要になります。上の例ではBash(git diff:*)と書き、git diff系のコマンドだけを許可しています。
このように許可範囲を絞っておくと、そのコマンドから予期しないシェル操作が走ることを防げます。!を使うときはallowed-toolsとセットで考える、と覚えておくと安全です。
@接頭辞｜ファイル内容を読み込ませる
@接頭辞は、行頭に@を付けてファイルパスを書くと、そのファイルの内容をプロンプトに直接読み込ませる仕組みです。「このファイルを見て」と口頭で伝える代わりに、中身をあらかじめ渡せます。
たとえば依存関係を踏まえてレビューさせたいとき、@package.jsonを書いておくと、使っているライブラリを前提にした指摘が得られます。
---
description: 依存関係を踏まえてコードをレビューする
allowed-tools: Read, Grep, Glob
---
このプロジェクトの依存関係は次のとおりです。
@package.json
上記のライブラリ構成を前提に、直近の変更をレビューしてください。
既存の依存で代替できる自前実装があれば、あわせて指摘してください。さらに、!と@は組み合わせられます。次は変更されたファイル一覧をシェルで取得しつつ、設定ファイルの中身も読み込ませる例です。
---
description: 変更ファイルと設定を踏まえてレビューする
allowed-tools: Bash(git status:*), Read
---
現在の変更状況は次のとおりです。
!git status --short
プロジェクトの設定は次のファイルを参照してください。
@tsconfig.json
以上を踏まえ、変更内容が設定方針に沿っているかレビューしてください。このように!で「その時点の状況」を、@で「固定の参照情報」を渡し分けると、コマンドの精度が大きく上がります。動的な情報と静的な情報を1つのコマンドにまとめられるのが、この2つのプレフィックスの強みです。
カスタムコマンドの運用・管理のコツ
最後に、カスタムコマンドを長く使い続けるための運用のコツを3つ紹介します。作ること自体より、使い続けられる形に整えることが効率化につながります。
小さく始めて頻度の高い作業から作る
最初から凝ったコマンドを大量に作る必要はありません。むしろ、毎日のように繰り返している作業を1つコマンド化するところから始めるのが効果的です。
頻度の高い作業ほど、コマンド化による時短効果が積み上がります。使ってみて指示が物足りなければ、そのつどMarkdownを書き足して育てていけばよいのです。
チームで共有するならGit管理に含める
チーム開発では、プロジェクト単位の.claude/commands/をそのままGitでコミットします。これでリポジトリを取得したメンバー全員が、同じコマンドを使えるようになります。
レビュー観点やコミット規約をコマンドに落とし込んでおけば、チーム全体で品質の基準をそろえられます。属人的になりがちなノウハウを、リポジトリに残る資産として共有できるわけです。Claude Codeをチーム運用する際の設定はClaude Codeの設定おすすめ9選もあわせて参考にしてください。
Claude自身にコマンドを作らせる
実は、コマンドファイルを手で書く必要すらありません。Claude Codeのチャット欄で「〇〇するカスタムコマンドを.claude/commands/に作って」と頼めば、ファイルの作成と配置まで自動でやってくれます。
たとえば「ステージ済みの差分からコミットメッセージを作るコマンドをcommit-msg.mdとして作って」と指示するだけで、frontmatterや!を含んだファイルが用意されます。作ってもらった中身を読めば、書き方の勉強にもなります。
なお、Claude Codeにはこうしたコマンドをさらに発展させた「スキル（Skills）」という、より自律的な仕組みも用意されています。ただし本記事の主題はカスタムコマンドの作り方なので、まずはコマンドに慣れることをおすすめします。
まとめ｜Claude Codeカスタムコマンドで開発を効率化する
Claude Codeのカスタムコマンドの作り方を、仕組みと配置先から実用例、引数、frontmatterや!・@、運用のコツまで解説しました。要点を振り返ります。
.claude/commands/にMarkdownを置くと、ファイル名がそのままコマンドになる- プロジェクト単位とユーザー単位を使い分ける
$ARGUMENTSで実行時に値を渡し、動的なコマンドにできる- frontmatterの
description・allowed-toolsで説明と安全性を制御する !でシェルの結果を、@でファイルの中身を自動で読み込ませる
いちばん大切なのは、まず1つ作ってみることです。この記事の/reviewをコピーして.claude/commands/に置くだけで、あなたの最初のカスタムコマンドが動きます。
カスタムコマンドに慣れたら、次はClaude Code全体の活用の幅を広げてみてください。Claude Codeでできること10選で機能の全体像をつかめます。実際の活用イメージは非エンジニアがClaude CodeでWordPress自動投稿を作った話も参考になるはずです。
