Claude Codeサブエージェントの作り方｜専用AIを定義

Claude Codeのサブエージェントは、独立したコンテキストウィンドウを持つ別インスタンスとして働き、レビューやテスト、調査のような重くてノイズの多い作業をメイン会話から切り離せます。
毎回同じ指示を打ち直す手間や、長い作業でコンテキストが埋まっていく不満をまとめて解消し、結果だけを受け取れるのが最初の魅力です。
設定は .claude 配下の1ファイルで完結し、必須なのは name と description の2つだけなので、思ったより敷居は高くありません。
しかも description は説明文ではなく自動委譲の発火条件として働くため、職種型の名前と合わせて整えると、code-reviewer のような役割がちゃんと呼ばれるエージェントになります。

サブエージェントとは何か｜通常のチャットとの違い

サブエージェントは、独立したシステムプロンプト、コンテキストウィンドウ、ツールアクセスを持つ別インスタンスです。
Claude Code では、特定の作業を委譲するとその中だけで処理が進み、完了時には最終的な要約や推奨だけが親に返ります。
だからこそ、メインの会話を汚さずに重い仕事を切り出せるのです。

サブエージェントの正体は『隔離された別インスタンス』

サブエージェントは、会話の続きをそのまま引き継ぐ相手ではありません。
毎回まっさらな専門家として起動し、自分のシステムプロンプトと作業に必要な最小限の環境だけを受け取って動きます。
既読ファイルや過去の会話が見えないぶん、役割を一つに絞りやすく、レビュー役、探索役、テスト役のような職能を明確に分けられるわけです。

この性質を理解しないままだと、最初は話が噛み合わないことがあります。
続きを覚えていてほしい、と期待すると外れます。
むしろ、文脈を背負わないからこそ、毎回同じ品質で同じ仕事だけを返す、と捉えたほうが使いどころが見えてきます。

なぜメインのコンテキストを節約できるのか

最大の利点は、結果だけが戻ることです。
巨大なリポジトリの調査やレビュー、テストのようにログが膨れやすい作業をメイン会話で回すと、途中経過だけでコンテキストが埋まり、後半ほど指示が通りにくくなります。
実際、探索をそのまま会話に流し込んだあとに後半の指示が鈍った経験から、調査だけをサブエージェントに隔離する判断はかなり自然でした。

サブエージェントは最終出力だけを返すため、親の会話には大量の途中ログが流れ込みません。
つまり、メイン側のコンテキストウィンドウを節約しながら、必要な探索や検証だけを並行して進められます。
重い処理ほどこの分離が効くでしょう。

CLAUDE.md・スラッシュコマンドとの使い分け

CLAUDE.md は常に読まれる前提知識で、プロジェクトの基本方針を共有する場所です。
スラッシュコマンドは、自分でタイプして起動する定型手順になります。
対してサブエージェントは、コンテキストを隔離して別の頭に任せたいときの選択肢だと整理すると迷いません。

使い分けの軸は、会話の文脈をそのまま持ち越したいかどうかです。
細かな前後関係を引き継いで続けるなら通常のチャットやスラッシュコマンドが素直ですし、要約か推奨だけ戻ってくれば足りる自己完結した重いタスクならサブエージェントが向いています。
逆に、同じ会話の空気を共有したまま進めたい作業には向きません。

作る前の準備｜保存場所とスコープを決める

Claude Codeのサブエージェントは、まず置き場所を決めるだけで運用の迷いが大きく減ります。
プロジェクト専用ならリポジトリ直下の .claude/agents/、全プロジェクトで使い回すなら ~/.claude/agents/ と分けることで、汎用版と案件別の調整版を自然に使い分けられるからです。
最初の一歩は「どこに置くか」を固めることだと言えるでしょう。

プロジェクトスコープとユーザースコープ

~/.claude/agents/ は、どのリポジトリでも共通に使いたい定義を置く場所です。
たとえば最初はここに汎用のレビュー役を置いておき、特定案件だけはプロジェクト側の .claude/agents/ に同名で上書きする、という運用ができます。
ひとつの定義を広く再利用しつつ、案件ごとに振る舞いを変えられるので、毎回ゼロから作り直すよりずっと扱いやすいです。

同名時の優先順位とチーム共有

同じ名前のサブエージェントが両方のスコープにある場合は、プロジェクト側が優先されます。
この挙動があるため、ユーザー共通の汎用版を残したまま、特定リポジトリでは独自の基準や文体に差し替える運用が成立します。
実際に全プロジェクト共通の ~/.claude/agents/ にまず汎用エージェントを置き、案件ごとに .claude/agents/ へ同名で上書きすると、設定の切り替えがかなり素直になります。

チームで共有したいなら、基本はプロジェクトスコープに置いて git 管理する形です。
.claude/agents/ 配下のファイルをコミットしておけば、クローンした全員が同じ専用エージェントを使えるようになり、手元ごとのレビュー基準のばらつきが消えます。
共有ルールをファイルに閉じ込められるので、口頭で「この案件ではこう」と伝える回数も減るはずです。

1ファイル=1エージェントの基本構造

定義ファイルは、YAMLフロントマターと Markdown 本文からなる1ファイルです。
先頭を --- で囲んだブロックに name や description を置き、その下の本文に役割の指示を書けば、そのままサブエージェントの定義になります。
ビルド手順も SDK もレジストリも不要で、.md を置くだけで認識される手軽さが強みでしょう。

原則は 1 ファイル = 1 エージェントです。
code-reviewer.md、test-runner.md のように役割名がそのまま分かるファイル名にしておくと、後から見返したときに迷いません。
本文が長くなっても、役割単位で切り分けておけば保守しやすく、呼び出し時の責任範囲も明確になります。
}`

/agentsコマンドで対話的に作る

/agents は、ファイルを手書きする前に最短で骨格を作れる入口です。
Claude Code のセッションで /agents と打つと、サブエージェントをプロジェクトとユーザーのどちらのスコープに置くかを選ぶところから対話的に進められます。
まず保存先を決め、次に Claude に草案を組ませる流れにすると、迷いどころが一気に減るのです。

/agentsを起動して保存先を選ぶ

/agents を開くと、最初にプロジェクト用かユーザー用かを選べます。
ここで分けておくと、いまの作業だけに閉じた設定なのか、別プロジェクトでも使い回す設定なのかが明確になり、あとから見返したときの意図もぶれません。
サブエージェントは思いつきで増やすより、置き場所から決めたほうが整理しやすいです。
作成の起点が同じでも、運用のしやすさはかなり変わります。

Claudeに設定の草案を作らせる

保存先を選んだら、『Claudeに手伝ってもらって作る』を選びます。
すると、いま開いているプロジェクトの文脈を踏まえて、役割の要約からフロントマター、システムプロンプトの草案までをまとめて出してくれるため、ゼロから組むより時間を短くできます。
実際、プロジェクトの構成を踏まえたレビュー観点まで入った草案が出てきて、そのまま使える下地の厚さに驚かされます。
ただし、そこで終わりにはしません。
生成物の tools が広すぎることがあるので、後からホワイトリストに絞り直し、model と description も意図に合わせて詰めます。
土台は Claude に作らせ、発火条件と権限だけ人間が締める。
この分担がいちばん回しやすいでしょう。

作成後の一覧・編集・削除

/agents は作成専用のコマンドではありません。
既存サブエージェントの一覧表示、編集、削除の入口にもなるので、今のプロジェクトでどんなエージェントが有効かを確認したいときにもまず開く場所になります。
増やす、直す、消すを同じ導線で扱えると、設定の棚卸しがしやすい。
運用の途中で役割が重なったり、権限が広すぎたりしても、その場で整えられます。
対話作成に慣れてきたら、/agents で骨格を作ってからエディタで .md を直接直す流れに移るといいです。
最初のドラフトは Claude に任せ、細部は手で仕上げる。
ハイブリッドにすると、速さと精度の両方を取りやすくなります。
おすすめです。

.claude/agentsにファイルを手書きで定義する

.claude/agents のファイルを手書きで定義するなら、まずは YAML フロントマターを最小限にして動作確認するのがいちばん安全です。
必須なのは name と description の2つだけで、ここで雛形は完成します。
本文はその下に続く Markdown で、そのままサブエージェントの振る舞いを決める設計です。

name・descriptionだけの最小構成から始める

最初は name と description だけを書き、実際に呼び出せるかを確かめるのが近道です。
name は @ で参照するときの識別子になり、description は「どんなときにこのエージェントを使うか」を示すため、自動委譲の判断材料になります。
フロントマターをいきなり厚くしない。
ここが安定運用の出発点です。

最小構成の .md は、先頭の --- から --- までに設定を置き、その下の本文で役割を説明します。
たとえば次の形なら、余計な要素を入れずにまず動かせます。

name: section-writer
description: セクション本文を下書きする

あなたは記事の本文を整えるエージェントです。指示された見出しに対して、指定された条件に沿って散文で書いてください。

実際にはこの2行から始めて、動くことを確認してから tools や model を足していく進め方が扱いやすいです。
最初から全部を詰め込むより、どこで挙動が変わったかを追えるからです。

modelで実行モデルとコストを決める

model フィールドでは、haiku・sonnet・opus のいずれか、または inherit を指定します。
軽い定型作業なら haiku、判断の多い役割なら opus、親セッションと同じ条件で走らせたいなら inherit という使い分けになります。
役割ごとにモデルを分けると、精度とコストのバランスを取りやすいのです。

設定は単純ですが、効き方は大きいです。
たとえば要約や整形中心のエージェントは haiku に寄せ、複数条件を見比べて文章を組み立てる役割は sonnet 以上に寄せる、といった整理ができます。
親と揃えたい場面では inherit を選べばよく、ファイル単体で迷わず読める記述になります。

本文＝システムプロンプトに役割を書き込む

2つ目の --- 以降に書く Markdown 本文は、そのままサブエージェントのシステムプロンプトになります。
つまり、ここに「あなたは何者か」「どんな順序で考えるか」「どの形式で返すか」を具体的に書くほど、出力はぶれにくくなるわけです。
抽象的な説明より、役割・手順・出力形式を分けて明記したほうが強い。

出力フォーマットを箇条書きで本文に書いたとき、返ってくる成果物の形が目に見えて安定しました。
段落で自由に書かせるより、先に形式を固定したほうが、後工程での差し戻しが減ります。
本文は飾りではない。
挙動そのものです。

tools を足す場合も、ここでの設計とつながっています。
Read・Grep・Glob のように使える道具を絞れば、役割の境界がはっきりし、誤用も抑えやすくなります。
最小構成で立ち上げ、model と tools を一つずつ重ねていく。
この順番が結局いちばんおすすめです。

自動委譲を効かせるdescriptionの書き方

descriptionは機能説明ではなく、Claude が委譲先を決めるための発火条件として書くべきです。
どんな依頼文が来たら起動するのか、どのタイミングで手を伸ばすのかを具体化すると、呼ばれる場面が一気に安定します。
役割を曖昧に広げるほど誤爆しやすくなるので、ひとつの仕事にひとつの条件を与える発想が要になります。

descriptionは『発火条件』として書く

実際、description を機能説明のまま置いていた時期は、エージェントがほとんど自動で呼ばれませんでした。
ところが「コード変更の直後にレビューする」といった発火条件へ書き換えた途端、狙った場面で起動するようになったのです。
Claude は説明文を眺めているのではなく、依頼文と条件を突き合わせている。
だから、何をするかよりも、どんな言葉や状況で使うかを書くほうが効きます。

さらに効くのが、「use proactively」「コードを書いた直後に使う」のような促し文言です。
これが入るだけで、指示がなくても自動で委譲されやすくなります。
迷ったら、機能の紹介文を削って、起動のトリガーを一行足しましょう。

職種型の名前で確実にルーティングする

名前も委譲精度を左右します。
test-runner、pr-reviewer、repo-explorer、docs-researcher のように職種・役割が一目で分かる名前は、frontend-engineer のような広い名前より安定します。
汎用名はあらゆる依頼に見えてしまうため、別の場面でも誤って呼ばれやすい。
結果として、どこでも中途半端な働き方になりがちです。

命名を変えるだけで、ルーティングのノイズは減ります。
実務では、汎用的なエージェントが他の依頼にも混線して呼ばれたため、職種型の具体名に変えて落ち着いたケースがあるはずです。
1つの仕事に1つの名前、これが正解です。

@メンションで明示的に呼ぶ

自動委譲に任せきりにせず、@に続けてタイプアヘッドから選べば明示的に呼び出せます。
ファイルを@で参照するのと同じ操作感なので、「今はこのエージェントに任せたい」という場面では手動指名が素直です。
自動で拾わせる設計と、必要なときだけ確実に指定する操作は、対立せずに併用できます。

おすすめは、普段は description で自動委譲を効かせ、要所だけ @ メンションで固定する運用です。
起動条件が明快なら自動で流れ、急ぐ場面では手で呼ぶ。
そうやって使い分けると、エージェントの役割がぶれません。

用途別のサブエージェント設計例

用途別にサブエージェントを分けるときは、まず権限を絞り、そのうえで役割を1つに固定すると運用が安定します。
toolsを省略した場合は親スレッドのツールを継承しますが、MCP連携で増えたものまでそのまま入るため、レビュー専用の相手に書き込み権限が混ざると事故の入口になります。
必要なものだけをホワイトリストで指定する設計が安全で、後から追加したツールが意図せず紛れ込む余地も減ります。

code-reviewer：読み取り限定＋チェックリスト

code-reviewer は、読み取り系ツールだけに閉じる設計と相性がよいです。
Read・Grep のような確認専用の道具に限定し、システムプロンプトには観点の順序と出力の型を明記しておくと、毎回同じ基準で抜けなく返ってきます。
変更直後に使う前提を description に書いておけば、コードを書くたびにレビューを走らせる運用にもつながるでしょう。
実際、この形にしてからはレビュー指示を毎回貼り付ける手間が消え、観点のブレも減りました。
やることが増えないのに品質だけ揃うのが利点です。

test-runner：失敗テストの修正を任せる

test-runner は、落ちているテストを直す作業を丸ごと渡したいときに向いています。
ここでもツールは最小限に絞り、テスト実行とファイル編集に必要なものだけを与えるのが基本です。
役割文も「テストを実行し、落ちている原因を特定して修正する」と具体的に固定すると、調査・修正・再実行の流れがぶれません。
メイン会話を止めず、裏で失敗を片づけてくれるので、開発の流れを切らしにくいのも強みである。
レビュー役と違って、この役割は手を動かすことに意味があります。

repo-explorer：重い調査をコンテキストから隔離

repo-explorer は、エントリポイントの特定やデータフロー追跡、コーディング規約の把握のような重い探索を隔離するのに最適です。
こうした調査はログ量が膨らみやすく、メイン会話に生ログが流れ込むと、その後の判断に使えるコンテキストがすぐ圧迫されます。
調査の生ログをサブエージェント側に閉じ込め、返すのは要約と要点だけにすると、メイン側は意思決定に集中できます。
大規模調査を任せたあとに会話が軽く保てるのは、この分離の効き目です。
ポイントは、探索そのものを外に出すこと。

うまく動かないときの対処と制約

サブエージェントがうまく動かない原因は、たいてい設定と前提の渡し方にあります。
まず自動で呼ばれない問題はdescriptionの書きぶりを見直し、何をする道具なのかではなく、どんな状況で使うのかを具体化しましょう。
情報が伝わらない場合は、相手が毎回まっさらな状態で始まる前提を置き、必要な材料を最初から全部渡す設計に変えるのが近道です。

自動委譲されないときの見直し順

『作ったのに自動で呼ばれない』なら、最初に見るべきはdescriptionです。
機能説明だけが並んでいて発火条件が書かれていないと、モデルは使いどころを判断しにくいままになります。
どんな状況で、どんな言葉が出たら呼ぶのかを明記し、必要なら use proactively のような促しも入れましょう。
名前が広すぎる場合は、抽象名より職種型の具体名に変えたほうが動きやすい。
ここを直すだけで、呼ばれ方は変わります。

情報が伝わらない（コンテキスト非共有）への対処

『指示が通らない』『的外れな成果が返る』ときは、コンテキスト非共有を疑うべきです。
サブエージェントは会話履歴も既読ファイルも呼び出し済みスキルも引き継がず、毎回ゼロから始まる。
前提を知らない新人に渡すつもりで、判断材料をその都度書き込む発想が要ります。
実際に『さっき読んだ設定ファイルを直して』と頼んでも通らず、ファイルパスとエラー全文をプロンプトに直接書いたら一発で直ったことがあり、伝達経路はプロンプト文字列しかないと腹落ちしました。
必要なファイルパス、エラーメッセージ、これまでの判断は、その文面の中に明示してこそ届くのです。

入れ子不可・トークン消費という構造的な制約

サブエージェントはさらに別のサブエージェントを生成できず、構造は単層に固定されています。
複数の役割を連携させたいなら、親が順番に呼び出してつなぐしかない。
ここを誤ると、設計が複雑になるほど見通しが悪くなります。
加えて、各サブエージェントは独自のコンテキストウィンドウを持ち、独立してトークンを消費します。
便利だからと多数を並列で回した結果、想定以上に利用枠が膨らみ、重い作業だけに絞り直したことがあります。
隔離の価値が本当にある場面にだけ使う。
これが現実的です。
複数を動かすなら、まず数を増やす前に役割を減らしましょう。