AI Coding Hub

ガイド

Claude Code のサブエージェント

サブエージェントは、独自のシステムプロンプトと権限を持つ「専門の作業者」を Claude Code の中に定義する仕組みです。定義ファイルはプロジェクト用が `.claude/agents/`、個人用が `~/.claude/agents/`。YAML フロントマターで必須なのは `name` と `description` の 2 つだけで、あとは任意です。委譲は自動でも起こりますが、確実に使わせたいときは `@"code-reviewer (agent)"` の形で名指しします。

日本語 · 最終確認日: 2026-09-05 · 英語版の全文: English

置き場所と優先順位

場所有効範囲優先度
管理設定（managed settings）組織全体1（最優先）
--agents CLI フラグ現在のセッション2
.claude/agents/現在のプロジェクト3
~/.claude/agents/自分の全プロジェクト4
プラグインの agents/ ディレクトリそのプラグインが有効な範囲5（最低）
プロジェクト用（.claude/agents/）はバージョン管理に入れてチームで共有するのが公式の推奨です。

定義ファイルの形

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
.claude/agents/code-reviewer.md。フロントマターがメタデータ、本文がそのままシステムプロンプトになります。

本文が重要です。サブエージェントは Claude Code の通常のシステムプロンプトを受け取らず、ここに書いた内容と環境情報だけで動きます。「レビューしてください」とだけ書いたサブエージェントが期待外れなのは、モデルのせいではなく指示が空だからです。

主なフロントマター項目

  • `name`：識別子。小文字とハイフンのみで、コロンは使えません。
  • `description`：どんなときに委譲すべきかを書きます。自動委譲の判断材料になるのはここです。
  • `tools`：使わせるツール（Read、Glob、Grep、Bash など）。読み取り専用にしたければここで絞ります。
  • `model`：`sonnet` / `opus` / `haiku` / `fable`、または完全なモデル ID。
  • `memory`：`user` / `project` / `local`。サブエージェント自身の永続メモリを持たせる場合に指定します。
  • `permissionMode`：`default` / `acceptEdits` / `auto` / `dontAsk` / `bypassPermissions` / `plan`。
description を長く書きすぎない

公式は、全サブエージェントの description を合わせた上限が 15,000 トークンであると明示しています。1 つ 1 つを丁寧に書きすぎると、数が増えたときにここで詰まります。判断に必要な一文に絞るのが正解です。

作り方：v2.1.198 で変わった点

以前は `/agents` が対話ウィザードを開いていましたが、v2.1.198 以降は開きません。代わりに Claude に直接頼みます——「~/.claude/agents/ に、可読性とパフォーマンスの改善提案を出す読み取り専用の code-improver サブエージェントを Sonnet で作って」のように。Claude がファイルを書き、ファイル監視が効いているため数秒で反映されます（新しい agents/ ディレクトリに最初の 1 つを作るときだけ再起動が要ります）。

呼び出し方 3 通り

# 1. 自然言語（自動委譲）
Use the code-reviewer subagent to look at my recent changes

# 2. @メンション（確実に委譲される）
@"code-reviewer (agent)" look at the auth changes

# 3. セッション全体で固定
claude --agent code-reviewer
設定ファイルで固定する場合は .claude/settings.json に {"agent": "code-reviewer"} を書きます。

メモリの扱いに注意

メインの会話の自動メモリはサブエージェントには読み込まれません（例外は fork で、これは親の会話とシステムプロンプトを引き継ぎます）。サブエージェントに `memory` を指定した場合、それは別ディレクトリの独立したメモリです。「メインで説明したのにサブエージェントが知らない」という現象は仕様であって不具合ではありません。必要な前提は description か本文に書いてください。

よくある質問

サブエージェントのファイルはどこに置きますか？
プロジェクト用は .claude/agents/、個人用は ~/.claude/agents/ です。プロジェクト用はバージョン管理に入れてチームで共有するのが公式の推奨。優先度は管理設定 > --agents フラグ > .claude/agents/ > ~/.claude/agents/ > プラグインの順です。
フロントマターで必須の項目は何ですか？
`name` と `description` の 2 つだけです。name は小文字とハイフンのみでコロン不可。description は「どんなときにこのサブエージェントへ委譲すべきか」を書き、自動委譲の判断材料になります。tools、model、memory、permissionMode などはすべて任意です。
/agents コマンドでウィザードが開きません。
仕様変更です。v2.1.198 以降、/agents は対話ウィザードを開かなくなりました。代わりに Claude に日本語や英語で「~/.claude/agents/ に読み取り専用の code-improver サブエージェントを作って」と頼むと、Claude が定義ファイルを書きます。ファイル監視により数秒で反映されます。
サブエージェントは会話の内容を引き継ぎますか？
メインの会話の自動メモリは引き継ぎません。例外は fork で、これは親の会話とシステムプロンプトを継承します。サブエージェントに memory を設定した場合も、それは独立した別ディレクトリです。必要な前提は description か本文に明記してください。

出典

次に読む