Claude Codeのカスタムスラッシュコマンド作成術｜チーム標準化の鍵

Claude Codeを日常的に使っていると、同じような指示を毎回手で入力している場面に気づきます。「PRを出す前にこのチェックリストを確認して」「コミットメッセージはこのフォーマットで」「テストはこの方針で書いて」— 毎回100文字以上のプロンプトを手打ちするのは、開発体験として明らかに非効率です。

カスタムスラッシュコマンドは、こうした繰り返しの指示をMarkdownファイルとして定義し、コマンド1つで呼び出せるようにする仕組みです。本記事では、コマンドの仕組み・作り方・実用的な5つの例（ファイル内容つき）・チーム展開戦略・バージョニングの考え方を解説します。Claude Codeの基本についてはClaude Code完全ガイドを参照してください。

結論 — スラッシュコマンドは「チームの暗黙知を実行可能にする」仕組み

カスタムスラッシュコマンドの本質は、チームが暗黙的に共有しているベストプラクティスを、再現可能な形で実行可能にすることです。属人的な知識やチェックリストをコマンドとして定義すれば、新メンバーでもベテランと同じ品質の作業ができるようになります。

重要なポイントとして、スラッシュコマンドは「プロンプトの再利用」であって「スクリプトの実行」ではありません。Markdownファイルの中身がそのままClaude Codeへの指示として渡される — この仕組みを理解しているかどうかで、効果的なコマンドが書けるかが変わります。

.claude/commands/ の構造と仕組み

カスタムスラッシュコマンドは、プロジェクトルートの .claude/commands/ ディレクトリにMarkdownファイルとして配置します。

.claude/
└── commands/
    ├── review.md          → /review で呼び出し
    ├── commit.md          → /commit で呼び出し
    ├── test.md            → /test で呼び出し
    ├── doc.md             → /doc で呼び出し
    └── deploy-check.md    → /deploy-check で呼び出し

ファイル名がそのままコマンド名になります。サブディレクトリを使えば名前空間の分離も可能です。

.claude/
└── commands/
    ├── review.md              → /review
    ├── test/
    │   ├── unit.md            → /test:unit
    │   └── e2e.md             → /test:e2e
    └── check/
        ├── security.md        → /check:security
        └── performance.md     → /check:performance

個人用とプロジェクト共通の使い分け

スラッシュコマンドには2つの配置場所があります。

配置場所	スコープ	Git管理
.claude/commands/	プロジェクト共通	リポジトリにコミット
~/.claude/commands/	個人用（全プロジェクト共通）	個人のdotfilesで管理

チーム標準のコマンドはプロジェクトの .claude/commands/ に、個人のワークフローに特化したコマンドは ~/.claude/commands/ に配置するのが推奨です。

$ARGUMENTS プレースホルダー

コマンドに引数を渡す場合は、Markdownファイル内で $ARGUMENTS を使います。

/review src/services/payment-service.ts

と実行すると、Markdownファイル内の $ARGUMENTS が src/services/payment-service.ts に置き換わってClaude Codeに渡されます。

5つの実用コマンド — 実際のファイル内容

1. /review — コードレビュー

# コードレビュー

$ARGUMENTS のファイル（指定がない場合は git diff --name-only で変更ファイルを取得）を対象に、以下の観点でレビューを実施してほしい。

## 必須チェック（違反は修正必須）
- any の使用がないか
- as による型アサーションがないか（型ガードまたはZodで解決すべき）
- ! (non-null assertion) の使用がないか
- console.log が残っていないか
- .env や認証情報のハードコードがないか

## 設計チェック（改善提案として報告）
- 1関数50行を超えていないか
- ネストが3レベルを超えていないか
- 1ファイル400行を超えていないか
- 同一ロジックの重複がないか（3箇所以上なら抽象化を提案）

## テストチェック
- 変更したロジックに対応するテストが存在するか
- 境界値・エラーケースのテストがあるか

## 出力形式
問題を以下の3カテゴリに分類して報告してほしい：
- 🔴 必須修正: 上記「必須チェック」の違反
- 🟡 推奨改善: 上記「設計チェック」の指摘
- 🟢 提案: より良いアプローチの提案

問題がなければ「レビュー通過」と報告してほしい。

使い方のコツ: 引数なしで /review を実行すると、git diff --name-only で変更ファイルを自動取得するフォールバックが入っています。PR前のセルフレビューとして使う場合はこの形が便利です。

2. /commit — コミットメッセージ生成とコミット実行

# コミット

以下の手順でコミットを作成してほしい。

## 手順1: 変更内容の確認
git diff --cached を実行し、ステージされた変更内容を確認する。
ステージされた変更がない場合は git diff を実行して未ステージの変更を確認し、
コミット対象のファイルを提案する（git add . は絶対に使わない）。

## 手順2: コミットメッセージの提案
以下のフォーマットでコミットメッセージを提案する。

形式: <type>: <description>

typeの選択基準:
- feat: 新しい機能の追加
- fix: バグの修正
- refactor: 動作を変えないコード改善
- test: テストの追加・修正
- docs: ドキュメントのみの変更
- chore: ビルド・設定・依存関係の変更
- perf: パフォーマンス改善

descriptionのルール:
- 日本語で記述する
- 50文字以内
- 「何を」ではなく「なぜ」を意識する

## 手順3: 承認を求める
提案したコミットメッセージを表示し、承認を求める。
承認されたら git commit を実行する。
承認されなければ、フィードバックを反映して再提案する。

運用上の注意: git add . を禁止している点に注目してください。複数のClaude Codeセッションが並行して動いている場合、他のセッションの変更を巻き込むリスクを防いでいます。

3. /test — テスト作成

# テスト作成

$ARGUMENTS のファイルに対するテストを作成してほしい。

## テストファイルの配置
- 実装ファイルと同じディレクトリに配置する
- ファイル名: {元のファイル名}.test.ts（または .test.tsx）
- 既にテストファイルがある場合は、既存のテストを壊さずに追加する

## テスト構造
describe ブロックで関数ごとにグループ化し、各関数について以下をカバーする：

1. 正常系（Happy path）: 期待通りの入力で期待通りの出力が返る
2. 異常系（Error cases）: 不正な入力でエラーが発生する
3. 境界値（Edge cases）: 空配列、空文字列、0、null、undefined、最大値

## 外部依存のモック化
- API呼び出し、DB接続、ファイルI/Oはモック化する
- モックは vi.mock() で定義する（Vitest前提）
- モックの戻り値は実際のレスポンス形式に合わせる

## カバレッジ目標
- 新規ファイル: 80%以上
- 既存ファイルへの追加: カバレッジを下げない

## 制約
- テスト内で any を使わない
- snapshot テストは使わない（脆い）
- テスト完了後に pnpm test を実行して全テストがパスすることを確認する

4. /doc — JSDoc生成

# ドキュメント生成

$ARGUMENTS のファイルを対象に、JSDoc コメントを生成・更新してほしい。

## 対象
- export されている関数、型、インターフェースのみ
- 内部関数（export されていないもの）にはJSDocを付けない

## JSDocのルール
- @description: 関数の目的を1行で記述（日本語）
- @param: 各引数の型と説明
- @returns: 戻り値の型と説明
- @throws: スローする可能性のあるエラーの種類と条件
- @example: 使用例を1つ以上（型が複雑な場合）

## 制約
- 既存のJSDocがある場合は内容を確認し、必要に応じて更新する
- 実装の変更は行わない（ドキュメントの追加のみ）
- 引数名や関数名から明らかに推測できる説明は冗長に書かない

## 例

```typescript
/**
 * @description セッションの評価スコアを算出する
 * @param session - 評価対象のセッションデータ
 * @param weights - 各評価項目の重み付け設定
 * @returns 0-100の範囲で正規化されたスコア
 * @throws {ValidationError} セッションデータが不正な場合
 */
export function evaluateSession(
  session: Session,
  weights: EvaluationWeights
): number {

### 5. /deploy-check — デプロイ前チェック

```markdown
# デプロイ前チェック

本番デプロイ前の安全確認を実施する。以下の項目を順番にチェックし、結果を報告してほしい。

## チェック項目

### 1. 型チェック
pnpm typecheck を実行する。

### 2. Lint
pnpm lint を実行する。

### 3. テスト
pnpm test を実行する。

### 4. ビルド
pnpm build を実行する。

### 5. 環境変数の差分
.env.example と .env.local を比較し、不足している環境変数がないか確認する。
.env ファイルの中身は表示しない（セキュリティ上の理由）。

### 6. マイグレーション状態
未適用のマイグレーションファイルがないか確認する。

### 7. 依存パッケージ
pnpm audit を実行し、既知の脆弱性がないか確認する。

## 結果報告
各項目について以下の形式で報告する：

| 項目 | 結果 | 詳細 |
|------|------|------|
| 型チェック | PASS/FAIL | エラー内容（FAILの場合） |
| ... | ... | ... |

全項目PASSの場合: 「デプロイ可能です」と報告する。
FAILがある場合: 問題の内容と修正案を提示する。

チーム標準化戦略

段階的に導入する

最初から大量のコマンドを作るのではなく、同じプロンプトを3回以上手入力したらコマンド化するのが実用的です。

導入の推奨順序：

1. /commit — 最も頻繁に使い、フォーマットの統一効果が高い
2. /review — PR前のセルフレビューとして全員が使える
3. /test — テスト作成の方針を統一できる
4. /doc — ドキュメントの書き方が揃う
5. /deploy-check — デプロイ事故の防止に直結する

PRベースでコマンドを改善する

コマンドの追加・修正もPRを通じて議論できるため、チームの合意形成が自然に行えます。実際の運用で「この観点が足りなかった」「この指示だと意図と違う結果が出た」というフィードバックを反映して改善していくプロセスが重要です。

# コマンド改善のPR例
fix: /review コマンドに Zod バリデーションのチェック項目を追加

外部APIからのレスポンスを直接型キャストしているケースが
レビューで見逃されていたため、Zodバリデーションの有無を
チェック項目に追加する。

バージョニングの考え方

コマンドはGitリポジトリで管理されるため、自然にバージョン管理されます。ただし、以下の点に注意が必要です。

破壊的変更のケース: コマンドの出力形式を変えると、そのコマンドの結果に依存しているワークフローが壊れる可能性があります。大きな変更はチームに周知してから実施してください。

コマンドの廃止: 使われなくなったコマンドは放置せず、READMEに非推奨マークを付けるか削除します。.claude/commands/ に大量のファイルがあると、Claude Codeの / 入力時のサジェストが見づらくなります。

CLAUDE.md との使い分け

混同されがちですが、役割は明確に異なります。

観点	CLAUDE.md	スラッシュコマンド
適用タイミング	常に自動適用	明示的に呼び出す
用途	全セッション共通のルール	特定タスクのアクション
例	コーディング規約、禁止事項	レビュー実施、テスト作成

# CLAUDE.md に書くべきもの
- any 禁止
- ファイルサイズ上限
- コミットメッセージ形式
- git add . 禁止

# スラッシュコマンドにすべきもの
- /review（レビュー実施）
- /commit（コミット作成）
- /test（テスト生成）

CLAUDE.mdは「常にClaude Codeが守るべきルール」、スラッシュコマンドは「必要なときに呼び出すアクション」です。この区分を明確にしておくことで、設定の重複や矛盾を防げます。

よくある質問

まとめ — スラッシュコマンドでチームの暗黙知を実行可能にする

カスタムスラッシュコマンドは、チームが日常的に行っている作業手順を、再現可能かつ実行可能な形で定義する仕組みです。レビュー基準、コミットルール、テスト方針、デプロイ前チェックなど、繰り返し行われる作業をコマンド化することで、品質のばらつきを減らし、オンボーディングのコストも下げられます。

まずは最も頻繁に繰り返している指示を1つ選び、.claude/commands/ にMarkdownファイルを1つ作るところから始めてみてください。そのコマンドが定着したら、次に頻度の高い指示をコマンド化する。この積み重ねが、チーム全体のClaude Code活用レベルを引き上げます。

関連記事

• Claude Code完全ガイド｜開発組織が今知るべき導入判断の全体像