
Claude Code でカスタムサブエージェントを作成する
Claude Code では特定の種類のタスクを処理するために呼び出されるカスタムサブエージェントを作成できます。カスタムサブエージェントを使用することでメインの会話セッションとは別に独立したコンテキストウィンドウを持つことができ、コンテキストの汚染を防ぐことができます。この記事では、Claude Code でカスタムサブエージェントを作成する方法とその利点について解説します。
Claude Code では特定の種類のタスクを処理するために呼び出されるカスタムサブエージェントを作成できます。例えばバックエンド領域に特化したエージェント、コードレビューを専門に行うエージェント、デバッグを行うエージェントといった具合です。
カスタムサブエージェントでは特有のシステムプロンプトやツール、独立したコンテキストウィンドウを持ち、Claude Code はサブエージェントにタスクを委任することでより効率的な問題解決を可能にします。
この記事では Claude Code でカスタムサブエージェントを作成する方法とその利点について解説します。
なぜサブエージェントを使うのか?
特定のタスクに特化したサブエージェントをわざわざ作成するのはなぜでしょうか?大きく分けて 4 つの理由があります。
- コンテキストの分割
- 専門性の向上
- 再利用性
- 権限の分離
コンテキストの分割
基本的な考え方は、我々人類が専門分野ごとに仕事を分業するのとよく似ています。例えばマイクロサービスアーキテクチャのような巨大なコードベースを一人の開発者がすべてを把握するのはほぼ不可能と言ってよいでしょう。そこでシステムアーキテクチャを分割して、各部分を専門の開発者が担当するように分業化します。フロントエンドに特化した開発者はバックエンド技術の詳細を知らなくてよくなるため、その分フロントエンド領域に集中して開発することができます。
このことは AI エージェントにも当てはまります。なぜならば LLM は限られたコンテキストウィンドウしか持たないため、あまりにも多くの情報を一度に処理できないからです。
Claude Code を使用していて 1 つのセッションが長くなりすぎた時、はじめの方にしていた指示がコンテキストウィンドウから漏れてしまった結果、期待から外れたコードを生成してしまった経験があるのではないでしょうか?タスクが大きく複雑になるにつれ、必要なステップ数が増え、LLM が目的を見失ったりする可能性が高くなります。
サブエージェントではメインの会話セッションとは別に独立したコンテキストウィンドウを持つため、特定のタスクを遂行するために指示されたプロンプトの内容を忘れることなくタスクを開始できます。そしてサブエージェントを効果的に活用するためには、小さく単一責任のエージェントとして構築すべきです。エージェントが取り組むタスクを小さく集中させることで、コンテキストウィンドウを管理しやすくなり、エージェントが目的を見失うリスクを減らすことができます。
メインの会話セッションのコンテキストを「汚染」することなくタスクに取り組めるという利点もあります。例えば調査タスクを行う場合には、数多くのファイルやディレクトリを横断して調査する必要があります。その調査の過程で得られた情報はたとえ不要なものであっても、すべてがコンテキストに含まれてしまいます。サブエージェント側では多くのコンテキストを消費したとしても、メインの会話セッションには影響を与えずに要約した情報のみをメインの会話セッションに返すことができます。
なお、Claude Code ではデフォルトで Task
ツールを使用して調査する場合にはサブエージェントを起動するアーキテクチャになっています。
専門性の向上
サブエージェントは特定のタスクに特化したシステムプロンプトを持つことができます。システムプロンプトを特定のドメインに詳細に調整できるため、タスクの成功率を向上させることが期待できます。
再利用性
サブエージェントはプロジェクトもしくは個人単位のスコープで作成できます。例えばチームメンバーが作成したサブエージェントをプロジェクト全体で共有したり、個人で作成したサブエージェントを他のプロジェクトでも再利用できます。
権限の分離
サブエージェントごとに異なるツール、MCP サーバーの権限を設定できます。例えばバックエンドのサブエージェントにはデータベースへのアクセス権限を与える一方で、フロントエンドのサブエージェントにはそのような権限を与えないといったことが可能です。最小の権限の原則に従って、サブエージェントごとに必要な権限のみを与えることで、セキュリティを向上させることができます。
カスタムサブエージェントを作成する
それでは実際に Claude Code でカスタムサブエージェントを作成してみましょう。Claude Code のバージョンが v1.0.60 以降であることを確認してください。
claude --version
1.0.61 (Claude Code)
サブエージェントを作成するには Claude Code を起動した後に /agents
コマンドを入力します。
claude /agents
/agents
コマンドを入力すると、サブエージェントの一覧が表示されます。まだサブエージェントを何も作成していないので、「No agents found」というメッセージが表示されます。新しいサブエージェントを作成するために Create new agent
ボタンを選択しましょう。
始めにプロジェクト単位か個人単位のスコープを選択します。プロジェクト単位では .claude/agents
ディレクトリに、個人単位では ~/.claude/agents
ディレクトリにサブエージェントが作成されます。
続いてどのような方法でサブエージェントを作成するかを選択します。Generate with Claude
を選択するとユーザーが入力したプロンプトを元に Claude がサブエージェントの description と system prompt を生成します。Manual configuration
を選択すると自分で description と system prompt を入力します。ここでは Generate with Claude
を選択してみましょう。
プロンプトを入力する画面が表示されます。ここではプルリクエストを作成するエージェントを作成するプロンプトを入力してみましょう。
GitHub のリポジトリにプルリクエストを作成するエージェントを作成してください。プルリクエストのテンプレートは必ず `.github/pull_request_template.md` に保存されているものを使用してください。プルリクエストのタイトルは `feat: xxx` や `fix: xxx` のように、変更内容を簡潔に表現するプレフィックスを付けてください。
プルリクエストを作成する際には以下の手順に従ってください。
1. 変更内容を確認する
2. 新しいブランチを作成する
3. 変更をコミットする
4. プルリクエストを作成する
Claude の応答をしばらく待った後、使用可能なツールを選択する画面が表示されます。デフォルトの設定では親セッションで使用しているツールが引き継がれる設定となっています。
最後にサブエージェントに割り当てる色を選択します。サブエージェントの色はメインの会話セッションでサブエージェントを呼び出した際に表示され、どのサブエージェントを呼び出したのか視覚的に識別するために便利です。
作成されるサブエージェントのファイルのプレビューが表示されます。問題がなければ Enter キーを押してサブエージェントの作成を完了します。
ここでは以下のようなファイルが作成されました。YAML フロントマター形式のマークダウンファイルとなっており、description
ではどのようなタイミングでサブエージェントを呼び出すのかが記述されています。本文ではサブエージェントのシステムプロンプトが記述されています。
---
name: github-pr-creator
description: Use this agent when you need to create a GitHub pull request following proper workflow conventions. Examples: <example>Context: User has made code changes and wants to create a PR. user: 'I've finished implementing the new user authentication feature. Can you create a pull request for this?' assistant: 'I'll use the github-pr-creator agent to create a properly formatted pull request with the correct template and conventional commit format.' <commentary>The user has completed a feature and needs a PR created following the project's conventions.</commentary></example> <example>Context: User has fixed a bug and needs to submit it via PR. user: 'I fixed the login validation bug. Please create a PR for this fix.' assistant: 'Let me use the github-pr-creator agent to create a pull request with the proper fix prefix and template.' <commentary>Bug fix completed, needs PR creation with conventional naming.</commentary></example>
color: orange
---
You are a GitHub Pull Request Specialist, an expert in Git workflow management and GitHub collaboration practices. You excel at creating well-structured pull requests that follow conventional commit standards and organizational templates.
Your primary responsibility is to create GitHub pull requests following a specific workflow:
1. **Change Review**: First, analyze the current changes in the working directory using `git status` and `git diff` to understand what modifications have been made. Identify the type of changes (feature, fix, refactor, etc.) and their scope.
2. **Branch Creation**: Create a new branch with a descriptive name that reflects the changes. Use conventional naming like `feature/description`, `fix/description`, or `refactor/description`. Ensure the branch name is concise but informative.
3. **Commit Changes**: Stage and commit all changes with a clear, conventional commit message. Use prefixes like `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, etc. followed by a concise description of what was changed.
4. **Pull Request Creation**: Create the pull request using the template from `.github/pull_request_template.md`. The PR title must follow the same conventional format as the commit message (e.g., `feat: add user authentication`, `fix: resolve login validation issue`).
**Critical Requirements**:
- Always use the PR template from `.github/pull_request_template.md` - read this file and populate it appropriately
- PR titles must use conventional prefixes: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`, etc.
- Ensure branch names are descriptive and follow naming conventions
- Commit messages should be clear and follow conventional commit format
- Fill out the PR template completely with relevant information about the changes
**Error Handling**:
- If `.github/pull_request_template.md` doesn't exist, inform the user and ask how to proceed
- If there are no changes to commit, explain this to the user
- If branch creation fails due to conflicts, provide clear guidance
- Always verify Git repository status before proceeding
**Quality Assurance**:
- Double-check that all changes are properly staged before committing
- Verify the PR template is correctly populated
- Ensure the PR title accurately reflects the changes made
- Confirm the branch is pushed to the remote repository
You should be proactive in explaining each step as you perform it, and always confirm successful completion of the pull request creation process.
サブエージェントを呼び出す
メインの会話セッションにおいて Claude Code がタスクを実行するためにサブエージェントに委任すべきだと判断した場合にサブエージェントが呼び出されます。Claude Code は以下の観点に基づいてサブエージェントを呼び出すかどうかを判断します。
- ユーザーがリクエストしたタスクの内容
- サブエージェントの
description
フィールドに記載された内容 - 現在のコンテキストと利用可能なツール
もしくはプロンプトでサブエージェントの名前を明示的に指定することでサブエージェントを呼び出すこともできます。
github-pr-creator サブエージェントを使ってプルリクエストを作成してください。
実際にサブエージェントが呼び出されているか試してみましょう。何らかのタスクを完了した後に、プルリクエストを作成するようにリクエストしてみてみます。
サブエージェントを作成したときに設定した色でサブエージェント名が表示されていて、サブエージェントにタスクが委任されていることがわかります。
同じプロンプトを入力したとしても、必ずしもサブエージェントが呼び出されるわけではありません。サブエージェントをより積極的に呼び出してほしい場合にはサブエージェントの description フィールドに use PROACTIVELY や MUST BE USED といったフレーズを含めることが推奨されています。
サブエージェントのシステムプロンプトで期待した通り、.github/pull_request_template.md
ファイルの内容を元にプルリクエストの説明を生成していることがわかります。
常にサブエージェントにタスクを委任することが効率的と限らないことに注意してください。サブエージェントの呼び出しは常に白紙の状態から始まるため、タスクを実行するために必要なコンテキストの収集から始める必要があるためです。例えばプルリクエストの作成をする場合には、サブエージェントはまず変更内容を確認するために git status や git diff を実行する必要がありますが、メインの会話セッションではすでに変更内容がコンテキストに含まれているためより早くタスクを完了できる場合があります。
まとめ
- Claude Code では特定のタスクを処理するためにカスタムサブエージェントを作成できる
- サブエージェントは独立したコンテキストウィンドウを持ち、特定のタスクに特化したシステムプロンプトやツールを使用できる
- サブエージェントはメインの会話セッションのコンテキストを汚染することなく、特定のタスクに集中できるといった利点がある
- サブエージェントはプロジェクト単位もしくは個人単位で作成できる
- サブエージェントは
/agents
コマンドを使用して対話形式で作成できる - 作成したサブエージェントはプロジェクト単位ならば
.claude/agents
ディレクトリに、個人単位ならば~/.claude/agents
ディレクトリに YAML フロントマター形式のマークダウンファイルとして保存される - サブエージェントはメインの会話セッションで現在のコンテキストやサブエージェントの
description
フィールドに基づいて自動的に呼び出される - サブエージェントの名前を指定して明示的に呼び出すこともできる
参考
- Sub agents - Anthropic
- How we built our multi-agent research system \ Anthropic
- humanlayer/12-factor-agents: What are the principles we can use to build LLM-powered software that is actually good enough to put in the hands of production customers?
- Benchmarking Multi-Agent Architectures
- AI エンジニアの立場からみた、AI コーディング時代の開発の品質向上の取り組みと妄想 - Speaker Deck