【Claude Code】カスタムエージェントの作り方と使い方

Claude Codeでカスタムエージェントを作りたい！
カスタムエージェントの定義ファイルはどこに置くの？

Claude Codeを使っていると、同じ指示を毎回一から打ち込んでいる作業が出てきませんか。

コードレビュー、ドキュメント生成、情報収集……繰り返し系のタスクこそ、Claude Codeのカスタムエージェントに任せると一気にラクになります。

カスタムエージェントを使えば、専用の「AIワーカー」をMarkdownファイル1枚で定義できます。
一度定義してしまえば、以降は自動で委譲されるか、@エージェント名で即呼び出せます。

私もはじめは「なんか難しそう」と敬遠していたのですが、実際に作ってみると構造はシンプルで、むしろ最初に触っておけばよかったと感じました。
この記事では、ゼロから7ステップで作る方法と、実際の活用例を紹介します。

Claude Codeのカスタムエージェントとは

カスタムエージェントを理解するには、まず「なぜメイン会話だけでは限界が来るのか」を知っておくと腑に落ちます。
仕組みの概要と、どんな場面で使うべきかを整理します。

ここでは、以下の内容について詳しく解説します。

コンテキストが汚れるとどうなるか

Claude Codeでタスクをこなしていると、メイン会話のコンテキストウィンドウがどんどん埋まっていきます。

調査結果、ファイルの読み込み内容、ログ出力……これらが会話に積み重なると、以降の指示への応答精度が下がる原因になります。

サブエージェントはこの問題を解消するための仕組みです。独自のコンテキストウィンドウでタスクを実行し、メイン会話には結果の要約だけを返します。

重い処理をサブエージェントに任せることで、メイン会話を常にクリーンな状態に保てます。

Claude Codeには組み込みのサブエージェント（Explore・Plan・general-purposeなど）がありますが、カスタムエージェントを使えば自分専用の役割を持つエージェントを追加定義できます。

カスタムエージェントを作るべき場面

すべての作業にカスタムエージェントが必要なわけではありません。
「このタスク、毎回同じ指示を書いているな」と感じたとき、それが作成を検討するサインです。

逆に、一度きりのアドホックなタスクや複雑な判断が必要な作業は、メイン会話で直接やるほうがシンプルです。
「再利用するかどうか」が判断の分岐点です。

Claude Codeでカスタムエージェントを作る7ステップ

実際の作成手順を、ステップごとに丁寧に見ていきます。
「ファイルを置くだけ」というのは本当で、構造自体はシンプルです。ただ、ハマりやすいポイントもあるので先回りして解説します。

ここでは、以下の内容について詳しく解説します。

【ステップ1】Proプランでの利用環境を確認する

Claude Codeのカスタムエージェント機能を使うには、最低でもProプランへの加入が必要です。
無料プランではClaude Codeそのものが利用できません。

Proプランに加入してClaude Codeをインストール済みであれば、次のステップにすぐ進めます。

【ステップ2】.claude/agents/ディレクトリを用意する

カスタムエージェントの定義ファイルを置く場所が .claude/agents/ディレクトリです。
スコープによって2種類の置き場所があります。

「自分だけが使うコードレビューエージェント」はユーザーレベル、「チームで共有するドキュメント生成エージェント」はプロジェクトレベルが向いています。

プロジェクト直下に作成する場合は以下のコマンドを実行します。

mkdir -p .claude/agents

【ステップ3】エージェント定義のMarkdownファイルを作成する

ディレクトリができたら、その中にMarkdownファイルを1つ作ります。
ファイル名がそのままエージェントのスラッグになるため、機能がわかる英数字ケバブケースにするのが慣習です。

touch .claude/agents/code-reviewer.md

Claude Code内で /agents コマンドを使えばGUIでも作成できます。
ウィザード形式で名前・説明・システムプロンプトを生成してくれるので、はじめての場合はこちらが入りやすいです。

ファイルの基本構造は「フロントマター（設定）＋本文（システムプロンプト）」の2ブロックです。

【ステップ4】nameフィールドでエージェントに名前をつける

フロントマターの最初に書くのが name フィールドです。
この名前はUIの表示と、@参照で呼び出すときの識別子になります。

---
name: code-reviewer
---

命名のコツは「何をするエージェントか」がひと目でわかること。
agent1 や mybot のような抽象的な名前にすると、後で何が何かわからなくなります。

【ステップ5】descriptionで自動委譲の精度を上げる

カスタムエージェントを作るうえで、最も重要なフィールドが description です。

Claude Codeはこの description の内容を読んで「このタスクはこのエージェントに任せよう」と判断します。
ここが曖昧だと、自動委譲されずにメイン会話でそのまま処理されてしまいます。

私も最初はこんな感じで書いていました。

description: コードをレビューする

これだと全然委譲されませんでした。
「いつ・どんなタスクのときに使うのか」を具体的に書いて初めて機能します。

description: Use this agent when reviewing Pull Requests, checking code quality, identifying bugs or security issues, or providing improvement suggestions for existing code. This agent reads code only and does not execute or modify files.

【ステップ6】システムプロンプトでエージェントの役割を詳細に指示する

フロントマターの --- 以降に書いた本文が、そのままそのエージェントのシステムプロンプトになります。

---
name: code-reviewer
description: Use this agent when reviewing Pull Requests, checking code quality...
tools:
  - Read
  - Grep
---

あなたはシニアエンジニアの視点でコードレビューを行う専門エージェントです。

レビュー時のルール：
- バグ・セキュリティリスク・パフォーマンス問題を優先して指摘する
- 指摘は具体的な改善案とセットで伝える
- 変更の意図を理解したうえで、過剰な指摘を避ける
- 出力はMarkdown形式で、重要度ごとに分類する（🔴 critical / 🟡 warning / 🔵 suggestion）

設計のポイントは「1エージェント1責務」です。
複数の役割を詰め込むと、どの指示も中途半端になります。
コードレビューならコードレビューだけ、ドキュメント生成ならドキュメントだけに絞るのが、品質を安定させるコツです。

【ステップ7】@エージェント名で呼び出して動作確認する

定義ファイルを保存したら、Claude Codeで実際に呼び出してみます。
@エージェント名を使えば明示的に指定できます。

@code-reviewer このPRのコードをレビューしてください

うまく動かない場合は、まず description を見直してください。
「このタスクは〜するときに使う」という条件をもっと具体的に書くと改善されることがほとんどです。

自動委譲（Claude Codeが判断して委譲）させたい場合は、descriptionを調整しながら繰り返しテストするのが近道です。

Claude Codeのカスタムエージェントのおすすめ設定項目

フロントマターで使えるフィールドは name と description だけではありません。
ここでは実際によく使う設定項目を整理します。

ここでは、以下の内容について詳しく解説します。

必須フィールドはnameとdescriptionの2つ

カスタムエージェントが最低限動くために必要なのは name と description の2つだけです。

特に description の質が、そのエージェントが使い物になるかを左右します。
「誰かに仕事を依頼するときの仕事記述書」のつもりで書くと精度が上がります。

任意フィールドでツールとモデルを最適化する

必須フィールドだけでも動きますが、任意フィールドを加えることでエージェントの精度・安全性・コストを最適化できます。

コスト管理の観点では model フィールドが特に効果的です。
パターン処理や情報収集など、深い推論が要らないタスクはHaikuに任せると費用をかなり抑えられます。

tools:
  - Read
  - Grep

Claude Codeでカスタムエージェントを活用する3つの場面

定義の仕方がわかったら、実際にどんな場面で使うかを見ていきます。
私が実際に使っている3つのエージェントを例に紹介します。

ここでは、以下の内容について詳しく解説します。

コードレビュー専用エージェント

コードレビューは「同じ観点を毎回適用する」という意味で、カスタムエージェントと相性が抜群です。

---
name: code-reviewer
description: Use this agent when reviewing Pull Requests, checking code quality, identifying bugs or security issues, or providing improvement suggestions for existing code.
tools:
  - Read
  - Grep
---

あなたはシニアエンジニアの視点でコードレビューを行う専門エージェントです。
指摘は重要度（🔴 critical / 🟡 warning / 🔵 suggestion）を分類してMarkdown形式で出力してください。
ファイルの読み取りのみ行い、変更・実行は一切しません。

ReadとGrepだけに絞ることで、レビュー中に誤ってファイルが書き換わるリスクがゼロになります。
「最小権限の原則」の最もシンプルな適用例です。

ドキュメント生成専用エージェント

READMEやAPIドキュメントの更新は、コードを読んでパターンに変換するだけの作業です。
推論深度が低いのでHaikuが向いていて、コストを大きく抑えられます。

---
name: doc-writer
description: Use this agent to generate or update README files, API documentation, inline code comments, or any technical documentation based on the existing codebase.
model: claude-haiku-4-5-20251001
tools:
  - Read
  - Grep
  - Write
---

コードを読み取ってドキュメントを生成・更新するエージェントです。
既存のコードの構造・目的・引数・戻り値を正確に反映したドキュメントを作成します。
推測で書かず、コードから読み取れる情報だけを記述します。

Writeは許可していますが、Bashは除外しています。
「書けるけど実行はしない」という線引きが、ドキュメント生成エージェントには適切です。

リサーチ専用エージェント

情報収集タスクをメイン会話でやると、大量のログがコンテキストに溜まります。
WebSearch・WebFetchだけ許可したリサーチ専用エージェントに任せることで、メイン会話のコンテキストをクリーンに保ちながら情報収集ができます。

---
name: web-researcher
description: Use this agent when you need to search the web, gather information about a topic, research competitors, or collect data from external sources.
tools:
  - WebSearch
  - WebFetch
---

Webから情報を収集するリサーチ専用エージェントです。
収集した情報は必ずソースURLとともにMarkdown形式でまとめてください。
情報の確認に必要な最小限のURL巡回のみ行い、不要なページは閲覧しません。

「このエージェントはWebしか触れない」と制限することで、ファイルシステムへの意図しないアクセスを防げます。
サブエージェントへの権限設計は、最初から最小限に絞っておくほうが後々安心です。

Claude Codeのサブエージェント機能全般については Claude Codeサブエージェントの活用法と注意点 でも詳しく解説しています。

カスタムエージェントに関するよくある質問

Q：カスタムエージェントとSkills（スラッシュコマンド）の違いは何ですか？

A：Skillsは「Claude Codeに覚えさせるコマンドのテンプレート」、カスタムエージェントは「独立したコンテキストで動く専用AIワーカー」です。
Skillsはメイン会話内で実行されますが、カスタムエージェントは独自のコンテキストウィンドウで動くため、コンテキストの分離が必要なタスクにはカスタムエージェントが向いています。

Q：カスタムエージェントの料金はどうなりますか？

A：Proプラン内の利用であれば、カスタムエージェントを使っても追加料金は発生しません。
ただし、modelフィールドにSonnet/Opusを指定したエージェントは消費量が多くなります。軽量処理はHaikuを指定するとProプランの使用量を節約できます。

Q：Claudeが自動でエージェントに委譲してくれない場合はどうすればいいですか？

A：ほぼ確実に description の問題です。「いつ・どんなタスクのときに使うのか」を英語でより具体的に書き直してみてください。
それでも改善しない場合は、@エージェント名で明示的に呼び出す方法で運用するのが現実的です。

まとめ

Claude Codeのカスタムエージェントは、Markdownファイルを1枚書くだけで始められるシンプルな仕組みです。

難しく見えますが、実際にやってみると「ファイルを置くだけ」という感覚がよくわかります。
最初のハードルは description の書き方だけで、ここさえ押さえれば自動委譲もスムーズに動き出します。

あなたの作業の中で「これ毎回同じことやってるな」と感じている繰り返し作業はありますか。
それがカスタムエージェントの出番かもしれません。

Claude Codeのhooks機能については Claude Code hooksの使い方 も、Git連携については Claude CodeのGit連携方法 もあわせて読んでみてください。