この記事でできるようになること: Claude Codeに専用の役割（サブエージェント）を1つ増やす方法が分かる。必要なのは .claude/agents/<name>.md というテキストファイル1枚だけで、必須項目は name と description の2つ。そこに tools・model を足せば権限とコストを絞り込める。最後にコピペで動く最小定義ファイルと動作確認手順を載せる。
.claude/agents/ は「役割の置き場所」
Claude Codeは起動時に、プロジェクト全体のルールを書く CLAUDE.md や独自コマンドの .claude/commands/ と並んで、.claude/agents/ も読みに行く。以下では例としてレビュー役を reviewer、調査役を researcher と名付けるが、名前は自由に決められる。ここに reviewer.md を1枚置けば、Claude Codeは「reviewerという名前のサブエージェントが使える」と認識する。フォルダが存在しなければ自分で作ればいい。
your-repo/
├── CLAUDE.md
├── .claude/
│ ├── commands/
│ │ └── pre-commit.md
│ └── agents/ ← ここに1ファイル=1役割で置く
│ ├── reviewer.md
│ └── researcher.md
└── src/
1ファイル=1サブエージェント。特別なビルドや登録作業は要らず、.claude/ 配下にあるのでGitでバージョン管理でき、チームでも共有できる。
フロントマターの必須項目は2つだけ
定義ファイルは「YAMLフロントマター（--- で囲んだ部分）+ Markdown本文」の2層構造になっている。公式ドキュメント上「必須」なのは name と description の2つだけで、tools と model は省略できる（2026年8月時点）。ただし省略すると挙動が変わるので、実務では明示するのが基本になる。
| フィールド | 必須/任意 | 役割 | 省略時の挙動 |
|---|---|---|---|
name |
必須 | 呼び出し時の識別子。英小文字とハイフンで書く | — |
description |
必須 | いつ・何のために使う役割かの説明。自動委譲の判断材料になる | — |
tools |
任意 | 渡すツールのカンマ区切りリスト | 使える全ツールが渡る（AskUserQuestion など一部の管理系ツールは常に除外） |
model |
任意 | 使用するモデル |
inherit（メインセッションと同じモデル） |
description は「コードレビューを行う」より「実装を批判的にレビューし、マージ前の品質ゲートとして機能する」のように、いつ・何のために呼ばれるかが分かる書き方をするほど自動委譲の精度が上がる。
本文（--- の下のMarkdown部分）は、そのサブエージェントのシステムプロンプトになる。「あなたは何をする人か」「どんな手順で進めるか」「何をやってはいけないか」を、普通の業務指示書のように自然な日本語で書けばいい。
tools——権限は役割の分だけ渡す
tools を省略すると全ツールが渡ると書いたが、実務では省略しないほうがいい。権限を持つほど、想定外の操作が起きたときの影響が大きくなるからだ。読んで指摘するだけの役割に Write/Edit を渡すと、指摘だけで済むはずの作業でファイルを書き換えてしまう余地が生まれる。役割ごとに必要なツールだけを渡すのが基本方針だ。
| 役割 | 推奨 tools
|
|---|---|
| 実装する役（コードを書く） | Read, Write, Edit, Bash, Grep, Glob |
| レビューする役（読んで指摘する） | Read, Grep, Glob, Bash |
| 調べる役（情報を集める） | Read, Grep, Glob, WebSearch, WebFetch |
「ほぼ全部渡したいが Write と Edit だけ外したい」場合は、許可リストの tools より除外リストの disallowedTools: Write, Edit を使うほうが書きやすい。公式ドキュメントによれば、両方書いた場合は disallowedTools が先に適用され、そのあとに tools の絞り込みが評価される。システムプロンプト本文に「〇〇はしない」と書く抑止も併用できるが、それは「お願いベース」の弱い制約で、tools/disallowedTools から外す「権限ベース」のほうが確実に効く。
model——役割の重さに合わせて選ぶ
model フィールドには、使うモデルを指定する。2026年8月時点で選べる値は次のエイリアスのほか、claude-opus-5 のようなフルモデルIDでの直接指定もできる。なお表の「性格」列は公式ドキュメントの記載ではなく、私の運用経験に基づく整理である。
| 指定値 | 性格 | 向いている役割 |
|---|---|---|
haiku |
速くて安い。定型処理向き | 単純な集計・定型変換・短い確認作業 |
sonnet |
バランス型 | 標準的な実装・レビューなど日常的な役割 |
opus |
賢いが高価 | 設計判断・長文レビューなど重い判断 |
fable |
最上位クラス | コストが重く回収が難しい一点ものの判断 |
inherit（省略時のデフォルト） |
メインセッションと同じモデル | 役割ごとに固定したくないとき |
正式なモデル名や料金は変わりうるため、最新の対応値は公式ドキュメントで確認してほしい。サブエージェントは独立してコストを消費するため、全部を最上位モデルにすると費用がかさむ一方、重い判断を軽いモデルに任せると品質が落ちる。日常的な実装・レビューは sonnet、定型作業は haiku、重い局面だけ opus/fable という配分が現実的だ。
呼び出し方——@メンションと自然言語
定義ファイルを置いたら、メインのClaude Codeから呼び出す。@ メンション（入力欄で @ を打ち補完候補から reviewer を選ぶ。手書きなら @agent-reviewer）は確実にそのサブエージェントを動かせる。自然言語で「reviewerに、このファイルのレビューを頼んで」と書いても呼び出せるが、この場合はメインのClaude Codeが description を見て委譲するかどうかを判断する。確実に呼びたい場面では @ メンション、カジュアルに頼みたい場面では自然言語と使い分けるとよい。
反映タイミングにも触れておく。公式ドキュメントによれば、.claude/agents/ と ~/.claude/agents/ はファイル変更を数秒以内に自動検知し、多くの場合再起動は不要とされている（2026年8月時点）。例外は2つある。(1) セッション開始時点でそのディレクトリ自体が存在しなかった場合（＝そのスコープで初めてサブエージェントを作った直後）と、(2) --disable-slash-commands オプション付きで起動したセッション（そもそもディレクトリを監視しない）では、再起動が必要になる。「@ の候補に出てこない」ときは、まず (1) のケースを疑う。
.claude/agents/ はどこに置くべきか——プロジェクト内 or ユーザーグローバル
サブエージェント定義は2か所に置ける。
| 配置場所 | 有効範囲 | 用途 |
|---|---|---|
<project>/.claude/agents/<name>.md |
そのプロジェクトのみ | プロジェクト固有の役割。Gitで共有できる |
~/.claude/agents/<name>.md |
すべてのプロジェクト | どこでも使いたい自分専用の役割 |
同じ名前の定義がある場合はプロジェクト内が優先される。プロジェクト固有の規約と結びついた役割はプロジェクト内に、汎用的な役割はユーザーグローバルに置くのが目安。複数プロジェクトを掛け持ちしているなら、まずプロジェクト内に置いて試し、どこでも使うと分かった役割だけグローバルに昇格させるとよい。
コピペで動く最小定義ファイル
そのまま <project>/.claude/agents/reviewer.md として保存すれば動く例を載せる。「読むだけで書き換えない」レビュー役の最小構成だ。
---
name: reviewer
description: 実装を批判的にレビューし、マージ前の品質ゲートとして機能する。コードは読むが書き換えない
tools: Read, Grep, Glob, Bash
model: sonnet
---
あなたはコードレビュアーです。変更されたコードを批判的に読み、改善点を指摘します。
コードは読みますが、書き換えはしません（書き換え権限は渡されていません）。
## 進め方
1. 変更されたファイルを Read で読む
2. ロジック・命名・テストの妥当性を検証する
3. 既存コードの規約に照らして、気になる点を指摘する
## 指摘の出し方
- 影響の大きい指摘から先に出す。タイポは最後
- 「読みにくい」ではなく「この関数は3つの責務を持つので分けるべき」と具体的に書く
- 修正案は押し付けず、選択肢として提示する
## やらないこと
- ファイルの書き換え（権限として渡されていない）
- 自分の好みだけを根拠にした指摘
フロントマター4行と本文だけで、コードは1行も書いていない。
サブエージェント定義ファイルはClaudeに作らせて手直しする
このファイルを一から手で書く必要はない。メインのClaude Codeに生成を依頼し、出来上がったものを細部だけ手直しするほうが実務では早い。依頼プロンプトの例を載せる。
reviewerというサブエージェントを .claude/agents/reviewer.md として作って。
役割: 実装を批判的にレビューする。コードは読むが書き換えない
権限: Read, Grep, Glob, Bash のみ渡す（Write/Editは渡さない）
モデル: sonnet
description には「いつ・何のために呼ばれる役割か」まで書いて
このように役割・渡す権限・モデル・descriptionの意図を自然言語で伝えれば、上の最小定義ファイルに近い形の雛形を生成してくれる。生成されたファイルは、そのまま使わずに次の点を自分の目で確認する。
-
toolsにWrite/Editなど渡すつもりのなかった権限が紛れ込んでいないか -
descriptionが「いつ呼ばれるか」まで書けているか（「レビューする」だけでは自動委譲の判断材料として弱い） -
modelが役割の重さに見合っているか（定型作業にopusを割り当てていないか、重い判断役がhaikuになっていないか） - 本文の「やらないこと」節が、
toolsで絞り込んだ権限と矛盾していないか
動作確認方法
ファイルを置いたら、次の手順で確認する。
-
@の候補に出るか確認する——入力欄で@を打ちreviewerが表示されるか見る。出なければ新規ディレクトリのケースを疑い、再起動する -
実際に呼び出してみる——
@reviewer 適当な変更ファイルをレビューしてと依頼し、読むだけで書き換えない・指摘が具体的、など想定どおりの振る舞いか確認する -
権限が絞れているか確認する——
toolsに含めていない操作（例: ファイルの書き換え）を依頼し、拒否・実行されないことを確認する
同じ .claude/agents/（または ~/.claude/agents/）のディレクトリツリー内に同名の定義ファイルが複数存在してしまった場合は、/doctor コマンドが重複を検出して教えてくれる（出典: 公式ドキュメント、2026年8月時点）。なお、プロジェクト内とユーザーグローバルで同名の定義がある場合はこの検出の対象外で、プロジェクト内の定義が優先されるだけで警告は出ない。
サブエージェント定義ファイルを作った次にやること
これで、サブエージェント定義ファイルという「部品」の読み書きは一通りできるようになったはずだ。.claude/agents/<name>.md を1枚置き、name と description を書き、必要に応じて tools で権限を絞り、model でコストと品質のバランスを取る。それだけで、Claude Codeに新しい役割を1つ増やせる。
ここまでできると、次に出てくる問いは「では実際にどの役割へ何の権限を渡し、何体構成で回すべきか」という設計判断のほうに移る。ここから先は、実際に手を動かして踏んだ判断の積み重ねが物を言う領域になる。
Zenn Book「Claude Codeで作る1人エージェントチーム」（序章無料）では、writer + reviewerの2体構成から始める設計判断の基準と、権限を絞りすぎた・緩めすぎた実際の失敗談を扱っている。この記事で1体を動かせるようになった人が、次に「もう1体足すかどうか」を考えるときの材料になるはずだ。
関連記事:
- Claude Code に最初から入っている SubAgent 5体——機能・モデル・使い分け一覧 — 自作の前に、ビルトインの5体で何が足りるかを把握したい人向け
- Claude Codeで役割を与えると結果はどう変わるか——writer + reviewer 二体構成の実践記録 — 本記事のリファレンスを実際に動かすとどうなるかの実践記録
- Claude Code の Built-in SubAgent は上書きできない——公式が書かないルールを実測で確かめた — 自作定義とビルトインの名前が衝突したときの挙動
Claude Code をもっと深く使いこなしたい方には、実践的な解説書が参考になる。
- 実践Claude Code入門――現場で活用するためのAIコーディングの思考法（西見 公宏・吉田 真吾・大嶋 勇樹）
- Claude CodeによるAI駆動開発入門（平川 知秀）
この記事は はてなブログ からのクロスポストです。