Claude Code のカスタムサブエージェント(.claude/agents)を自作する実装手順 — 自動委譲されない・tools 制限・コンテキスト分離の3つのハマりどころ【2026】

はじめに / 対象と前提

Claude Code には、特定の作業を専任の「サブエージェント」に委譲する仕組みがある。.claude/agents/ に Markdown ファイルを置くだけで、コードレビュー専任・調査専任のようなエージェントを自作できる。

自分は普段のリポジトリでレビュー用・調査用のサブエージェントを運用しているが、最初に導入したとき「定義したのに一向に使ってくれない」「ツールを絞ったつもりが動かない」で数時間溶かした。この記事では最小構成での作り方と、実際に踏んだ3つのハマりどころをまとめる。

• 想定読者:Claude Code を日常的に使っていて、素の Task ツール委譲から一歩進みたい人
• 前提環境:Claude Code v2 系(2026年9月時点)、macOS / Linux
• 先週書いた Agent Skills(SKILL.md)とは別機能。Skills は「手順書を現在のセッションに読み込む」仕組み、サブエージェントは「独立したコンテキストで作業を丸ごと任せる」仕組み。混同しやすいので注意

TL;DR

• .claude/agents/<name>.md に frontmatter(name / description / tools)+ 本文(システムプロンプト)を書くだけで動く
• 自動で使ってくれるかは description の書き方が9割。「いつ使うか」をトリガー条件として書く
• サブエージェントは会話履歴が見えない独立コンテキスト。「さっきの話の続き」は通じない

手順 / 動かし方

プロジェクト直下に定義ファイルを作る。例としてコードレビュー専任エージェント:

---
name: reviewer
description: コード変更のレビュー専任。diff を見て正しさ・セキュリティの欠陥のみを指摘する。コードを編集した直後に必ず使うこと。
tools: Read, Grep, Glob, Bash
---

あなたはシニアエンジニアのレビュアーである。
渡された diff を読み、以下の観点で欠陥のみを報告する。

- ロジックの誤り・境界条件の見落とし
- 秘密情報のハードコード
- 指摘は「ファイル:行番号 + 理由 + 修正案」の形式で返す

置き場所は2種類ある:

• .claude/agents/reviewer.md — このプロジェクト専用(リポジトリにコミットしてチーム共有可)
• ~/.claude/agents/reviewer.md — 全プロジェクト共通(同名ならプロジェクト側が勝つ)

動作確認は明示指名が確実:

> reviewer サブエージェントで直近の変更をレビューして

実行されるとメインの応答とは別枠でサブエージェントのタスクが走り、最終レポートだけが会話に戻ってくる。/agents コマンドで対話的に作成・編集もできるが、仕組みを理解するには一度手書きするのがおすすめ。

ハマりどころ

1. 定義したのに自動委譲されない

一番多いやつ。ファイルを置いても、Claude が「この作業はこのサブエージェント向きだ」と判断しない限り自動では使われない。判断材料は description だけ。

自分は最初 description: コードレビューをする と書いて全く発火しなかった。「何をするか」ではなく「いつ使うか」を書くと通るようになる:

# NG:能力の説明だけ
description: コードレビューをする

# OK:トリガー条件を書く
description: コードを編集・追加した直後に必ず使う。diff の正しさとセキュリティを検証する専任レビュアー。

「〜した直後に必ず使う」「〜のときに使う」のような条件文を入れるのがコツ。それでも不安定なら、CLAUDE.md 側に「編集後は reviewer サブエージェントを起動する」と運用ルールとして書いてしまうのが確実だった。

2. tools 欄の指定ミスは黙って壊れる

tools を省略するとメイン側の全ツール(MCP 含む)を継承する。絞りたい場合はカンマ区切りで列挙するが、ここで ツール名をタイポしてもエラーは出ない。存在しない名前は無視され、意図したツールが使えないまま「〜ができませんでした」と報告だけ返ってくる。

# Grep を grep と書いた → 検索できないエージェントが黙って誕生する
tools: Read, grep, Glob

ツール名は大文字小文字まで正確に(Read Edit Write Grep Glob Bash など)。また、サブエージェントにさらに Task(入れ子のサブエージェント起動)は渡せない。読み取り専用のレビュアーには Edit / Write を渡さない、が安全側の定石。

3. コンテキスト分離を理解していないと会話が破綻する

サブエージェントは毎回まっさらなコンテキストで起動する。メイン会話の履歴・直前の議論・過去に読んだファイルの内容は一切引き継がれない。

自分がやらかした例:メイン側で設計方針を散々議論した後「その方針で実装をサブエージェントに任せて」と依頼 → サブエージェントは方針を知らないので、全く違う実装が返ってきた。

対策は2つ:

• 委譲プロンプトに全部書く:前提・制約・対象ファイルパスを依頼文に明示する(Claude に「委譲時は方針を要約して渡すこと」と指示しておく)
• ファイル経由で受け渡す:方針を docs/plan.md に書き出させ、サブエージェント定義側に「作業前に docs/plan.md を読むこと」と書く

逆に言えば、この分離のおかげでメイン側のコンテキストを消費せずに大量のファイル探索を任せられる。「調査系こそサブエージェント向き」というのが運用して分かった実感。

まとめ

• .claude/agents/<name>.md + frontmatter で専任エージェントを定義できる。プロジェクト用と全体用の2階層、同名はプロジェクト優先
• 自動委譲は description が全て。「いつ使うか」のトリガー条件を書く
• tools のタイポは無言で壊れる。大文字小文字まで正確に、権限は最小限に
• 独立コンテキストなので前提はプロンプトかファイルで毎回渡す
• Skills(手順書の読み込み)とは役割が違う。「コンテキストを分けて作業を任せたい」ならサブエージェント一択