Claude Code のカスタムスラッシュコマンドとサブエージェントはどう使い分けるか

こんにちは、 Gaji-Labo フロントエンドエンジニアの @semigura です。

Claude Code を使っているものの、カスタムスラッシュコマンドとサブエージェントをどう使い分けるか悩んでいる方は多いと思います。
事実、自分も実際のプロジェクトで活用したり社内での知見交換を通じて自分なりの運用ルールを定めるまでは悩んでいました。

そんな方のために今回の記事では、コンテキストを切って処理してほしいか、コンテキストを持って処理するべきかを基準にした運用ルールと、Gaji-Labo の開発で実際に使っているパターンを紹介します。

※当記事の Claude Code は v2.0.8 を使用しています。

カスタムスラッシュコマンド/サブエージェントの概要

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

よく使うプロンプトをコマンド化して再利用できる機能です。

# .claude/commands/generate-test.md
---
description: テストコード生成
---

この関数に対する単体テストコードを書いてください。
エッジケースも含めて網羅的にお願いします。

.claude ディレクトリ配下にこのようなマークダウンファイルとして置くと /generate-test と入力するだけで上記のプロンプトが呼び出せるようになります。

サブエージェント

特定のタスクに特化したエージェントを作成し、メインセッションから呼び出せる機能です。

# .claude/agents/generate-test-agent.md
---
name: generate-test-agent
description: テストコード生成エージェント
---

あなたは優秀なQAエンジニアです。
この実装に対するテストケースを生成し、テストコードを書いてください。

最大の特徴は、メインの会話とは別のコンテキストで動作することです。メインスレッドのコンテキストに影響されず、特定のタスクを集中して実行させることができます。

カスタムスラッシュコマンドは /command で呼び出しますが、サブエージェントは @agent-name で呼び出せます。また、明示的に呼び出さずとも、メインセッションが必要と判断した場合に自動的にサブエージェントを呼び出すこともあります。

共通するメリット

サブエージェントもカスタムスラッシュコマンドも、「AIに指示したいプロンプトやタスクを使い回せる」という点では似ています。

• 頻繁に使うプロンプトやタスクを簡単に呼び出せる
• チーム内で共有できる（リポジトリで管理できる）
• プロジェクト固有のベストプラクティスを標準化できる

これらのメリットが共通化しているため、どちらを使っても同じでは？と思えてしまい、使い分けが難しく感じられました。

しかしここでポイントとなるのがサブエージェントの項目で書いた「メインの会話とは別のコンテキストで動作する」ことでした。

実践的な使い分け

以前の自分は「どのような作業であってもそれまでのコンテキストはあったほうがいいのでは？」と考え、カスタムスラッシュコマンドばかりを使っていました。

しかしたとえばコードレビューのように「客観的な視点で評価してほしい」場合には、それまでの会話内容や指示内容が影響してしまい、望ましくない結果になることが多いことに気づきました。

この「客観的な視点が欲しいか否か」で判断すると、カスタムスラッシュコマンドとサブエージェントの使い分けが明確にできると考えています。

イメージとしては、カスタムスラッシュコマンドは「今話している相手（Claude Code）に対して定型的な頼み事をする」、サブエージェントは「第三者に頼み事をする」という感じです。

カスタムスラッシュコマンドが適している指示

---
description: 作業計画からの実装
---

生成した作業計画に基づいて、ページとコンポーネントを実装してください。
既存のコードスタイルに合わせて、適切なファイル配置でお願いします。
...

このような、これまでの作業内容を踏まえた上での実装タスクはカスタムスラッシュコマンドが適しています。

メインのスレッドで作業が進むので、結果を見ながら「この実装はちょっと違う」とすぐにフィードバックできるのもメリットです。

サブエージェントが適している場面

---
name: review-pr
description: コードレビュー
---

与えられたコード差分に対して、以下の観点でコードレビューを行ってください：
- バグの可能性
- パフォーマンス上の問題
- セキュリティリスク
- 保守性・可読性
...

コードレビューは第三者的な視点で行ってほしいタスクなのでサブエージェントが適しています。
メインのコンテキストを引き継がないため、より客観的なレビューが期待できます。

---
name: tech-research
description: 技術的な調査タスク
---

特定の技術的なトピックについて調査し、要点をまとめてください。
...

このような技術的な調査タスクも特定のコンテキストに依存しない情報収集が求められるため、サブエージェントが適しています。

開発ワークフローへの組み込み

この使い分けを実際のプロジェクトに適用すると以下のような形になりました。

• 仕様定義に基づいて作業計画を立てる : カスタムスラッシュコマンド
  • フィードバックをしながら調整
• 作業計画に基づいて実装を行う : カスタムスラッシュコマンド
  • 計画の文脈を引き継いでコーディング
• 実装に対してテストコードを生成・修正する : カスタムスラッシュコマンド
  • 実装内容を理解した上でテストを作成・修正
• 実装全体に対してコードレビューを行う : サブエージェント
  • ここでコンテキストを分け、客観的な視点でレビューしてもらう

カスタムスラッシュコマンド/サブエージェントを使い分けている他、カスタムスラッシュコマンドもフェーズごとに細かく分割してみています。

こうすることでカスタムスラッシュコマンドとサブエージェントのメリットを最大限に活かしつつ、プロジェクトでの質とスピードを両立したワークフローが実践できていると感じています。

まとめ

今回は、Claude Code のカスタムスラッシュコマンドとサブエージェントの使い分けについて、自分なりの考え方をまとめました。

再度ポイントを整理すると以下の通りです。

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

• コンテキストを引き継ぎたい
• それまでの会話を踏まえた作業
• 実装、テスト生成、バグ修正など
• 人間がフィードバックしながら進めたい作業
• 会話の中で頼み事をするイメージ

サブエージェント

• コンテキストをリセットしたい
• 客観的な視点が欲しい作業
• コードレビュー、技術調査など
• 専門特化した独立タスク
• 別の専門家に依頼するイメージ

両者を適切に使い分けることで、AIエージェントを活用した開発の効率を最大化できます。

この記事で紹介した使い分けのアプローチは、実プロジェクトでの試行錯誤と、 Gaji-Labo チーム内での知見共有を通じて得られたものです。

Gaji-Labo では、「こんな使い方をしたら効率化できた」「この設定だと期待通りに動かなかった」といったようなこうしたAI活用の知見を週次の社内勉強会や Slack チャンネルで積極的に共有し合っています。

ぜひ参考にしていただければ幸いです。

Gaji-Labo フロントエンドエンジニア向けご案内資料