はじめに

Claude Codeには標準で多くのスラッシュコマンドが用意されていますが、プロジェクト固有のワークフローや繰り返し行うタスクには、カスタムスラッシュコマンドが効果的です。カスタムコマンドを活用することで、複雑なプロンプトを1行で呼び出せるようになり、チーム全体の開発効率を大幅に向上させることができます。

本記事では、カスタムスラッシュコマンドの作成方法から実践的な活用パターンまで解説します。この記事を読むことで、以下のことができるようになります。

  • .claude/commandsディレクトリの構成と仕組みを理解する
  • プロジェクト固有のカスタムコマンドを作成する
  • $ARGUMENTSプレースホルダーで動的なコマンドを実装する
  • 個人用コマンドとチーム共有コマンドを適切に使い分ける

実行環境

  • オペレーティングシステム: macOS 10.15以上、Ubuntu 20.04以上/Debian 10以上、Windows 10以上（WSL 1/2またはGit for Windows）
  • ハードウェア: 4GB以上のRAM
  • Node.js 18以上（npmインストールの場合のみ必要）
  • インターネット接続（認証およびAI処理に必要）
  • シェル環境: Bash、Zsh、またはFish推奨

前提条件

  • Claude Codeがインストール済みであること
  • コマンドライン操作の基礎知識
  • プログラミングの基礎知識（言語は問わない）

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

カスタムスラッシュコマンドは、Markdownファイルとして定義されたプロンプトテンプレートです。定義したコマンドは/で始まるスラッシュコマンドとしてClaude Codeから呼び出せます。

カスタムコマンドのメリット

カスタムコマンドを導入することで、以下のメリットが得られます。

メリット 説明
再利用性 一度定義すれば何度でも使用可能
一貫性 チーム全体で同じワークフローを適用
効率化 複雑なプロンプトを1行で実行
共有 Gitで管理してチームに展開

コマンドの種類と配置場所

カスタムコマンドは配置場所によって3つのスコープに分かれます。

graph TB
    A[カスタムコマンド] --> B[プロジェクトコマンド]
    A --> C[個人コマンド]
    A --> D[プラグインコマンド]
    B --> E[".claude/commands/<br>チームで共有"]
    C --> F["~/.claude/commands/<br>全プロジェクトで利用"]
    D --> G["plugin-name/commands/<br>プラグイン機能"]

プロジェクトコマンド（チーム共有）

.claude/commands/
├── review.md      # /review コマンド
├── test.md        # /test コマンド
└── deploy.md      # /deploy コマンド
  • 配置場所：.claude/commands/
  • スコープ：特定のプロジェクトで利用可能
  • 表示：/helpで「(project)」と表示
  • 用途：チームワークフロー、プロジェクト固有タスク
  • Git管理：リポジトリにコミットしてチームで共有可能

個人コマンド（全プロジェクト共通）

~/.claude/commands/
├── my-workflow.md  # 個人用ワークフロー
└── quick-fix.md    # 素早い修正用
  • 配置場所：~/.claude/commands/
  • スコープ：すべてのプロジェクトで利用可能
  • 表示：/helpで「(user)」と表示
  • 用途：個人ワークフロー、クロスプロジェクトユーティリティ

基本的なコマンドの作成

最もシンプルなコマンド

最もシンプルな形式では、Markdownファイルにプロンプトを記述するだけです。

1
2
3
4
5
6
7

このコードをセキュリティの観点からレビューしてください。

以下の点を確認してください：
- SQLインジェクション
- XSS攻撃
- 認証バイパス
- 機密データの取り扱い

このファイルを.claude/commands/security-review.mdとして保存すると、/security-reviewコマンドとして呼び出せます。

YAMLフロントマター付きコマンド

より高度なコマンドでは、YAMLフロントマターで設定を追加できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

---
description: コードのセキュリティレビューを実行
allowed-tools: Read, Grep, Bash(git:*)
---

このコードをセキュリティの観点からレビューしてください。

以下の点を確認してください：
- SQLインジェクション
- XSS攻撃
- 認証バイパス
- 機密データの取り扱い

問題が見つかった場合は、ファイルパスと行番号を示してください。

利用可能なフロントマターフィールド

フィールド 説明 デフォルト
description /helpに表示される説明文 なし
allowed-tools コマンド実行時に許可するツール 継承
model 使用するモデル（sonnet/opus/haiku） 継承
argument-hint 引数のヒント（補完時に表示） なし
disable-model-invocation プログラムからの呼び出しを禁止 false

動的引数の活用

$ARGUMENTSプレースホルダー

$ARGUMENTSを使用すると、コマンド呼び出し時に渡された引数をプロンプトに埋め込めます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

---
description: 指定されたIssueを分析して修正
argument-hint: [issue-number]
---

GitHub Issue #$ARGUMENTS を分析し、修正してください。

以下の手順で進めてください：

1. `gh issue view $ARGUMENTS`でIssueの詳細を確認
2. 問題の原因を特定
3. 関連するファイルを検索
4. 修正を実装
5. テストを実行して動作確認
6. コミットメッセージを作成

使用例：

1

> /fix-issue 1234

上記のコマンドを実行すると、$ARGUMENTSが1234に置き換えられます。

位置引数（$1, $2, $3…）

複数の引数を個別に受け取る場合は、位置引数を使用します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

---
description: 指定環境にデプロイ
argument-hint: [environment] [version]
---

$1 環境にバージョン $2 をデプロイしてください。

デプロイ前チェック：
1. $1 の設定ファイルが存在するか確認
2. バージョン $2 が有効か確認
3. クラスターへの接続を確認

デプロイ手順：
1. マニフェストをバージョン $2 で更新
2. $1 環境に設定を適用
3. ロールアウト状況を監視
4. Podのヘルスチェック
5. スモークテストを実行

使用例：

1

> /deploy staging v1.2.3

この場合、$1はstaging、$2はv1.2.3に置き換えられます。

ファイル参照（@構文）

@構文を使用すると、指定したファイルの内容をコンテキストとして含めることができます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

---
description: 指定ファイルのドキュメントを生成
argument-hint: [source-file]
---

@$1 のドキュメントを生成してください。

以下の情報を含めてください：

**概要**
- 目的と責務
- 主な機能
- 依存関係

**API仕様**
- 関数/メソッドのシグネチャ
- パラメータの説明と型
- 戻り値と型
- 発生する例外

**使用例**
- 基本的な使い方
- 一般的なパターン
- エッジケース

使用例：

1

> /document src/api/users.ts

この例では、src/api/users.tsの内容が読み込まれ、Claudeがその内容を分析してドキュメントを生成します。

Bashコマンドの埋め込み

コマンド内でBashコマンドを実行し、その結果をコンテキストとして含めることができます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

---
description: 現在のGit状態を分析
allowed-tools: Bash(git:*)
---

現在のリポジトリの状態を分析してください。

現在の状態: !`git status --short`
最近のコミット: !`git log --oneline -5`
変更されたファイル: !`git diff --name-only`

上記の情報を基に、以下を報告してください：

1. 未コミットの変更の概要
2. 最近の変更傾向
3. 次に行うべきアクションの提案

! バッククォート構文（!command）で囲まれたコマンドは、プロンプトがClaudeに送信される前に実行され、その出力がプロンプトに埋め込まれます。

実践的なコマンド例

コードレビューコマンド

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
description: PRのコードレビューを実行
allowed-tools: Read, Bash(git:*)
---

このPull Requestをレビューしてください。

変更内容: !`git diff main...HEAD --stat`

以下の観点でレビューしてください：

1. **コード品質**
   - 可読性と保守性
   - 一貫したスタイル
   - 適切な抽象化レベル

2. **潜在的な問題**
   - ロジックエラーやバグ
   - 未処理のエッジケース
   - パフォーマンス上の懸念

3. **ベストプラクティス**
   - デザインパターンの適切な使用
   - エラーハンドリング
   - ドキュメントの充実度

具体的なフィードバックをファイル名と行番号とともに提供してください。

テスト生成コマンド

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

---
description: ファイルのテストを生成
argument-hint: [source-file]
allowed-tools: Read, Write, Bash(npm:*, jest:*)
---

@$1 のユニットテストを生成してください。

以下の手順で進めてください：

1. 対象ファイルの機能を分析
2. 既存のテストパターンを確認
3. テストケースを設計
   - 正常系テスト
   - 異常系テスト
   - エッジケース
   - 境界値テスト

4. テストファイルを作成
   - 既存の命名規則に従う
   - 既存のテストフレームワークを使用

5. テストを実行して検証

テスト対象のモックは最小限にし、実際の動作を検証することを優先してください。

Issue対応コマンド

このコマンドは、Anthropicのベストプラクティスで紹介されている典型的なワークフローです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

---
description: GitHub Issueを分析して修正
argument-hint: [issue-number]
allowed-tools: Read, Write, Bash(gh:*, git:*, npm:*)
---

GitHub Issue #$ARGUMENTS を分析し、修正してください。

以下の手順で進めてください：

1. `gh issue view $ARGUMENTS`でIssueの詳細を取得
2. 問題の内容を理解
3. コードベースで関連ファイルを検索
4. 必要な変更を実装
5. テストを作成・実行して修正を検証
6. リントと型チェックをパス
7. 説明的なコミットメッセージを作成
8. プッシュしてPRを作成

GitHub関連のタスクにはGitHub CLI（`gh`）を使用してください。

使用例：

1

> /fix-github-issue 1234

2ファイル比較コマンド

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

---
description: 2つのファイルを比較分析
argument-hint: [file1] [file2]
---

@$1 と @$2 を比較分析してください。

**分析内容：**

1. **差分**
   - 追加された行
   - 削除された行
   - 変更された行

2. **機能的な変更**
   - 破壊的変更
   - 新機能
   - バグ修正
   - リファクタリング

3. **影響範囲**
   - 影響を受けるコンポーネント
   - 他の箇所で必要な更新
   - マイグレーション要件

4. **推奨事項**
   - コードレビューの重点箇所
   - テスト要件
   - ドキュメント更新の必要性

構造化された比較レポートとして提示してください。

使用例：

1

> /compare-files src/old-api.ts src/new-api.ts

コマンドの整理と命名規則

フラット構造

コマンド数が少ない場合（5〜15個程度）は、フラット構造がシンプルで管理しやすいです。

.claude/commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md

名前空間構造

コマンドが多くなる場合は、サブディレクトリで整理できます。

.claude/commands/
├── ci/
│   ├── build.md        # /build (project:ci)
│   ├── test.md         # /test (project:ci)
│   └── lint.md         # /lint (project:ci)
├── git/
│   ├── commit.md       # /commit (project:git)
│   └── pr.md           # /pr (project:git)
└── docs/
    ├── generate.md     # /generate (project:docs)
    └── publish.md      # /publish (project:docs)

サブディレクトリを使用すると、/helpでカテゴリ別にコマンドが表示され、見つけやすくなります。

命名規則のベストプラクティス

コマンド名は動詞-名詞パターンを使用すると、意図が明確になります。

良い例 悪い例
review-pr.md pr.md
fix-issue.md issue.md
generate-docs.md docs.md
run-tests.md tests.md

チーム開発での活用

プロジェクトコマンドのGit管理

.claude/commands/ディレクトリをGitで管理することで、チーム全体でコマンドを共有できます。

1
2
3
4
5
6
7
8
9

# コマンドディレクトリを作成
mkdir -p .claude/commands

# コマンドファイルを作成
echo "レビュープロンプト..." > .claude/commands/review.md

# Gitにコミット
git add .claude/commands/
git commit -m "feat: チーム共有のカスタムコマンドを追加"

個人コマンドとプロジェクトコマンドの使い分け

flowchart TD
    A[新しいコマンドを作成] --> B{このプロジェクト<br>固有か？}
    B -->|Yes| C{チームで<br>共有したいか？}
    B -->|No| D[個人コマンド<br>~/.claude/commands/]
    C -->|Yes| E[プロジェクトコマンド<br>.claude/commands/]
    C -->|No| F[ローカルコマンド<br>.claude/commands/*.local.md]
    
    E --> G[Gitにコミット]
    F --> H[.gitignoreに追加]
    D --> I[全プロジェクトで利用可能]

使い分けの基準

種類 配置場所 Git管理 用途
チーム共有 .claude/commands/ する プロジェクト標準ワークフロー
個人ローカル .claude/commands/*.local.md しない 個人的な実験・カスタマイズ
全プロジェクト共通 ~/.claude/commands/ しない 個人の汎用ワークフロー

.gitignoreの設定

ローカル専用のコマンドをGit管理から除外する場合は、.gitignoreに追加します。

# ローカル専用のClaude Codeコマンド
.claude/commands/*.local.md

ベストプラクティス

コマンド設計の原則

  1. 単一責任: 1つのコマンドは1つの明確なタスクに集中
  2. 明確な説明: /helpで見つけやすい説明文を記述
  3. 引数のドキュメント化: argument-hintで必ず引数を説明
  4. 最小限のツール許可: allowed-toolsは必要最小限に
  5. 一貫した命名: 動詞-名詞パターンを採用

エラーハンドリング

引数が不足した場合のガイダンスを含めることで、ユーザー体験が向上します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

---
description: 環境へのデプロイ
argument-hint: [environment]
---

環境引数を検証: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`

$1 が有効な環境の場合：
  $1 環境へのデプロイを実行

それ以外の場合：
  有効な環境を説明: dev, staging, prod
  使用方法を表示: /deploy [environment]

コメントの活用

複雑なコマンドには、意図を説明するコメントを含めます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

---
description: 本番リリース準備
allowed-tools: Read, Write, Bash(git:*, npm:*)
---

<!-- 
このコマンドは本番リリース前のチェックリストを実行します。
すべてのチェックをパスするまでリリースしないでください。
-->

本番リリースの準備を行います。

**事前チェック**
1. mainブランチが最新か確認
2. すべてのテストがパス
3. 型チェックがパス
4. リントがパス

**リリース準備**
1. CHANGELOGの更新
2. バージョン番号の更新
3. リリースタグの作成

トラブルシューティング

コマンドが/helpに表示されない

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# ファイルの場所を確認
ls -la .claude/commands/my-command.md

# パーミッションを確認
chmod 644 .claude/commands/my-command.md

# 構文を確認（フロントマターが正しいか）
head -n 20 .claude/commands/my-command.md

# Claude Codeを再起動
claude

引数が展開されない

1
2
3
4
5
6

# 構文を確認
grep '\$1' .claude/commands/my-command.md
grep '\$ARGUMENTS' .claude/commands/my-command.md

# シンプルなコマンドでテスト
echo "Test: \$1 and \$2" > .claude/commands/test-args.md

Bashコマンドが実行されない

1
2
3
4
5

# allowed-toolsを確認
grep "allowed-tools" .claude/commands/my-command.md

# 構文を確認（!`command`形式か）
grep '!\`' .claude/commands/my-command.md

まとめ

カスタムスラッシュコマンドは、Claude Codeの柔軟性を最大限に活用するための強力な機能です。本記事で解説した内容を活用することで、以下のことが実現できます。

  • 繰り返しタスクの自動化: 複雑なプロンプトを1行のコマンドに集約
  • チーム開発の効率化: Git管理でコマンドをチーム全体に展開
  • 一貫性の確保: 標準化されたワークフローでコード品質を維持
  • オンボーディングの迅速化: 新メンバーもすぐにベストプラクティスを適用可能

まずはシンプルなコマンドから始めて、徐々に複雑なワークフローを構築していくことをおすすめします。チームで効果的なコマンドが見つかったら、積極的に共有して開発効率の向上に活かしてください。

参考リンク