Claude Subagent 初心者向け入門ガイド

Claude Codeにバグ修正を依頼すると、彼は意気込んでコードの読み取りを開始する—— src/auth を一通り読み、src/api を一通り読み、src/db もさらう。テストファイルさえ見逃さない。いざ手を動かそうとした時には、コンテキストウィンドウはすでに満杯になっている。そして「物忘れ」が始まる——前に読んだ重要なロジックがはっきり思い出せず、修正したコードの前後整合性が取れなくなる。

このような事態が何度か発生した後、一つのことに気づいた：すべてのタスクをメインダイアログが自ら行うべきではない。

Subagentはまさにこのために存在する。

実際には何か

最もシンプルな理解：Subagentは、具体的なタスク実行のために派遣された担当者で、独立したコンテキストウィンドウ内で動作する。

たとえ話で説明しよう。メインダイアログはプロジェクトマネージャーで、全体を管理し意思決定を行う。Subagentは具体的な作業を担当するエンジニアだ——独立して作業し、最終的な結論だけを報告する。Subagentが読み込んだ50のファイル、実行した数千行のログはすべてSubagent自身の記憶に留まり、メインダイアログを汚染しない。

この設計には双方向のメリットがある。

一つは、メインダイアログのコンテキストがノイズで埋まらないことだ。Subagentは自ら50のファイルを処理し、メインダイアログには「このモジュールはJWT認証を使用しており、検証ロジックは middleware/auth.ts にある」という一文だけが届く。

もう一つは、並列実行が可能になることだ。3つのSubagentを同時に派遣して、認証、データベース、APIをそれぞれ調査させれば、3つの作業が並行して進められ、互いに干渉しない。

初期搭載の3つ

特別な設定は不要だ。Claude Codeには最初から以下の3つが用意されている。

** Explore ** ——読み取り専用の検索エキスパート。デフォルトではHaikuモデルで実行される（安価で高速）。「このプロジェクトでXがどう実装されているか見て」と頼むと、Claudeは自動的に「大量のファイルを読み込むが書き込みはしない」タスクをこれに委任する。

** Plan ** ——実際に作業に入る前にアーキテクチャ案を作成する。計画のみで実行はしない。承認を受けてから実行する。

** General-purpose ** ——特定の目的がなく、何でもこなせる汎用モデル。

多くの人が気づいていないが、Claudeに「調査して」「理解して」と言うと、ClaudeはすでにExploreを使用していることが多い。明示的には言わないだけで。

独自のSubagentを作成する

Subagentとは、YAMLヘッダー付きのMarkdownファイルに過ぎず、特別な魔法はない。

最も簡単な方法は、Claude Code内で /agents と入力し、ガイドに従って進めることだ。手動でファイルを作成し、.claude/agents/（プロジェクトレベル）または ~/.claude/agents/（グローバルレベル）に置くこともできる。

具体例として、コードレビュー用のSubagentを挙げる：

---
name: code-reviewer
description: コードレビューの専門家。コードを書き終えたり変更した直後に自動的に使用する。
tools: Read, Grep, Glob, Bash
model: inherit
---

あなたはシニアのコードレビュアーです。呼び出された場合：
1. git diff を実行して最近の変更を確認
2. 変更されたファイルのみに焦点を当てる
3. 優先度順にフィードバック：重大な問題 → 警告 → 提案

チェックリスト：
- 命名は明確か
- 重複はないか
- エラー処理は十分か
- シークレットが露出していないか
- テストは十分か

いくつかのフィールドについて補足する。

description はファイル全体で最も重要な行である。 Claudeはこの記述に基づき、いつ自動的に委任するかを判断する。「コードアシスタント」とだけ書けば、Claudeはいつ使うべきかわからない。「コードを書き終えたり変更した直後に自動的に使用する」と書けば——トリガー条件と「自動的に」という言葉——Claudeは初めて実際に呼び出す。この行の書き方次第で、このSubagentが飾り物になるかどうかが決まる。

tools は権限のゲートである。 読み取り専用のタスクなら Read, Grep, Glob だけを付与し、Edit, Write は与えない。これは簡潔さだけでなく、Subagentが権限を超えて変更を加えるのを防ぐ安全柵でもある。

model は段階的に使い分けることができる。 探索のような安価なタスクにはHaikuを、深いレビューにはSonnetやOpusを使い、必要に応じて支払い、高価なモデルを無駄にしない。

使い方

呼び出し方法は3種類ある。それぞれ異なる場面で使用する。

自然言語で直接指示する：「code-reviewer でauthモジュールを見て」。自然だが、Claudeが別のSubagentを選択する可能性がある。

@code-reviewer で最近の変更を確認する。@で指定したものは必ず使用され、ずれることがない。

claude --agent code-reviewer 。セッション全体をこのSubagentに固定する。特定の作業だけを行いたい場合に適している。

よく使う3つのシナリオ

テスト実行やログ処理など「大量出力」を伴う操作。 npm test を実行すると数千行の出力が得られ、メインダイアログに流し込むと混乱を招く。Subagentに委任しよう：「テストスイートを実行し、失敗したテストとエラーだけを報告」——Subagentがすべてのノイズを処理し、シグナルだけを送ってくれる。

並行調査。 「3つの独立したSubagentを使用して、認証、データベース、APIモジュールを同時に調査」——逐次的な調査より明らかに速く、3つのモジュールの詳細が互いに混ざり合うこともない。

連鎖的なワークフロー。 「code-reviewer でパフォーマンスの問題を見つけ、次にoptimizer でそれらを修正」。前のSubagentの出力を次のSubagentの入力として使用でき、結論を手動で引き継ぐ必要がない。

SubagentとSkillの混同を避ける

这两个概念はClaude Code内で最も混同されやすい。以下にまとめた：

	Skill	Subagent
本質	再利用可能な指示パッケージ	独立したコンテキストを持つワーカー
実行環境	メインダイアログのコンテキスト内	独自の独立したコンテキストウィンドウ
使用場面	メインダイアログ内で一連のプロセスを再利用したい場合	コンテキストを分離し、並列実行や権限制御を行いたい場合

覚え方：分離が必要ならSubagent、再利用が必要ならSkill。

陥りやすい2つの落とし穴

SubagentはさらにSubagentを派遣できない。 再帰的な呼び出しは不可能だ。ネストされた委任が必要な場合は、プロセスをSkillとして書くか、メインダイアログから手動で複数のSubagentを連鎖させる。

description が抽象的すぎるのと等しい。 これは初心者が最もよく犯すミスだ。「general purpose helper」のような記述では、Claudeが自発的に呼び出すことは永遠にない——いつ登場させるべきか理解できないからだ。具体的であればあるほど良い。例えば「PR提出前に自動的にコードをレビューし、自動的に使用する」のように、トリガーとなるシナリオを直接示す。

応用：Subagentに記憶を持たせる

YAMLヘッダーに以下の行を追加する：

memory:
  scope: project

これにより、Subagentは毎回発見したプロジェクトのパターン、遭遇したバグ、アーキテクチャの約束事を記録する。次回呼び出された時には、Subagentはすでにプロジェクトを「知っている」状態になる。

本文中に以下の一文を追加する：

タスク完了後、学んだことを記憶に保存してください。

しばらく運用すると、このSubagentはプロジェクト内の「ベテラン社員」に変わる——レビューの品質が向上する。なぜなら、過去に問題が発生した場所を把握しているからだ。

まとめ

冒頭のコンテキスト不足の話に戻ろう。以降、このような状況では「コード読み取り」ステップをExploreに委任し、メインダイアログには結論だけが届く：「問題は middleware/auth.ts にあり、トークン解析時に空のヘッダーが処理されていない」。あとは適切な箇所を修正するだけだ。

Subagentの核心的価値は、主に3つの点にある：メインダイアログのコンテキストを保護し、並列実行を可能にし、権限を制御する。

最初から複雑に考えすぎる必要はない。最もシンプルなコードレビューSubagentから始め、コミットするたびに自動的に実行させてみよう。慣れれば、自然と次のアイデアが浮かぶはずだ——「この作業も担当者に任せるのが良さそうだ」と。