はじめに
個人開発の育児記録アプリを、ほぼすべて Claude Code に実装させています。
.claude/agents/ には、実装担当・テスト担当・ドキュメント監査担当のサブエージェントを置いていました。
せっかく作ったので、こちらから名前を出さなくても、場面に合わせて使ってほしいと考えました。
そこで「サブエージェントが自動で呼ばれるように工夫して」と Claude に頼みました。
この記事では、そのときに分かった次の2つを紹介します。
- サブエージェントへの自動委譲は、hook ではなく
descriptionと CLAUDE.md で決まる - レビューのような重い処理は、サブエージェント側で動かすとメインの会話が汚れない
Claude Code でカスタムサブエージェントを作ったものの、あまり使われていないと感じている方に向けた内容です。
TL;DR
- Claude は「依頼の内容」「サブエージェントの
description」「今の文脈」から、委譲するかを自分で判断する。確実に振らせたいなら、descriptionにどんな依頼で使うかを具体的に書く - それでも足りない分は、CLAUDE.md に「この状況では確認せずに委譲する」という表を書く
- hook でできるのは、条件を確かめる判定用のサブエージェント（実験的機能）まで。「この作業は feature-dev に任せる」といった振り分けには使えない
- 汎用的な役割（コードレビュー）は自作をやめ、公式の
/code-reviewに寄せた。プロジェクト固有の観点は CLAUDE.md に書けば、サブエージェントにも届く -
/code-reviewをサブエージェント経由で呼んで、メインのコンテキストを守っていた。今の/code-reviewは最初から別コンテキストで動くので、この工夫は公式に取り込まれた形になった
前提
| 項目 | 内容 |
|---|---|
| 構成 | Next.js / Supabase / Vercel の個人開発（2026年6月〜） |
| サブエージェント |
feature-dev（実装）、qa-tester（バグ探索・テスト補強）、docs-auditor（ドキュメントと実装のずれの検出） |
| 公式のスキル |
/code-review、/security-review
|
| 見直した日 | 2026-08-24 |
サブエージェントは「Claude が判断して」呼ぶもの
公式ドキュメントでは、自動委譲の仕組みが次のように説明されています。
Claude automatically delegates tasks based on the task description in your request, the
descriptionfield in subagent configurations, and current context.
つまり、委譲するかどうかは、その場の Claude が依頼の内容と description を照らし合わせて決めます。
「必ずこのエージェントを起動する」というスイッチがあるわけではありません。
hook で強制できないか
「自動で何かを起動する」と聞くと、hook が思い浮かびます。「実装が終わったら、必ずレビュー用のサブエージェントを起動する」ようにできないでしょうか。
公式ドキュメントを見ると、hook には type: "agent" という種類があります。
- hook のイベントでサブエージェントを起動し、ファイルを読んで条件を確かめさせる
- 結果は
{ "ok": true }か{ "ok": false, "reason": "..." }で返す - 実験的な機能で、本番の運用には command hook を勧めると書かれている
これは「条件を満たしているか」を判定するためのサブエージェントです。
「この作業は feature-dev に任せる」のように、仕事そのものを自作のサブエージェントに振り分ける仕組みではありません。
そこで、自動委譲は hook ではなく、次の2つで実現することにしました。
手段1：description に「どんな依頼で使うか」を書く
公式ドキュメントでは、積極的に委譲させたいときは description に "use proactively" のような言葉を入れるよう勧めています。
筆者は、ユーザーが実際に言いそうな依頼の言葉を書き足しました。
---
name: qa-tester
-description: 品質保証エージェント。バグ探索・テストの空白補強・エッジケース検証を行う。コードの新機能実装はせず、修正とテスト追加に専念する。
+description: 品質保証エージェント。バグ探索・テストの空白補強・エッジケース検証を行う。コードの新機能実装はせず、修正とテスト追加に専念する。「バグがないか調べて」「テストのカバレッジを上げて」「エッジケースを確認して」等の依頼で使う。
tools: Read, Edit, Write, Bash, Glob, Grep
model: sonnet
---
---
name: feature-dev
-description: バックログ項目を1件、設計→実装→テスト→ドキュメント更新→コミットまでエンドツーエンドで完了させる開発エージェント。並列で複数項目を進めるときは worktree 分離で起動する。
+description: バックログ項目を1件、設計→実装→テスト→ドキュメント更新→コミットまでエンドツーエンドで完了させる開発エージェント。並列で複数項目を進めるときは worktree 分離で起動する。BACKLOG.md の項目着手・新機能追加・不具合修正の実装を頼まれたら使う。実装完了後は /code-review に必ず引き継ぐ。
tools: Read, Edit, Write, Bash, Glob, Grep
model: inherit
---
「何ができるか」だけでなく、「どんな依頼のときに使うか」まで書くのがポイントです。
サブエージェントの description は、合計で 15,000 トークンを超えると起動時に警告が出ます（公式ドキュメント）。トリガーの例は、よく使う言い回しに絞ってください。
手段2：CLAUDE.md に「委譲の表」を書く
description だけでは、委譲するかどうかは Claude の判断次第です。
そこで、CLAUDE.md に**「この状況では、確認を取らずに委譲する」**という表を書きました。
## Subagent 運用（自動委譲）
`.claude/agents/` に専任サブエージェントがいる。該当する状況では、ユーザーに確認を取らず**自動的に**委譲する（いずれも読み取り主体・push はしない前提のため）。
| 状況 | 委譲先 |
|------|--------|
| BACKLOG.md の項目着手・新機能追加・不具合修正の実装 | `feature-dev`（Agent ツール） |
| `feature-dev`（または自分）の実装完了後・コミット/push 前 | `/code-review`（必須） |
| 上記のうち認証・RLS・migration・環境変数・CSP等セキュリティに関わる変更を含む場合 | 上記に加えて `/security-review`（必須） |
| バグ探索・テストの空白補強・エッジケース検証 | `qa-tester`（Agent ツール） |
| docs/ と実装の乖離チェック・ドキュメント整合性確認 | `docs-auditor`（Agent ツール） |
- `feature-dev` → `/code-review`（→該当時は `/security-review`）は一連の流れとして扱う。実装が終わったら聞かずに実行する。
- 数行の修正や調査だけで完結する依頼にはサブエージェント・スキルを使わず本体で完結させる（大げさにしない）。
- push・コミット自体は各エージェント/スキルの規約どおり指示がない限り行わない。
書くときに気をつけたことは3つです。
- 「確認を取らずに」と明記する。実装からレビューまでを、途中で止まらずに流してほしいためです
- 「なぜ聞かなくてよいか」を添える（読み取り主体・push しない）。理由があると、例外的な場面で AI が判断しやすくなります
- 使わない場面も書く。数行の修正にまでサブエージェントを起動すると、かえって遠回りになるためです
自作のレビュー用エージェントをやめた
見直しの前は、reviewer という自作のサブエージェントでレビューしていました。
---
name: reviewer
description: 検証専任のコードレビューエージェント。feature-dev の実装完了後・push 前に必ず使う。…
tools: Read, Bash, Glob, Grep
model: inherit
---
## レビュー観点（優先順）
1. バグ: 日付境界（タイムゾーン・日マタギ・月末）、null/空配列、オフライン時、…
2. 本番影響: Vercel（UTC）でだけ壊れる箇所、Supabase の 1000行上限・RLS 漏れ
3. 規約: CLAUDE.md / docs の規約、ドキュメント更新漏れ
4. テスト: 重要ロジックにテストが添えられているか
見直しのときに筆者から「/code-review などの公式のコマンドを使わせたほうがいいのでは」と提案し、この自作エージェントは削除しました。
自作 reviewer
|
公式 /code-review
|
|
|---|---|---|
| レビューの深さ | 固定 | effort で変えられる（low〜max、クラウドで動く ultra） |
| 保守 | 書いた時点の知識のまま | 公式が更新し続ける |
| プロジェクト固有の観点 | プロンプトに埋め込み | CLAUDE.md に書く |
プロジェクト固有の観点（日付境界・Supabase の RLS・1000件上限など）は、CLAUDE.md に移しました。
公式ドキュメントによると、カスタムサブエージェントは起動時に CLAUDE.md を読み込みます（組み込みの Explore と Plan は除く）。CLAUDE.md に書いておけば、レビューにも実装にも同じ観点が届きます。
一方で、auto memory はサブエージェントに読み込まれません（公式ドキュメント）。サブエージェントにも守らせたいルールは、auto memory ではなく CLAUDE.md に書く必要があります。詳しくは Claude Code の引き継ぎメモが3か月で110KBに膨らんだので、3層に分けた に書きました。
自作エージェントを残す価値があるのは、公式のツールにない役割だけだと考えています。
筆者の場合は、feature-dev（このプロジェクトの実装の流れ）、qa-tester、docs-auditor の3つを残しました。
/code-review をサブエージェント経由で呼ぶ（当時の工夫）
メインの会話がレビューの過程で埋まる
/code-review を自動で回し始めると、別の問題が出てきました。
レビューのために読んだ差分・grep の結果・テストの出力が、すべてメインの会話のコンテキストに残るのです。
このプロジェクトは1つのセッションが長くなりがちでした。そこで筆者から「レビューはサブエージェント側で実行したほうが、コンテキストを消費しないのでは」と提案しました。
汎用サブエージェントに包んで呼ぶ
新しいエージェントを作る必要はありませんでした。
組み込みの general-purpose サブエージェントに、/code-review の実行を丸ごと頼みます。
- `/code-review`・`/security-review` は本体で直接 Skill ツールを叩かず、`Agent(subagent_type: "general-purpose")` 経由で呼ぶ（effort: medium）。
diffの読み込み・grep・lint/test実行などの探索コストを本体のコンテキストに持ち込まず、サブエージェント側に閉じ込めて指摘事項の要約だけを持ち帰るため。
プロンプト例:「変更差分に対して /code-review を effort:medium で実行し、指摘事項を200字程度で要約して報告して」。
`ultra` は元々クラウドで分離実行されるので、この工夫は不要（直接呼んでよい）。
公式ドキュメントでも、サブエージェントは「調べた結果やログでメインの会話があふれるとき」に使うものと説明されています。サブエージェントは独立したコンテキストで作業し、要約だけを返します。
今は /code-review 自体がそうなっている
この記事を書くために公式ドキュメントを確認したところ、次のように書かれていました。
-
/code-reviewは、独自のコンテキストを持つバックグラウンドのサブエージェントとして動く。会話を埋めず、終わったら結果が届く -
/code-reviewが forked subagent で動くのは v2.1.218 から。それより前は会話の中で直接（inline で）動いていた
つまり、筆者が CLAUDE.md で工夫していたことは、今は /code-review が最初からやってくれます。
新しいバージョンでは、general-purpose で包む必要はありません。
考え方そのものは、今も使えます。
-
自作のスキルが重い探索をするなら、frontmatter に
context: forkを書くと、サブエージェントの中で動かせます - 逆に、ユーザーと相談しながら進める作業は、サブエージェント越しにすると往復が増えるので、メインの会話のままにします
運用してみて
見直し以降、BACKLOG.md の完了記録で /code-review に触れている作業は10件ありました。
指摘で見つかったものの例です。
| 作業 | 指摘 |
|---|---|
| 2段階認証（MFA）の実装 | RLS で aal2 を強制するテーブルから、1つ漏れていた（マージ不可級） |
| データ取得の見直し | 画面を開いたあとに別の端末で作られた種類の記録が、黙って欠ける |
| 期間を絞った取得への変更 | 取得に失敗したときに、途中までのデータを「取得済み」扱いにしていた |
一方で、/code-review と /security-review を通ったあとに、本番障害を起こしたこともあります。
RLS 用の関数に security definer が抜けていて、全ユーザーの書き込みが止まりました。差分を読むだけでは分からない「本番の権限」の問題で、見つけたのは本番相手の E2E テストでした。
→ Supabase で2段階認証（TOTP）を入れたら本番の書き込みが全部止まった
レビューは自動化できても、本番相当の環境での確認は別に必要だと実感しました。
ハマったポイント・注意事項
/simplify は自動の流れに入れない
/simplify は、見つけた改善点をそのままコードに反映します。
自動の流れに入れると、頼んでいない書き換えが混ざります。CLAUDE.md には「明示的に頼まれたときだけ使う」と書きました。
機械的な作業は軽いモデルで動かす
qa-tester と docs-auditor は、frontmatter で model: sonnet にしています。
テストの補強やドキュメントの突き合わせは、軽いモデルでも十分な品質が出ると判断したためです。実装担当の feature-dev は、品質に直結するので inherit（メインと同じモデル）のままです。
サブエージェントには会話の流れが届かない
カスタムサブエージェントは、メインの会話の履歴を見ていません。公式ドキュメントでは、Claude が書く委譲メッセージだけを頼りに作業すると説明されています。
CLAUDE.md にない前提（「この画面は今日ユーザーと決めた仕様で」など）は、委譲のときに伝わるとは限りません。大事な前提は、CLAUDE.md かタスクの指示に書きます。
まとめ
- サブエージェントへの委譲は、Claude が
descriptionと依頼内容から判断する。どんな依頼で使うかをdescriptionに書く - 確実に振らせたい流れは、CLAUDE.md に「確認せずに委譲する」表として書く。使わない場面も書く
- hook の agent タイプは判定用（実験的）。仕事の振り分けには使えない
- 汎用的な役割は公式（
/code-review）に寄せ、プロジェクト固有の観点は CLAUDE.md に書く - 重い処理はサブエージェント側で動かしてメインのコンテキストを守る。
/code-reviewは今は最初からそう動く。自作スキルならcontext: fork
関連記事:
- Claude Code の完了通知がサブエージェントのせいで何度も鳴るので、全部終わったときだけ鳴らす
- Claude Code のメモリを理解する — CLAUDE.md vs auto memory
- Claude Codeの/loopで「要件定義→テスト→デプロイ」を半日自走させて分かった運用ノウハウまとめ