【Claude Codeサブエージェント入門 第3回】担当を定義する ― ファイルの形(frontmatterと本文)、Claudeに頼むかファイルを書くか、フィールドの一覧、「いつ任せるか」を伝えるdescription

Claude Codeサブエージェント入門 第3回 担当を定義する 生成AI

「担当を自分で作りたいのですが、ファイルに何を書けばよいのか分かりません。/agents から作るのですか」
「description を書いたのに、担当がなかなか使われません。本体はどこを見て、任せるかどうかを決めているのですか」

第2回で、組み込みの担当と、担当を使う・使わないの判断、置き場所を見ました。この回からは、自分の担当を定義する番です。担当は、.claude/agents/ に置く Markdown のファイル1つが1人です。ファイルの形は単純ですが、書き方の1行1行に意味があり、特に description が、担当が使われるかどうかを左右します。

第3回では、ファイルの形、作り方(Claude に頼むか、ファイルを書くか)、フィールドの一覧、description の書き方を扱います。


ファイルの形

担当の定義は、.claude/agents/ の Markdown 1つが1人の担当です。ファイルは次の形です。

  • 2つの部分:先頭の --- で挟んだ frontmatter(設定)と、その下の本文(担当のシステムプロンプト)
  • 本文が担当への指示:本文が担当のシステムプロンプトになり、Claude Code の既定のシステムプロンプトは入らない(ほかに渡るものは第1回の「担当に渡るもの・渡らないもの」)
  • 必須は2つ:name と description(いつ任せるか)。model などは任意(下の「フィールドの一覧」)

筆者が練習用に使う調査担当の例です。

---
name: infra-researcher
description: roles や inventory を読み取り専用で調べ、見つけたファイルと要点だけを返す。調べものを任せるときに使う。
tools: Read, Grep, Glob
model: haiku
effort: medium
---
あなたは調査担当です。ファイルは変更しません。
返す形:
1. 結論(1〜3行)
2. 根拠(ファイル:行)
3. 分からなかったこと(なければ「なし」)
4. 遭遇した障害(なければ「なし」)
  • name:担当の名前。infra-researcher のように書く。担当は、この name だけで呼び分けられる
  • description:いつ任せるか。本体が、この文を見て任せるかを決める(後の節)
  • tools:使える道具。ここでは読み取りだけ(Read・Grep・Glob)に絞っている(第4回の「tools で「できること」を絞る」で扱います)
  • model・effort:担当のモデルと考える量。別名で書く(第5回の「model に書ける値」、第6回の「effort も担当ごとに」で扱います)
  • 本文:担当への指示。役割(調査担当)、してはいけないこと(ファイルは変更しない)、返す形を書く(第4回の「返す形と、障害の報告」で扱います)

説明のため、description を短くした例です。筆者の担当の定義の全文は、第11回の「準備プロンプト」に載せます。3役の一覧は、第9回の「3役のひな形(筆者の例)」で扱います。Web も調べさせるなら、tools に WebFetch・WebSearch を足します。出典は https://code.claude.com/docs/ja/sub-agents です。

公式の文書には、次の決まりもあります。

  • name は、公式の説明では、一意の識別子で256文字以内。code-reviewer・reviewer-v2 のような形です。ファイル名と一致しなくてもよい
  • name に : は使えません。: は、プラグインの担当の名前(my-plugin:reviewer)のために予約されています
担当の定義ファイル .claude/agents/infra-researcher.md の形を示した図。ファイルの上半分は青い枠の frontmatter で、「---」で挟まれた中に name: infra-researcher、description: roles や inventory を読み取り専用で調べ、見つけたファイルと要点だけを返す。調べものを任せるときに使う。(2行に分けて表示)、tools: Read, Grep, Glob、model: haiku、effort: medium がある。下半分は緑の枠の本文で、「あなたは調査担当です。ファイルは変更しません。」「返す形:」に続けて、1. 結論(1〜3行)、2. 根拠(ファイル:行)、3. 分からなかったこと(なければ「なし」)、4. 遭遇した障害(なければ「なし」)が並ぶ。右に2つの説明枠がある。青い「frontmatter(設定)」は、必須は name と description(いつ任せるか)で、model などは任意。緑の「本文=担当への指示」は、本文が担当のシステムプロンプトになり、Claude Code の既定のシステムプロンプトは入らない。最下行に「2つの部分:先頭の --- で挟んだ frontmatter と、その下の本文」とある。

作り方:Claude に頼むか、ファイルを書く

担当の作り方は、2つです。

  • 頼む:「.claude/agents/ に、読み取り専用で Haiku の調査担当を作って」のように、置き場所・役割・道具・モデルを言うと、Claude が定義を書く(公式)
  • 手で書く:上の形のファイルを .claude/agents/ に置く。どちらでも、できたら定義を読み、tools・model が頼んだとおりかを確かめてから使う

/agents は案内だけ

公式の文書では、Claude Code v2.1.198 以降、/agents は「Claude に頼むか、ファイルを直接編集する」という案内を表示するだけです。担当を作る対話式のウィザード(Running と Library のタブ)は、v2.1.197 以前の動きです。公式の commands の一覧も、/agents を、Claude に担当の作成・管理を頼むか .claude/agents/・~/.claude/agents/ を直接編集するよう促す案内として載せています。

  • Academy のレッスン2は、その以前の画面の説明です。 /agents を開いて「Create new agent」を選び、次の順に進みます
    • スコープを選ぶ:プロジェクトレベル(現在のプロジェクトでのみ使える)か、ユーザーレベル(マシン上のすべてのプロジェクトで共有する)
    • 作成方法を選ぶ:Claude に生成させる(レッスンは、これを推奨しています)か、手で書く
    • ツールを選ぶ:カテゴリは、読み取り専用ツール・編集ツール・実行ツール・MCPツール・その他のツール
    • モデルを選ぶ:Haiku(高速で軽量なタスクに最適)・Sonnet(速度と深さのバランス)・Opus(複雑な分析に最適)・Inherit(メインの会話で動いているモデルをそのまま使う)
    • 色を選ぶ
  • 事前課題でレッスン2を任意にした理由も、これです(第1回の「あわせて読みたい公式の教材」)。Academy のページには版の記載が無く、今の /agents と画面が合いません
  • Code タブの /agents で何が出るかは、筆者は確かめていません

書き込みの確認

.claude/ の下(.claude/agents/ も)は保護されたパスで、自動では承認されません。公式の文書は、「手動」と「編集を受け入れる」では確認が出る、と書いています(権限モードの表で、default と acceptEdits は「Prompted」)。保護されたディレクトリの例外の一覧(.claude/worktrees/、セッションのプランのファイルなど)に、.claude/agents/ は入っていません。

確認の画面には、公式の文書によると、セッションの間だけ .claude フォルダーの編集を許す選択肢(「Yes, and allow Claude to edit files in this project’s .claude folder for this session」)が出ることがあります。Code タブで、確認の画面にどんな選択肢が出るかは、筆者は確かめていません。迷ったら、内容を見てその1回だけ許可して進めます。

筆者が CLI の Claude Code 2.1.302 で、非対話の claude -p で担当の定義3つの作成を頼んだときは、3つのファイルの書き込みがどれも承認待ちになり、Claude は「許可してもらえれば続ける」と止まりました。-p には確認の画面が無いので、「承認が要る」として止まります。筆者は、プロンプトに書かれた中身のままファイルを置き、git commit しました。保護されたパスの考え方は、連載「Claude Code実践入門」第5回「6つの権限モード」にもあります。

出典は、公式の sub-agents のページ(Quickstart)、公式の permission-modes のページ(https://code.claude.com/docs/ja/permission-modes)、Academy のレッスン2です。


フィールドの一覧

frontmatter に書けるフィールドの主なものは、次のとおりです。

フィールド意味メモ
name・description必須。名前と、いつ任せるか全担当に書く(次の節)
tools・disallowedTools使える道具・外す道具役割で絞る(第4回の「tools で「できること」を絞る」)
model・effort担当のモデルと考える量別名で書く(第5回の「model に書ける値」、第6回の「effort も担当ごとに」)
skills起動時に全文を読み込むスキルansible-verify(第7回の「スキルと担当の組み合わせ方2つ」)
maxTurns・color最大ターン数・表示の色必要なら足す
permissionMode・isolation・memory・omitClaudeMd・background・hooks権限のモード・作業ツリーの分離・記憶・CLAUDE.md なし・常に裏・フック必要になったら公式を見る。hooks は連載「Claude Codeフック入門」
  • フィールド名は camelCase で、綴りを間違えるとエラーなしで無視されます。 公式は、maxTurns・disallowedTools のように複数の語は camelCase で、表のとおりに書くこと、知らないフィールドは報告せずに無視することを書いています。読み込まれた担当の綴りの間違いは、claude --debug で見つけられます(Claude Code v2.1.296 以降。デバッグのログに、認識されないフィールド名が出ます)
  • permissionMode は、本体が「自動」「編集を受け入れる」のとき無視されます。 公式は、本体が「権限をバイパス」のときも同じと書きます。本体のモードで担当も動き、担当の permissionMode は使われません
  • mcpServers と、Academy レッスン2のツールのカテゴリ「MCPツール」は、この連載では扱いません
  • 公式の表には、このほかに autoCompactWindow・initialPrompt・experimental などのフィールドもあります。この連載では使いません
  • プラグインの担当は、hooks・mcpServers・permissionMode が無視されます(第2回の「担当の置き場所と優先順位」)

出典は https://code.claude.com/docs/ja/sub-agents です。


description は「いつ任せるか」と「何を渡すか」

本体は、全担当の名前と description を見て、任せるかを決めます。公式の文書は、「Claude は各担当の description を使って、いつタスクを任せるかを決める。担当を作るときは、明確な description を書いて、Claude がいつ使うかを分かるようにする」と書いています。任せるときの依頼文も、description を手がかりに書かれます。

本体が description を見て担当に任せる流れを示した図。左の灰色の箱「全担当の名前と description」(infra-researcher、playbook-writer、playbook-reviewer)から「見て」の矢印でオレンジの箱「本体 任せるかを決める」へ進み、さらに「依頼文」の矢印で緑の箱「担当 infra-researcher など」へ進む。その下に「依頼文も、description を手がかりに本体が書く」とある。下段に3つのカードがある。青「依頼文を具体的にする」は、渡すものと返すものを書く、例:レビューするファイルを正確に渡すこと、例:引用できる出典を返すこと。オレンジ「自分から任せてほしいとき」は、公式の例 Use proactively after code changes.。緑「短く、1行で」は、全担当の description の合計が 15,000 トークンを超えると、起動時に警告が出る。最下段の枠に「確実に使うなら 担当の名前を言う、または @ で選ぶ」とある。
  • 依頼文を具体的にする:「レビューするファイルを正確に渡すこと」「引用できる出典を返すこと」のように、渡すものと返すものを書く(Academy レッスン3)。description は、担当がいつ動くかを決めるだけでなく、担当に何をするよう指示するかも形作る、とレッスン3は説明します。上の例の「roles や inventory を読み取り専用で調べ、見つけたファイルと要点だけを返す」は、何を調べ、何を返すかを書いています
  • 自分から任せてほしいとき:公式の例は「Use proactively after code changes.」(description の例:Expert code reviewer. Use proactively after code changes.)。Academy のレッスン2は、依頼しなくても任せてほしいときは、description に「proactively」という語を含めるよう書いています。日本語の description で効くかは、筆者は Code タブでは確かめていません
  • 短く、1行で:description は文脈の場所を取ります。公式は「短く保つ」ように書き、組み込みを除く全担当の description の合計が15,000トークンを超えると、起動時に警告が出ます(名前と description を数えます。警告が出ても、担当はすべて読み込まれます)。「1行でなければならない」は Academy の記述(改行が要る場合は \n を使う)で、公式に同じ記述は見つかっていません(公式の例は1行です)
  • 名前を言わない依頼:筆者の記録では、同じ依頼でも、選ばれる担当が変わりました。「roles/ntp の tasks はどこで定義されている?」と、担当の名前を言わずに頼むと、CLI の Claude Code 2.1.289(2026年10月17日)では、自作の担当ではなく組み込みの Explore が選ばれました(description に同じ言い回しがあっても、です)。CLI の 2.1.302(2026年10月18日、claude -p)では、自作の infra-researcher が選ばれました(どちらの版でも、担当の description には「どこで定義されている?」という言い回しが入っていたので、選ばれた理由は断定できません。全文は第11回の「準備プロンプト」)。名前を言わない依頼では、どの担当が選ばれるかは決まりません
  • 確実に使うなら:担当の名前を言う、または @ で選ぶ(呼び方は、第7回の「担当の呼び方3つ」で扱います)
  • description が無い定義は、読み込まれません。 筆者の CLI 2.1.289 では、description の無い定義は担当の一覧に出ず、エラーも出ませんでした。公式の文書も、name はあるが description が無いファイルは読み飛ばし、理由はデバッグのログに書く、と説明します。name が無いファイルは、担当ではなく「担当の隣に置いた文書」として扱われます(第4回の「反映のタイミングと、読み込まれないとき」で扱います)

冒頭の2つ目の相談が、これです。本体は description を手がかりに任せるかを決めるので、「いつ使うか」「何を渡し、何を返すか」を書きます。 確実に使いたいときは、名前を言います。

出典は、Academy のレッスン2・3(https://academy.claude.com/ja/courses/introduction-to-subagents/designing-effective-subagents)と、公式の sub-agents のページです。


考えてみよう

  1. 自分の作業から、担当にしたい作業を1つ選び、name と description を書いてみてください。description に、いつ使うかと、何を渡し、何を返すかが入っていますか
  2. 上の調査担当の本文には、「返す形」と「遭遇した障害」の欄があります。自分の担当には、どんな返す形が要りますか。(ヒント:本体が次に何をするかを考えます)
  3. .claude/agents/ に自作の担当を置くとき、確認の画面に出るのはどんな選択肢でしたか。その1回だけ許すか、セッションの間 .claude の編集を許すか、どちらにするか理由を言えますか

ヒント:1は「description は『いつ任せるか』と『何を渡すか』」、2は「ファイルの形」(返す形は、第4回の「返す形と、障害の報告」で詳しく)、3は「書き込みの確認」の節を見直してください。


まとめ

  • 担当の定義は、.claude/agents/ の Markdown 1つ。frontmatter(設定)と本文(担当のシステムプロンプト)の2つの部分。必須は name と description
  • 作り方は、Claude に頼むかファイルを手で書くか。どちらでも、できたら tools・model が頼んだとおりかを確かめる。/agents は v2.1.198 以降、案内を表示するだけ
  • .claude/ の下は保護されたパス。「手動」「編集を受け入れる」では確認が出る。確認の画面には、セッションの間だけ許す選択肢が出ることがある(公式)
  • フィールド名は camelCase で、綴りを間違えるとエラーなしで無視される。--debug で見つけられる(v2.1.296 以降)
  • 本体は description を見て任せるかを決める。いつ使うか・何を渡し何を返すかを書く。合計が15,000トークンを超えると警告。名前を言わない依頼では、選ばれる担当が決まらないので、確実に使うなら名前を言う

次回は、tools で担当ができることを絞る方法、返す形と障害の報告、定義の反映のタイミングと、読み込まれないときを扱います。


連載「Claude Codeサブエージェント入門」全13回

全回の目次と、読む順番・目的別の読み方は、Claude Codeサブエージェント入門の入口のページにまとめています。

  1. サブエージェントとは
  2. 組み込みの担当と使い分け
  3. 担当を定義する(この記事)
  4. toolsと返す形
  5. 担当のモデルの決まり方
  6. 役割とモデル・effort
  7. スキルから担当を呼ぶ
  8. 順に使う・前と裏
  9. ログの要約とレビューの担当
  10. 費用を測って小さく使う
  11. 演習(前編):準備
  12. 演習(中編):読み込む・呼ぶ・モデルを見る
  13. 演習(後編):レビュー・スキル・費用

コメント

タイトルとURLをコピーしました