Claude Code カスタムスラッシュコマンドの作り方｜毎回同じ指示を打つのをやめる

📝 はじめに

Claude Code を使っていて、こんなことはありませんか？

• 「このコードをレビューして。観点は〇〇と△△と□□で…」→ 毎回同じ観点を書いている
• 「このファイルのテストを書いて。Jest で、カバレッジは…」→ 毎回同じフォーマットで指示している
• 「コミットメッセージを日本語で、Conventional Commits 形式で…」→ 毎回同じルールを伝えている

Claude Code は賢いですが、あなたのプロジェクト固有のルールは毎回教えないと分かりません 。CLAUDE.md にある程度書いておくことはできますが、「今この瞬間にやってほしい特定のタスク」の定型文は CLAUDE.md の守備範囲外です。

ここで登場するのが カスタムスラッシュコマンド です。

よく使うプロンプトを .md ファイルに保存しておくだけで、/review や /test-gen のように スラッシュ一発で呼び出せるコマンド に変換できます。一度作れば、何百回でも同じクオリティの指示を一瞬で出せます。

この機能、公式ドキュメントにはさらっとしか書かれていませんが、使いこなすと生産性が劇的に変わります 。この記事では作り方から実践レシピ、チーム共有の方法まで一気に解説します。

📝 カスタムスラッシュコマンドとは？

🔹 一言でいうと

「プロンプトのテンプレートを保存して、スラッシュコマンドで呼び出せる仕組み」 です。

通常の Claude Code の操作:

あなた: このファイルをレビューして。セキュリティ、パフォーマンス、
        可読性の観点でチェックして。問題があれば具体的な修正案を
        コードブロックで示して。重要度をHigh/Medium/Lowで分類して。

カスタムコマンドを使った場合:

あなた: /review

これだけ 。裏では先ほどの長いプロンプトが自動的に展開されて Claude に渡されます。

🔹 たとえ話で理解する

カスタムコマンドは 料理のレシピカード のようなものです。

毎回「小麦粉 200g、卵 2 個、バター 50g を混ぜて…」と口頭で説明する代わりに、レシピカードを渡して「これ作って」と言うだけ。レシピカードが正確なら、何度作っても同じクオリティの料理が出てきます。

Claude Code のカスタムコマンドも同じ。正確なプロンプトを一度書いておけば、何度呼び出しても同じクオリティの出力が得られます 。

🔹 CLAUDE.md との違い

項目	CLAUDE.md	カスタムコマンド
目的	常に適用されるルール・方針	特定タスクの実行指示
発動タイミング	常に（自動で読み込まれる）	コマンド実行時のみ
例	「コミットメッセージは日本語」	「/review でコードレビューを実行」
粒度	プロジェクト全体のガイドライン	1 回の作業の具体的な手順

CLAUDE.md は「憲法」、カスタムコマンドは「業務マニュアル」 と考えると分かりやすいです。憲法は常に適用されるけど、具体的な業務手順は必要な時だけ参照する。この使い分けが大事です。

📝 作り方

🔹 ファイルを置く場所

カスタムコマンドは Markdown ファイル（.md）を所定のディレクトリに置くだけ で作れます。

ディレクトリ	スコープ	呼び出し方	Git 管理
.claude/commands/	プロジェクト固有	/project:コマンド名	する（チーム共有）
~/.claude/commands/	ユーザー全体	/user:コマンド名	しない（個人用）

プロジェクトコマンド（.claude/commands/）はリポジトリに含まれるので、チーム全員が同じコマンドを使えます。ユーザーコマンド（~/.claude/commands/）はどのプロジェクトでも使える個人用のコマンドです。

🔹 最小構成

たった 2 ステップで作れます。

ステップ 1: ディレクトリを作る

mkdir -p .claude/commands

ステップ 2: Markdown ファイルを置く

.claude/commands/review.md:

以下の観点でこのプロジェクトのコードをレビューしてください。

## レビュー観点
- セキュリティ上の問題はないか
- パフォーマンスのボトルネックはないか
- 可読性は十分か（命名、構造、コメント）
- エッジケースの処理は漏れていないか

## 出力フォーマット
問題ごとに以下の形式で報告してください。

- **ファイル**: 該当ファイルのパス
- **行**: 該当行番号
- **重要度**: High / Medium / Low
- **内容**: 問題の説明
- **修正案**: 具体的なコード修正（コードブロックで）

これだけ 。次に Claude Code を起動して /project:review と打てば、この内容が自動的にプロンプトとして送信されます。

🔹 引数を受け取る（$ARGUMENTS）

コマンドに 引数を渡したい 場合、Markdown ファイルの中で $ARGUMENTS という変数を使います。

.claude/commands/review.md:

$ARGUMENTS のファイルをレビューしてください。

## レビュー観点
- セキュリティ上の問題はないか
- パフォーマンスのボトルネックはないか
...

呼び出し方:

あなた: /project:review src/components/Header.tsx

すると $ARGUMENTS が src/components/Header.tsx に置き換わり、Claude は指定されたファイルをレビューしてくれます。

$ARGUMENTS が空の場合 は、Claude が自分で対象を判断してくれます（直前のコンテキストや、プロジェクト全体を見て判断）。「引数を渡さなかったらプロジェクト全体を見てね」というような柔軟な動作が可能です。

📝 実践レシピ集

ここからは、すぐにコピペして使えるコマンドを紹介します。それぞれ 「なぜ便利か」「コマンドの内容」「使い方の例」 をセットで解説します。

---

🔹 レシピ 1: コードレビュー（/project:review）

なぜ便利か？

コードレビューは毎回同じ観点でチェックしたいのに、毎回「セキュリティと可読性と…」と書くのは面倒です。さらに、人間のレビューと違って Claude は 疲れない ので、100 ファイルでも同じクオリティで見てくれます。

.claude/commands/review.md:

$ARGUMENTS を以下の観点でレビューしてください。
引数が空の場合は、直近の変更（git diff）を対象にしてください。

## レビュー観点

### セキュリティ
- インジェクション攻撃（SQL, XSS, コマンド）の可能性
- 認証・認可の漏れ
- 機密情報のハードコード
- 入力値のバリデーション不足

### パフォーマンス
- N+1 クエリ
- 不要な再レンダリング（React の場合）
- 大きなデータの非効率な処理
- メモリリークの可能性

### 可読性・保守性
- 命名の適切さ（変数名、関数名）
- 関数の責務が単一か
- マジックナンバーの有無
- 複雑すぎる条件分岐

### エッジケース
- null / undefined の処理
- 空配列・空文字列の処理
- 境界値（0, 負数, 最大値）
- 並行処理での競合

## 出力フォーマット
問題ごとに以下の形式で報告してください。

**[High/Medium/Low] ファイル名:行番号**
問題の説明。
修正案をコードブロックで提示。

最後にレビューサマリー（問題の総数、重要度別の内訳）を付けてください。

使い方:

/project:review                          # git diff 全体をレビュー
/project:review src/utils/auth.ts        # 特定ファイルをレビュー
/project:review src/components/          # ディレクトリ単位でレビュー

---

🔹 レシピ 2: テスト生成（/project:test-gen）

なぜ便利か？

テストを書くのは面倒だけど、テストの「書き方」は毎回ほぼ同じ 。使うフレームワーク、モックの作り方、アサーションのスタイル——これらをコマンド化しておけば、テスト生成の品質が安定します。

.claude/commands/test-gen.md:

$ARGUMENTS のテストコードを生成してください。
引数が空の場合は、直近の変更に関連するテストを生成してください。

## テストフレームワーク
- Vitest を使用
- describe / it のネスト構造

## テストの方針
- 正常系を最初に書く
- 異常系（エラーケース）を次に書く
- 境界値テストも含める
- 外部依存はモック化する（vi.mock）

## 命名規則
- describe: 対象の関数名やコンポーネント名
- it: 日本語で「〜のとき、〜になること」

## 例
```typescript
describe('calculateTotal', () => {
  it('正常な値が渡されたとき、合計を返すこと', () => {
    expect(calculateTotal([100, 200, 300])).toBe(600);
  });

  it('空配列のとき、0 を返すこと', () => {
    expect(calculateTotal([])).toBe(0);
  });
});
```

## 注意事項
- 既存のテストファイルがあればそのスタイルに合わせる
- テストファイルは対象ファイルと同じディレクトリに `.test.ts` で作成
- カバレッジ 80% 以上を目指す

使い方:

/project:test-gen src/utils/formatDate.ts
/project:test-gen src/components/SearchBar.tsx

---

🔹 レシピ 3: コミットメッセージ生成（/project:commit）

なぜ便利か？

コミットメッセージのルールは決まっているのに、毎回「Conventional Commits で、日本語で…」と指示するのは無駄です。さらに、このコマンドは ステージングされた変更を自動で分析 して適切なメッセージを提案してくれます。

.claude/commands/commit.md:

現在のステージング済みの変更（git diff --staged）を分析して、コミットメッセージを作成してください。

## コミットメッセージのルール

### フォーマット
```
type: subject

body
```

例: `feat: ログインフォームにバリデーションを追加`

### type の種類
- feat: 新機能の追加
- fix: バグ修正
- refactor: リファクタリング（機能変更なし）
- style: フォーマット変更（コードの動作に影響なし）
- docs: ドキュメントの変更
- test: テストの追加・修正
- chore: ビルドプロセスや補助ツールの変更

### ルール
- subject は日本語で、50 文字以内
- body は「なぜこの変更をしたか」を日本語で簡潔に
- body が不要なほど自明な変更なら省略可
- 複数の変更が含まれる場合は箇条書き

## 手順
1. `git diff --staged` を実行して変更内容を確認
2. 変更の意図を分析してコミットメッセージを生成
3. メッセージを表示して確認を求める
4. 承認されたら `git commit -m "メッセージ"` を実行

使い方:

git add src/components/Header.tsx
/project:commit

---

🔹 レシピ 4: リファクタリング提案（/project:refactor）

なぜ便利か？

「リファクタして」だけだと Claude は何を優先すべきか分かりません。プロジェクトのコーディング規約や優先順位 をコマンドに込めておけば、一貫したリファクタリングが得られます。

.claude/commands/refactor.md:

$ARGUMENTS をリファクタリングしてください。
引数が空の場合は、直近の変更に含まれるファイルを対象にしてください。

## リファクタリングの優先順位（上から順に重要）

1. **セキュリティリスクの排除**
   - ハードコードされた秘密情報 → 環境変数化
   - インジェクション可能な箇所 → サニタイズ

2. **可読性の向上**
   - 関数が 50 行を超えている → 分割
   - ネストが 3 段以上 → 早期リターンに変換
   - マジックナンバー → 名前付き定数に変換

3. **重複の排除**
   - 3 箇所以上で同じパターン → ユーティリティ関数に抽出
   - ただし、2 箇所の重複は放置してよい（早すぎる抽象化を避ける）

4. **型の安全性**
   - any 型 → 具体的な型に置き換え
   - as でのキャスト → 型ガードに変換

## やらないこと
- 動作に影響する変更（機能追加、仕様変更）
- テストが無いコードの大規模変更
- ライブラリの入れ替え

## 出力
- 変更前後の diff を提示
- なぜその変更をしたか 1 行で説明
- 変更後もテストが通ることを確認（テストがある場合）

---

🔹 レシピ 5: 記事の校正（/project:proofread）

なぜ便利か？

ブログ記事を書いた後の校正ルールも毎回同じ。誤字脱字チェック、表記ゆれ、読みやすさの観点を決めておけば、自分の記事を一貫した品質に保てます 。プログラマー以外にも使えるレシピです。

.claude/commands/proofread.md:

$ARGUMENTS の記事を校正してください。
引数が空の場合は、直近の変更に含まれる .mdx ファイルを対象にしてください。

## チェック項目

### 誤字脱字
- 漢字の変換ミス
- 送り仮名の間違い
- 英単語のスペルミス

### 表記ゆれ
- 同じ単語で漢字/ひらがなが混在していないか
  - 例: 「分かる」と「わかる」→ どちらかに統一
  - 例: 「出来る」と「できる」→ ひらがな推奨
- 英語表記の統一
  - 例: 「JavaScript」と「Javascript」→ 正式名称に統一

### 読みやすさ
- 一文が長すぎないか（60 文字を超えたら分割を検討）
- 同じ語尾が 3 回以上連続していないか（「〜です。〜です。〜です。」）
- 専門用語に説明が必要か（初出の用語は補足があるか）

### 構成
- 見出し（h2, h3）の粒度は適切か
- 結論が最初に来ているか（結論→詳細の順）
- 各セクションに導入文があるか

### SEO
- title が 30〜60 文字か
- description が 80〜160 文字か
- h2 にキーワードが含まれているか

## 出力フォーマット
修正箇所ごとに以下の形式で報告してください。

- **行**: 該当行番号
- **種類**: 誤字 / 表記ゆれ / 読みやすさ / 構成 / SEO
- **修正前**: 原文
- **修正後**: 修正案
- **理由**: なぜ修正すべきか（1 行）

最後に総評（良い点 3 つ、改善点 3 つ）を付けてください。

使い方:

/project:proofread src/content/pages/260413-claude-code-hooks/index.mdx

記事を書き終わった直後に走らせるだけで、セルフレビューの品質が格段に上がります 。

---

🔹 レシピ 6: 翻訳（/user:translate）

なぜ便利か？

これはプロジェクト固有ではないので ユーザーコマンド（~/.claude/commands/）に置きます。どのプロジェクトでも使える汎用コマンドです。

~/.claude/commands/translate.md:

$ARGUMENTS を以下のルールで翻訳してください。

## 翻訳ルール
- 日本語 → 英語、英語 → 日本語を自動判定
- 技術用語は無理に訳さない（例: React, API, Docker はそのまま）
- 自然な口語体で訳す（直訳ではなく意訳）
- コードブロック内は翻訳しない
- Markdown の構造（見出し、リスト、表）は維持する

## 出力
翻訳結果のみを出力してください。
説明や注釈は不要です。

使い方:

/user:translate README.md
/user:translate "This function calculates the total price including tax."

---

🔹 レシピ 7: 実装計画の作成（/project:plan）

なぜ便利か？

いきなりコードを書かせると、Claude は自分の判断で進めてしまいます。まず計画を立てさせてから実装 に入ることで、手戻りを大幅に減らせます。

.claude/commands/plan.md:

$ARGUMENTS の実装計画を作成してください。
コードは書かないでください。計画のみを出力してください。

## 計画に含めること

### 1. 現状分析
- 関連する既存コードの洗い出し
- 変更が影響するファイルの一覧

### 2. 方針の選択
- 考えられるアプローチを 2〜3 個列挙
- それぞれのメリット / デメリット
- おすすめのアプローチとその理由

### 3. 実装ステップ
- 具体的な作業を番号付きリストで
- 各ステップで変更するファイルと内容の概要
- 依存関係があるステップは明記

### 4. リスクと注意点
- 破壊的変更の有無
- テストが必要な箇所
- ロールバック方法

## 注意
- この段階では **絶対にコードを書かない**
- 計画を確認してもらってから実装に入る

使い方:

/project:plan ログイン機能にGoogleアカウント認証を追加したい
/project:plan 記事ページのパフォーマンスを改善したい

「まず計画、次に実装」の流れを コマンド一発で強制 できるのが強みです。

---

🔹 レシピ 8: 依存関係の整理（/project:deps）

なぜ便利か？

package.json の依存関係は放置するとカオスになります。使っていないパッケージ、古いバージョン、セキュリティ問題——これらを定期的にチェックする習慣をコマンド化しておくと楽です。

.claude/commands/deps.md:

このプロジェクトの依存関係を整理してください。

## チェック項目

### 1. 未使用の依存関係
- package.json に記載されているがコード内で import されていないパッケージを特定
- devDependencies も含めてチェック

### 2. バージョン
- `npm outdated` を実行してアップデート可能なパッケージを一覧表示
- メジャーバージョンアップは破壊的変更のリスクを注記

### 3. 重複
- 同じ目的のパッケージが複数入っていないか
  - 例: moment.js と dayjs が共存、lodash と ramda が共存

### 4. セキュリティ
- `npm audit` を実行して脆弱性をチェック

## 出力フォーマット
| パッケージ | 現在 | 最新 | 状態 | アクション |
|---|---|---|---|---|
| react | 18.2.0 | 19.1.0 | メジャー更新あり | 要検討 |
| lodash | 4.17.21 | 4.17.21 | 最新 | 不要 |

最後に推奨アクション（安全に実行できるもの）をリストアップ。

📝 プロジェクトコマンド vs ユーザーコマンド

🔹 どちらに置くかの判断基準

判断基準	プロジェクトコマンド	ユーザーコマンド
置き場所	.claude/commands/	~/.claude/commands/
呼び出し方	/project:xxx	/user:xxx
Git 管理	される（チーム共有）	されない（個人用）
適するもの	プロジェクト固有のルール	汎用的な個人タスク

プロジェクトコマンドに向いているもの:

• コードレビュー（レビュー観点はプロジェクトごとに違う）
• テスト生成（使うフレームワークはプロジェクト固有）
• コミットメッセージ（ルールはチームで統一したい）
• リファクタリング（コーディング規約はプロジェクト固有）
• 記事校正（ブログのスタイルガイドはサイト固有）

ユーザーコマンドに向いているもの:

• 翻訳（どのプロジェクトでも同じ）
• コードの説明（「これ何してるの？」は汎用的）
• 雑談・ブレスト（プロジェクトに依存しない）

🔹 チーム共有のコツ

プロジェクトコマンドはリポジトリに含まれるので、PR レビューの対象 になります。

チームで運用する場合のおすすめ:

1. .claude/commands/ ディレクトリをリポジトリに含める
2. コマンドの追加・変更も PR を通す — レビュー観点やテストルールの変更はチーム全体に影響するため
3. README 的なファイルを置く — commands/ の中に簡単な一覧を書いておくと、新メンバーが見つけやすい

.claude/
├── commands/
│   ├── review.md       # コードレビュー
│   ├── test-gen.md     # テスト生成
│   ├── commit.md       # コミットメッセージ
│   ├── refactor.md     # リファクタリング
│   ├── plan.md         # 実装計画
│   └── deps.md         # 依存関係整理
└── settings.json       # Hooks 設定（前回記事参照）

前回の記事で紹介した Hooks の設定ファイル と合わせて、.claude/ ディレクトリが 「このプロジェクトでの Claude Code の使い方」を定義する場所 になります。

📝 コマンド設計のコツ

🔹 1. 出力フォーマットを明記する

「レビューして」だけだと、Claude は毎回違うフォーマットで返してきます。出力の形を指定 しておくと、結果が安定します。

## 悪い例
コードをレビューしてください。

## 良い例
コードをレビューしてください。

問題ごとに以下の形式で報告してください。
- **ファイル**: パス
- **重要度**: High / Medium / Low
- **内容**: 問題の説明
- **修正案**: コードブロック

🔹 2. 「やらないこと」も書く

Claude は親切なので、指示していないことまでやろうとすることがあります。スコープを明確に制限 すると、意図しない変更を防げます。

## やること
- 変数名の改善
- 不要な import の削除

## やらないこと
- 機能の追加や変更
- テストの修正
- ライブラリの入れ替え

🔹 3. 引数が空の時のデフォルト動作を決める

$ARGUMENTS が空の場合にどうするかを明記しておくと、引数なしでも使えるコマンドになります。

$ARGUMENTS のファイルをレビューしてください。
引数が空の場合は、`git diff --staged` の変更を対象にしてください。

🔹 4. 段階的に指示する

一度に全部やらせるより、ステップを分けて指示 した方が精度が上がります。

以下のステップで作業してください。

1. まず対象ファイルを読んで構造を理解する
2. 問題点を洗い出してリストアップする（この時点では修正しない）
3. リストを確認してもらう
4. 承認されたら修正を実行する

🔹 5. 具体例を入れる

Claude に「こういう出力がほしい」という 実例 を 1 つ入れるだけで、出力の精度が劇的に上がります。

## 出力例
**[Medium] src/utils/format.ts:18**
`userInput` が `null` の場合に `toString()` で例外が発生します。オプショナルチェーンまたは事前チェックを追加してください。

```typescript
// Before
const label = userInput.toString().trim();

// After
const label = userInput?.toString().trim() ?? '';
```

📝 応用: コマンドの組み合わせ

カスタムコマンドは 組み合わせて使う と真価を発揮します。

🔹 開発フロー例

1. /project:plan ログイン画面にバリデーションを追加
   → 計画を確認

2. （Claude が実装）

3. /project:review
   → 実装結果をセルフレビュー

4. /project:test-gen src/components/LoginForm.tsx
   → テストを自動生成

5. /project:commit
   → コミットメッセージを自動生成

plan → 実装 → review → test → commit という流れが、すべてスラッシュコマンドで回せます。毎回同じクオリティの出力を得つつ、指示にかかる時間はほぼゼロ。

🔹 週次メンテナンス

毎週月曜日:
1. /project:deps          → 依存関係チェック
2. /project:review src/   → プロジェクト全体レビュー

こういった 定期タスクもコマンド化 しておくと、「やらなきゃと思いつつ忘れる」がなくなります。

📝 注意点

🔹 コマンドが多すぎると逆効果

30 個も 40 個もコマンドを作ると、どれを使えばいいか分からなくなります。最初は 3〜5 個 に絞って、本当に毎回使うものだけコマンド化しましょう。

おすすめの最初の 3 つ:

1. /project:review — コードレビュー
2. /project:commit — コミットメッセージ
3. /project:plan — 実装計画

🔹 コマンドは育てるもの

最初から完璧なコマンドを作る必要はありません。使いながら「この観点が足りないな」「この出力フォーマットは使いにくいな」と感じたら、.md ファイルを編集するだけ で即座にアップデートできます。

コードと同じで、小さく始めて、使いながら改善 するのが一番です。

🔹 機密情報を書かない

コマンドファイルに API キーやパスワードを直接書かないでください。プロジェクトコマンドは Git 管理されるので、リポジトリに秘密情報が入ってしまいます。

## 悪い例
APIキー sk-xxxx を使って OpenAI にリクエストを送ってください。

## 良い例
.env に設定された OPENAI_API_KEY を使って OpenAI にリクエストを送ってください。

📝 さいごに

カスタムスラッシュコマンドは、「毎回同じことを打つ」から「一度書いて永遠に使う」への転換 です。

やっていることはシンプルで、.md ファイルを置くだけ。でもその効果は累積していきます。1 日 10 回コマンドを使えば、1 週間で 70 回、1 ヶ月で 300 回。毎回 30 秒のプロンプト入力を省略 するだけで、月に 150 分（2 時間半）の節約になります。

さらに大事なのは 品質の安定 です。人間が毎回手打ちするとプロンプトの品質にばらつきが出ますが、コマンドなら 何百回使っても同じクオリティの指示 が出せます。

前回の Hooks でガードレールを作る記事 と、前々回の git worktree で並列開発する記事 と合わせて:

• Hooks で安全を担保し
• Commands で品質を安定させ
• Worktree で並列に走らせる

この 3 つが揃うと、Claude Code の使い方が まるで別物 になります。まずは /project:review 一つから試してみてください。