自分用のサブエージェントを作る

用語辞典のサブエージェントでは、サブエージェントが独立したコンテキストウィンドウを持ち、探索の過程をメインの会話に残さないという仕組みを扱いました。ここでは一歩進んで、自分用のサブエージェントを作る側の実務を扱います。

説明文（description）は2つの役目を持つ

サブエージェントの設定ファイルには、descriptionという項目があります。公式ドキュメントは、この項目の役割をこう説明しています。

これだけを見ると、descriptionは「起動条件」を書く欄のように見えます。ただし実際にはもう一つの役目があります。Claudeはこの説明文をもとに、サブエージェントへ渡す依頼文そのものを組み立てるのです。つまりdescriptionの書き方は、サブエージェントが呼ばれるかどうかと、呼ばれたときに何を頼まれるかの両方を左右します。

自動的に委任されやすくしたいときは、説明文に「使うべき場面」を具体的に書き添えるほうが効きます。たとえば「コードの変更後に使う」とだけ書くより「コードを変更した直後に、積極的に使う」のように促す言い回しを添えると、Claudeが自分の判断で呼び出しやすくなります。

説明文は要点だけに絞ってください。すべてのサブエージェントの説明文を合わせた分量が一定を超えると、起動時に警告が出るほど、この部分はコンテキストを消費します。細かい振る舞いは説明文でなく、本文（システムプロンプト）側に書きます。

作り方は、いまは対話式ではない

サブエージェントの作成画面が案内として紹介されることがありますが、現行のClaude Codeでは/agentsコマンドは対話的な作成ウィザードを開きません。実行すると、Claudeに直接頼むか、設定ファイルを自分で編集するよう促すだけです。作り方は次の2択になります。

ファイルの中身は、YAMLの先頭部分（フロントマター）と、そのあとに続く本文で構成します。本文がそのままサブエージェントのシステムプロンプトになります。

---
name: tone-checker
description: 社外向けの文章のトーンを整える。書き終えた直後に、積極的に使う
tools: Read, Grep
model: sonnet
---

あなたは文章のトーンを確認する担当です。敬語の崩れ、
過度な断定、社外に出すには強すぎる言い回しを指摘してください。
指摘には該当箇所と、言い換えの案を1つ添えてください。

必須なのはnameとdescriptionだけです。toolsで使える道具を絞り込み、modelで担当させるモデルを選べます。ファイルを保存すると数秒で読み込まれるので、セッションを再起動する必要はありません（新しいディレクトリに最初の1つを置いたときだけ再起動が要ります）。

やってはいけない使い方

サブエージェントは万能ではありません。向かない使い方には共通の型があります。

各段階が前の発見に依存する仕事は、サブエージェントに分割せず、1つのセッションの中で通しで進めるほうが確実です。「中間の過程を自分（メインスレッド）が知る必要があるかどうか」を先に自問すると、分割すべきかどうかの判断がぶれません。

やってみよう

演習1：繰り返している「調べて」仕事を1つ選ぶ

自分がClaude Codeに繰り返し頼んでいる調査系の仕事を1つ選び、descriptionの下書きを書いてみましょう。「いつ使うべきか」が具体的に伝わる一文になっているか、声に出して確かめてください。

演習2：分割してよい仕事、悪い仕事を見分ける

最近扱った複数手順の仕事を1つ選び、各手順が前の手順の発見に依存しているかどうかを考えてみましょう。依存していないなら独立したサブエージェントに分ける価値があり、依存しているなら1つのセッションで通しに進めるべき仕事です。

今日のまとめ

3行で振り返ります。

• サブエージェントのdescriptionは、いつ呼ぶかの判断材料であると同時に、何を頼むかを形作る文章でもある
• 現行の作り方は/agentsの対話式ウィザードではなく、Claudeに直接頼むか.claude/agents/にファイルを置く2択
• 肩書きだけの説明文や、各段階が前の発見に依存する仕事の分割は、サブエージェントに向かない使い方

次のレッスンでは、長く任せるときにどこまで確かめればよいかを扱います。