独立した注意の窓としてのサブエージェント

1. サブエージェントとは何か、なぜ使うのか

サブエージェントとは、Claude Codeがタスクを渡す専門のアシスタントです。自分専用のコンテキストウィンドウで作業し、あなたのセッションには短いサマリーを返します。ファイルの読み取り、検索、ツールの呼び出しは、サブエージェントのコンテキストの中に残ります。

なぜこうするのか。メインセッションで作業していると、メッセージ、読み込んだファイル、コマンドの結果がすべて1つのウィンドウの場所を取ります。そしてその容量には限りがあります。ウィンドウが埋まっていくと、Claude Codeは履歴を短くするため、細かい情報の一部が失われることがあります。サブエージェントを使えば、途中の作業を別のウィンドウに移し、メインの会話にはその結果だけを残せます。

いちばんシンプルなサブエージェント

最初の実行には、Claude Codeへの普通のメッセージで十分です。サブエージェントを呼び出すようはっきり頼み、そのタスクを説明してください。事前に独自のロールファイルを作る必要はありません。こうした依頼には組み込みのアシスタントが使えます。たとえば、次のように頼みます。

サブエージェントを呼び出して、index.htmlファイルを読ませて。
ファイルの短いマップを作ってもらって: 主なセクションと、
それぞれが何をしているか。そのあと、内容の要約を
3-5文で書いてもらって。
ファイルは変更しないで。サブエージェントの回答をこのセッションに返して。

メインエージェントはタスクをアシスタントに渡し、終わったらその回答をあなたの会話に表示します。バックグラウンドで実行した場合は、入力欄の下にサブエージェントの名前と作業状況を示すバーが表示されます。それをクリックするとサブエージェントのセッションが開き、何を読んで何をしているかを見られます。作業中に、サブエージェントが別途起動されたことを確かめてください。普通の文章での依頼はClaudeの選択を方向づけますが、それだけで委任が保証されるわけではありません。

サブエージェントが受け取るもの

同じ依頼を決まったルールで繰り返す必要があるなら、独自のロールをファイルに記述できます。こうしたカスタムサブエージェントが起動時に受け取る主な入力は、次の2つです。

• ロールの指示。あなたの設定ファイルに書かれた、専門分野と振る舞いのルールです。
• タスクの説明。あなたの依頼をもとにメインエージェントが作成します。

これに加えて、Claude Code自身が共通の背景情報を追加します。プロジェクトのCLAUDE.mdファイル、git statusのスナップショット、実行環境に関する情報です。メインエージェントとのあなたの会話は、ここには含まれません。

この図で大事なのは1点だけです。サブエージェントは自分のウィンドウで依頼をこなし、メインの会話にはサマリーを返します。メインエージェントは、途中の読み取りや検索をすべて抱え込まずに済みます。とはいえ、サマリー自体もメインのコンテキストの場所を取ります。

こうした分担には裏の面もあります。サマリーには、結論に至るまでの道のりがすべて書かれているわけではありません。アシスタントにどんなデータが足りなかったのか、何を確認しないまま残したのかを見落とすおそれがあります。だからこそ、回答には根拠と制約が必要で、その結論は確かめる価値があります。

Claudeがすべてを覚えていない理由

コンテキストウィンドウとは、モデルが次の回答を用意するときに手元にある情報のことです。指示、参照できる会話の履歴、読み込んだコード、コマンドの結果などが含まれます。エージェントが数メッセージ前に話し合った決定を踏まえて動けるのは、このためです。ウィンドウには上限があり、会話のすべてを細部まで永遠に保持しているわけではありません。

スクリーンショットでは、/contextコマンドが4k/200k tokens (2%)と表示しています。使える20万トークンのうち、約4千トークンが使われているという意味です。トークンとはテキストの小さな断片で、単語、単語の一部、あるいは記号1つにあたります。そのため、20万トークンは20万語と同じではありません。これは画面に表示されているセッションのウィンドウサイズで、モデルや設定が違えば変わることがあります。

その下には、何が場所を取っているかが表示されています。System promptはシステムの指示、Memory filesは読み込まれたメモリやルールのファイル、Skillsはスキルの情報、Messagesはメッセージです。やり取りはまだほとんどありませんが、ウィンドウの一部はすでに指示で埋まっています。Free space: 196k (98.0%)の行は、残りの空き容量を示します。会話を続け、ファイルを読み、コマンドを実行するにつれて、この空きは減っていきます。

ここからは、コードを読むカスタムのreviewerを例に、この仕組みを見ていきます。reviewerがどんな情報を受け取るのか、そのロールファイルをどう作るのか。ここで扱うのは通常の新規実行です。以前の作業を続ける方法や、履歴のコピーを渡す方法は、この例では使いません。

2. reviewerはプロジェクトについて何を知っているか

コンテキストが独立しているからといって、アシスタントが何も知らないわけではありません。最初の指示があり、プロジェクトにもアクセスできます。この例のカスタムreviewerが情報を得る経路は次のとおりです。

CLAUDE.mdは、Claude Code向けの共通の指示を書いたファイルです。たとえば、ソースコードがどこにあるか、プロジェクトでどんな規約を採用しているかなどを書きます。今回の確認のためにわざわざ作る必要はありません。

あなたとの会話の履歴は、自動では引き継がれません。メインエージェントがすでにapp.jsを読んでいても、その読み取り結果がreviewerの手元に現れるわけではありません。とはいえ、ファイルがなくなったわけではないので、アシスタントはもう一度開けます。

チャットで決めたことも同じです。たとえば、リストに同じ名前が2つあっても、別々の買い物として残すべきだと話し合ったとします。削除の確認では、これは重要な要件です。この要件がreviewerに届くのは、メインエージェントが指示に含めた場合か、それが書かれたドキュメントをアシスタントが読んだ場合です。

3. ロールファイルを作成する

ロールはプロジェクト内の.claude/agents/reviewer.mdに置きます。ユーザーフォルダの~/.claude/agents/にも、複数のプロジェクトで使えるロールを置けます。~はユーザーのホームフォルダを表す記号です。今はプロジェクト用のもので足ります。

ファイルはClaude Codeに頼んで作ってもらえます。

ページのコードを変更せずに確認するための
.claude/agents/reviewer.mdを作って。Read、Grep、Globだけを許可して。
reviewerは根拠のある指摘、確認した範囲、制約を返す。
指摘がゼロでも構わない。
作ったファイルを見せて。

結果として、普通のテキストファイルができるはずです。魔法は何もありません。下に完成版を載せておきます。エージェントの回答と見比べてもいいですし、自分で保存してもかまいません。同じ名前のロールがすでにある場合は、必要な指示を上書きしないよう、先に中身を確認してください。

---
name: reviewer
description: 完成したページのコードに動作上の誤りがないか確認し、根拠のあるレポートを返す。修正なしでページのレビューを頼まれたときに使う。
tools: Read, Grep, Glob
---
指定されたファイルのコードを、与えられた要件に沿って調べて。
ファイルは変更しないこと。ページを実行するとは約束しないこと: 使えるのは読み取りと検索だけ。
指摘ごとに、場所、期待される動作、結論の根拠、
確認の条件、影響を示して。データが足りなければ、そう明記して。
確認したことと確認していないことを分けて挙げて。
指定された基準で問題が見つからなければ、そう書いて。

2本の---行に挟まれたブロックはfrontmatterと呼ばれ、Markdownファイルの先頭に置く設定です。ここではnameがロールの名前を決め、descriptionがメインエージェントにいつこのロールを選ぶべきかを伝え、toolsが使えるツールを並べています。その下は、普通の言葉で書いた指示です。

例の3つのツールは、コードを見るのに必要なことをちょうどカバーしています。Readはファイルを読み、Grepは中身を検索し、Globは名前やパスでファイルを探します。そのためreviewerは、削除の関数を見つけて読むことはできますが、ブラウザでページを動かしたり、ターミナルでコマンドを実行したりはできません。

"ファイルは変更しないこと"という一文は、依頼の内容を述べています。toolsフィールドは、それを実行する手段を制限します。本文でお願いするだけでツールを制限しなければ、アシスタントに書き込みの手段が残るかもしれません。完成版の例では両方がそろっているので、あとから制限を足す必要はありません。

ロールファイルはスキルに似ています。設定があって、指示の本文がある。取り違えやすいところです。ただし、ここで設定しているのは確認のための独立した実行です。スキルは通常、繰り返し使う手順を今の会話に持ち込みますが、スキルも独立したコンテキストで実行できる場合があります。2つのファイルの見た目が似ているかどうかではなく、作業をどう実行させたいかで選んでください。

4. reviewerを確認して呼び出す

ディスク上にファイルができたのが、最初の成果です。次は、セッションがそれを認識しているかを確かめます。ファイルを開き、名前reviewer、説明、ツールの行、本文を確認してください。ブラウザを起動するとか、すぐにエラーを直すとかいった約束が書かれていないかも見ておきます。

Claude Codeの入力欄に@と入力し、agentの印が付いたreviewerを選びます。必要なのはロールそのもので、ファイルパスが付いた似た項目ではありません。リストから選ぶことで、この依頼を担当するアシスタントをはっきり指定できます。

ロールが見つからない場合は、まずパスを確認してください。ファイルは、開いているプロジェクトの.claude/agents/にある必要があります。次にfrontmatterです。区切り線が2本ともあるか、名前と説明があるかを見ます。定義ファイルそのものをClaude Codeにチェックしてもらうこともできます。

Claude Codeのドキュメントによると、すでに監視されているフォルダでの変更は数秒で反映されます。セッションの開始後にagentsフォルダが初めてできた場合は、再起動が必要です。今のセッションを終了し、普通のターミナルで、同じプロジェクトフォルダから次を実行してください。

claude --continue

これで、今いるディレクトリでの最後の会話が再開されます。起動したら、もう一度@のリストを確認してください。Claudeを起動するこのコマンドは、終了したあとのターミナルで入力するものです。動いている会話の中で打つものではありません。

最初の依頼には、買い物リストのページを使います。マークアップはindex.html、ロジックはapp.jsにあり、どちらもプロジェクトのルートに置かれています。ご自身のプロジェクトでは、パスと期待する動作を自分のものに置き換えてください。リストからreviewerを選んだら、メンションに続けて次の文を書きます。

プロジェクトのルートにあるindex.htmlとapp.jsを調べて。
項目の追加と削除を確認して: カウンターは残っている項目の数と
一致すること。1件を削除したときに、
同じ名前の別の項目が消えてはいけない。
ファイルは変更しないで。コードからの結論と、ブラウザで確認すべきことを返して。

範囲を絞った確認に必要なものは、これでそろっています。どこを見るか、何が起きるべきか、どんな結果がほしいか。ブリーフを別ファイルにする必要はありません。メインエージェントが、選ばれたreviewer向けにタスクをまとめ直します。@での選択が決めるのは担当者であって、あなたのメッセージがそのまま一字一句渡るわけではありません。

5. 結果はどう返ってくるか

依頼を送ったら、reviewerの実行が始まったかを確認してください。通常の対話型セッションでは、この作業はバックグラウンドで進むことがあります。パネルで様子を見ながら、会話を続けられます。/tasksコマンドを使うと、最近終わったものも含めてタスクを確認できます。

確認が終わると、メインエージェントが結果を受け取り、あなたに伝えます。まとめが短すぎるときは、"reviewerの最終レポートを全文見せて"と頼んでください。そのほうが、指摘の正確な言い回しや確認の制約を残しやすくなります。

たとえば、カウンターについての学習用のレポートは、次のような形になるかもしれません。

app.jsの追加と削除を確認した。
removeItem()ではリストが再描画されるが、この経路で
updateCounter()の呼び出しは見つからなかった。カウンターは
残っている項目の数を示すはず。
ブラウザでの確認: 項目を1つ追加して削除し、
カウンターを空のリストと比べる。
同じ名前の項目の削除は個別には確認していない。
ブラウザでは実行していない。

これは回答の形式の例であって、あなたのページでこのバグが見つかるという意味ではありません。この例のreviewerはコードを読むことしかできないので、最後の行はその能力を正直に書いています。コードからの結論は実行しなくても筋が通っていることがありますが、その根拠は確かめる必要があります。たとえば、同じ経路の別の関数がカウンターを更新していないか、といった点です。

示された場所を開くか、書かれている操作をブラウザで試してみてください。問題が確認できたら、修正をメインエージェントに任せられます。確認できなければ、あなたが見た結果を伝えて、結論を見直すよう頼みます。きれいに整ったレポートだからといって、何を変えるべきかが決まるわけではありません。

"指定された基準では問題は見つからなかった"という回答も、何を確認したかがはっきりしていれば問題ありません。一方、"削除のロジックがあるファイルが見つからなかった"は途中までの結果です。まずパスを確かめる必要があります。数をそろえるために推測でレポートを埋める意味はありません。

ちなみに、リストには組み込みのロールExploreやPlanが出てくることもあります。これらは独自のロールファイルを作らなくても使えます。

6. どんなときに委任するか

最初の確認がうまくいくと、あらゆる作業に専用のアシスタントを付けたくなるかもしれません。その気持ちはよく分かります。ただ、新しい実行には何かしらの意味が必要です。独立した目で見てもらうこと、あるいは細かい経過をメインの会話に持ち込まなくていい独立した作業です。

互いに依存する複数のステップも、サブエージェントへの1つのタスクにまとめられます。ハンドラーを見つけ、その呼び出し元を確認し、結論をまとめる。これは筋の通ったひとまとまりの依頼です。避けたいのは、ステップごとに別のアシスタントに振り分けて、隣のステップの結果を毎回全員に説明し直すはめになることです。

サブエージェントのモデルは、modelフィールドで個別に指定できます。今は必要ありません。まずは分かりやすいロールと、確かめられる結果を手に入れるほうが役に立ちます。別に実行するからといって、モデルが強くなるわけでも弱くなるわけでもありません。

2つ目のロールは別のものを確認すべき

reviewerとは別に、ユーザーの操作シナリオを確認するplaytesterがほしくなったとします。前の指示を名前だけ変えてコピーしても、ほとんど何も変わりません。まずは、何を相手に作業し、何を結果とするのかを区別してください。

たとえば、同じ名前の買い物2つのうち1つを削除するケースだけを扱うロールも考えられます。操作のあとに項目が1つ残り、カウンターが1を示せば正解です。これは測れる依頼です。"このページがいいかどうか評価して"では、好みの問題にすぎない助言が入り込む余地が大きすぎます。

次に、依頼とツールを突き合わせます。この例のreviewerのように読み取りと検索しかできなければ、アシスタントはブラウザで操作を実行できません。確認のシナリオを作ったり、あなたが記録した観察結果を分析したりはできます。これは確認の準備や分析であって、自分で実行したplaytestではありません。

同じ名前の買い物2つのうち1つを削除する確認シナリオを用意して。
ステップごとに、操作と
期待される結果を書いて。コードは変更しないで。実行したとは言わないで。
私の観察結果を渡したら、期待と実際を比べて、
足りないデータを挙げて。

自分で実行させるには、使えるブラウザ操作のツールと、実行が本当に行われたことの確認が必要です。playtesterという名前だけでは足りません。まず確認の方法を決め、それからロールの中に、いつ呼ぶのか、どんな結果なら正直に返せるのかを書いてください。

7. あなたのセッションではどうなるか

これで、セッションが認識するロールのファイルと、それに任せられる短い確認がそろいました。始めるにはこれで十分です。似たようなreviewerを前もって何個も用意する必要はありません。

この先は、問題が見つかった層を直していきます。大事な条件を渡していなかったなら、依頼に書き足す。怪しい結論が返ってきたなら、根拠を確かめる。reviewerが毎回ざっくりした答えばかり返すなら、ロールの指示を具体的にする。ファイルはプロジェクトに残るので、次の確認はこのルールを備えたところから始められます。

繰り返す依頼には、reviewerへのブリーフが役に立ちます。回答を受け取ったら、指摘の確認と修正の選び方に進んでください。