雑に理解する Claude Code サブエージェント
Claude Code に先日追加された「サブエージェント」という機能を試し、雰囲気で理解した話をここに記録します。
サブエージェントは、良い感じのタイミングで勝手に現れて仕事を手伝ってくれる専門家のオジサンです。（「オジサン」か「小人」かで迷いましたが、オジサンの方が高い専門性を発揮しそうなのでオジサンでいきます。）
サブエージェントとは、実態
サブエージェントはメインのエージェントから使用される、子エージェントです。セッションとしては同じ場所で仕事をしそうな感じに出てきますが、メインからは切り離されたプロセスとして働く、ツールの一種というイメージです。
ドキュメントによれば、サブエージェントは特定の目的を持ったエキスパートで、こんな特徴を持っているらしいです :
- 専門的な能力を持っている、何かの係の人である
- メインのエージェントとはコンテキストが別である
- 振る舞いや使用ツールを独自にカスタマイズできる
ある目的に特化するようにチューニングされていて、その目的でしか使われないので高いパフォーマンスを発揮します。そしてメインのコンテキストを汚染しないので、メインエージェントがコンテキストの肥大化でアホの子になるのを緩和してくれます。あくまで緩和です。どのみちアホの子になる未来からは逃れられません。
どこにどのように定義されるか
サブエージェントは、スラッシュカスタムコマンドなど他の機能と同様に .claude/agents ディレクトリ内に Markdown 文書で定義されます。また、サブエージェント作成用の /agents というサブコマンドが用意されているのではじめはこれで作ってみて、あとからカスタマイズするやり方が推奨されていました。
/agents コマンドでは、「これがどんなオジサンで、どんな時に使ってほしいか」を伝えれば、あとはよしなに定義してくれます。例示は英語ですが、日本語でお願いしてもちゃんと理解してくれます。（ただし、出来上がる Markdown 文書は英語で出力されます。）
例えば、「フロントエンドコードの実装が完了した後やPR作成前に、パフォーマンスとUXの観点から品質チェックを行うシニアエンジニア」のような。
細かいチューニングは Markdown 文書を直接編集するか、AIに編集してもらいます。
どのタイミングで呼び出されるか
Claude Code は適切なタイミングで適切なサブエージェントを選択して自動的に呼び出してくれます。例えばユーザーが「コードレビューをおねがい」と言ったらコードレビューが得意なサブエージェントを呼び出して仕事をしてもらいます。
「適切なタイミングって何時よ？」という疑問ですが、Claude Code がサブエージェントの description を見て「このオジサンは何が得意なのか」「このオジサンはどんな場面で呼んで欲しいと言っているか」を把握して、ユーザーからそれを求められたタイミングが、「適切なタイミング」となるようです。
ということは description 自体がちゃんと整備されていないといけません。「こういう場面では 必ず このオジサンを使ってほしい」という強い要望がある場合は、description に use PROACTIVELY だったり MUST BE USED といった強めのキーワードを埋め込んでおくと良いそうです。
それをやってても使ってくれないこともあります。そんな時は CLAUDE.md で明記しておくと、ようやく使ってくれるようになったので、試してみると良いかもしれません。
明示的に呼び出すこともできる
Claude Code に自動的に使ってもらう他に、プロンプトで「 code-reviewer を使ってください」とバイネームでお願いすることもできます。指名料はかかりません。でも勝手にやってくれるところが魅力のひとつではある気がするので、出来るだけ自動で呼び出されるようにチューニングしたいですね。
抱いていた誤解
誤解１：単純に処理が速くなるわけではない
自分ははじめ、専任のサブエージェントに大きなデータ処理をさせたら速いのでは？と考えましたがそういう話ではないようです。
背景として、Atlassian MCP を使って大きな構造データを取得させると、そのデータの読み込み・解釈が不得意なエージェントが長考状態に陥ってしまうという問題がありました。その問題をサブエージェントが解決してくれるのかと期待して Atlassian MCP 専任のサブエージェントを作成して試してみたところ、かえって時間がかかってしまうという結果となりました。
- メインエージェントで直接処理 : 3分30秒
- サブエージェントで処理 : 10分超
Claude Code に聞いてみたところ、
- サブエージェントの起動とコンテキスト構築コスト
- メインエージェントとサブエージェント間のコミュニケーションによる遅延
このあたりがオーバーヘッドになっているのではないかと推論していました。そもそもコンテキストが分離されているだけで性能そのものが上がったり、不得意なものが得意になったわけではなかったのでした。
誤解２：並列処理はするが非同期処理はできない
サブエージェントは他のツールと同様に、同期で処理されます。サブエージェントから最終的なレスポンスが返されるまでは他の指示をすることはできません。なので、「このオジサンにこれやってもらってる間に他のオジサンにこれやってもらう」という使い方はできないです。それをやりたければ別の Claude Code を起動してセッションを分けます。
しかし Claude Code にサブエージェントについて解説してもらっている時に「並列処理ができます」と言っていたのが気になったので、もう少し詳しく教えてもらいました。どうやら Claude Code はユーザーからのひとつのメッセージから複数のサブエージェントを並列起動できるということを言いたかったそうで。その場合は、並列で処理されている全てのツールが完了しないと次の作業には移れません。結果待ちは同期です。
どんなサブエージェントがあると便利か
Claude Code に「どんなサブエージェントが有用か」を聞いてみたところ、10点ほどの候補をあげてもらったうえで、次の2つを推してくれました。
1. code-archaeology-agent
レガシーコードの考古学的調査
- コードの歴史的経緯を追跡（git履歴、コメント分析）
- 削除可能なデッドコードの特定
- 暗黙の仕様やビジネスルールの発掘
- リファクタリングの影響範囲分析
2. test-generator-agent
コードを読んで適切なテストを自動生成
- エッジケースの自動発見
- モックの自動生成
- 既存テストパターンの学習と適用
- カバレッジギャップの特定と改善提案
サブエージェントの得意・不得意
サブエージェントは、コンテキストを大きく消費するような複雑で大きな作業や、特定領域の専門知識を要するような調査をサブエージェントに切り出すと高い効果が期待できるそうです。
逆に、サブオジサンの真価を発揮できなさそうなのは次のようなケースですね。
- 小さく単純な処理
- 明確な手順があるタスク
このあたりはカスタムスラッシュコマンドが得意な領域でしょう。
おわりに
今後は「うちのチームに必要なオジサン」を育てていきましょう。記事を書くオジサンも良いかもしれない。
Discussion