【設計】Claude Code の specialized agent をどう切り分けるか — メイン context を汚さない subagent 設計（連載 第3回）

概要: 連載第1回で「.claude/ の上層は拡張層」と言い、第2回でガード層の hook を掘り下げました。本記事では拡張層の中で一番面白い subagent に踏み込みます。code-reviewer / security-reviewer / pipeline-debugger / test-writer の 4 つを例に、frontmatter をどう書けば「いつ呼ばれるか」をコントロールできるか、tools と model: inherit の使いどころ、そしてメイン Claude の context window を汚さない運用のコツを整理します。

はじめに#

Claude Code を使い込んでくると、どこかで「メインのセッションが重たくなってきた」と感じるタイミングが来ます。原因の多くはこれです。

• デバッグのために 10 ファイル読んだメイン Claude の context に、そのデバッグログがそのまま乗っている
• PR レビューのために git diff を読み、周辺コードも読み、その所見も context に乗り、以降の作業が重い
• テストを書くために既存コードを読み込んだが、本題は「テストを書く」だけだった

Claude Code の subagent は、この「作業用のスクラッチスペース」をメインから切り離す仕組みです。独立した context window を持つサブセッションとして走り、最終的にサマリだけをメインに返すため、メインの context は「レビューした」「デバッグした」という事実と結論だけを受け取ります。

本記事では、実運用している 4 つの subagent を題材に、どう切り分けて、どう frontmatter を書くかを整理します。

この記事でわかること#

• subagent を使うと何が起きるのか（独立 context / サマリだけ返る）
• subagent の frontmatter の構造と、各フィールドの意味
• description の書き方が「いつ自動で呼ばれるか」をどう決めるか
• tools を絞る設計と、独走リスクをコードの側で抑える考え方
• model: inherit の使いどころ、状況別のモデル選択

1. なぜ subagent か — context window と 「作業用スクラッチスペース」#

Claude Code のメインセッションは、会話全体が 1 つの context window に詰まっています。ところが次のような「一時的に重い作業」がしばしば出てきます。

• レビュー: git diff を読み、周辺 30 行を読み、判断し、所見を返す
• デバッグ: 複数のサービスのログを読み、stack trace をたどり、原因を特定する
• セキュリティスキャン: 見逃したくないパターンを diff 全体に grep し、該当ファイルを読む

これをメインでやると、作業中に使った中間データが context にそのまま残り、以降の作業を重い状態のまま進めることになります。「さっきレビューをさせたら、そのあとの作業が鉱くなった」という体験は、このスクラッチスペース汚染が原因です。

subagent はこの課題に対して、独立した context window を持つサブセッションとして走り、作業結果のサマリだけをメインに返す、というモデルを提供します。

メイン Claude (context 軽い)
    │
    │  「この PR をレビューして」
    ▼
+-------------------+
| subagent          |
| code-reviewer     |  <- diff 読む・コード読む・判断する
| (独立 context)   |
+-------------------+
    │
    │  「must-fix 3 件、nit 5 件。マージ可。」
    ▼
メイン Claude (context 軽いまま)

これは「人間のジュニアにだいたいの作業を任せ、結果だけ受け取るシニアエンジニア」の関係に似ています。

2. subagent の frontmatter — 4 フィールドだけ押さえる#

.claude/agents/foo.md は Markdown ファイルで、先頭に YAML frontmatter、以下がシステムプロンプトという構造です。

---
name: code-reviewer
description: Pre-PR code reviewer for this monorepo. Use proactively after a meaningful set of edits, before opening a PR, or when the user asks for a "review", "second opinion", or "is this safe to merge".
model: inherit
tools: Read, Grep, Glob, Bash
---

You are an experienced reviewer for this monorepo. You read the diff, then the surrounding code, then form an opinion.

## Scope of every review
...

押さえるフィールドは 4 つだけです。

name: agent 名。ファイル名と揃えると以降の参照が迷わなくなります。

description: メイン Claude が「いま subagent に投げるべきか」を判断するためのトリガー文。これが subagent 設計の中核です。詳しくは次節。

model: inherit: モデル選択。inherit にしておくとメイン Claude と同じモデルが使われます。sonnet / haiku と明示してコストを下げる選択もありますが、そこは状況依存で、「何も考えず inherit」が無難なデフォルトです。

tools: この subagent が使えるツール。明示したものだけ使え、それ以外は使えません。「独走リスクをコードの側で抑える」ためのフィールドで、こちらも重要です。

3. description をどう書くか — 「いつ呼ぶか」を具体的に#

一番誘惑に負けるのは description を「この agent は何をやるか」だけ書いてしまうことです。それだとメイン Claude は「何をやるかはわかったが、今呼ぶべきかはわからない」状態になり、使われません。

よい description には 2 つの要素を入れます。

[何をやる agent か] + [いつ呼ぶべきかの具体例]

例えば code-reviewer の description はこうです。

description: Pre-PR code reviewer for this monorepo. Use proactively after a meaningful set of edits, before opening a PR, or when the user asks for a "review", "second opinion", or "is this safe to merge".

分解するとこうです。

• 何をやる: 「Pre-PR code reviewer for this monorepo」
• いつ呼ぶべきか: 「意味のある編集の一区切りの後」「PR を開く前」「ユーザーが review / second opinion / is this safe to merge と言ったとき」

この「ユーザーがこういう言葉を使ったとき」というトリガーワードを明示するのが重要です。メイン Claude はユーザーの言い回しから description をマッチングして「この agent を呼ぶべき」と判断します。

「use proactively」 を付けると自動起動しやすい#

「use proactively」 という言い回しを入れると、ユーザーから明示的に頼まれなくても「そろそろこの agent を呼ぶといいタイミング」で Claude が自発的に使うようになります。

逆に、「明示的に言われたときだけ使ってほしい」 agent にはこの言い回しを入れません。security-reviewer は重いので明示起動に限定してもよい、という選択もあります。

補足・言い換えを豊かに#

ユーザーは一つのコンセプトを 1 語で言わないことが多いので、description には「review」「second opinion」「is this safe to merge」 のように 言い換えを 3 つ以上 並べましょう。「どれか 1 つでもマッチすれば呼ばれる」という設計です。

4. ツールを絞って「やらせたくない仕事」をコードの側で抑える#

tools フィールドは、agent に「そもそもやらせない」ことを仕様として明示します。

レビュー系に Write を渡してしまうと、「ここの null チェックは足りない」と見つけて勝手に修正を始めることがあります。人間のレビュアーも「レビュー中にコミットしない」のがマナーですが、agent にも同じマナーをコードで強制します。

5. 4 つの代表的な agent テンプレート#

ある程度のサイズのプロジェクトだと、この 4 つはだいたい定番になります。

5.1 code-reviewer — PR 前のレビュー#

---
name: code-reviewer
description: Pre-PR code reviewer for this monorepo. Use proactively after a meaningful set of edits, before opening a PR, or when the user asks for a "review", "second opinion", or "is this safe to merge".
model: inherit
tools: Read, Grep, Glob, Bash
---

You are an experienced reviewer for this monorepo.

## Scope of every review
- Correctness: off-by-one, null/None handling, race conditions, error swallowing.
- Stack rules: framework conventions and lint config.
- Security: no secrets in code, no SQL string-concat, no user-controlled paths into open().
- Test coverage: new routes should have at least one test.
- Repo hard rules (project-specific).

## Workflow
1. Run `git diff origin/develop...HEAD` to see the change set.
2. For each non-trivial hunk, open the file and read at least 30 lines of context.
3. Group findings by severity (must-fix / should-fix / nit) with file:line citations.
4. End with a one-sentence verdict: ready to merge / needs work / needs another reviewer.

Be direct. Do not pad with praise. If the diff is clean, say so in one sentence.

ポイントは「出力フォーマットを system prompt で規定する」こと。must-fix / should-fix / nit の 3 段階、最後に 1 文の verdict — こういうフォーマットを決めておくと、メイン Claude に返ってくるサマリが予測可能になります。

5.2 security-reviewer — セキュリティ観点だけを見る#

code-reviewer と分けておくメリットは、両者で system prompt が全く違うことです。code-reviewer は「コードの正しさ」を見ますが、security-reviewer は「脅威モデル」を見ます。

---
name: security-reviewer
description: Security-focused reviewer. Invoke before merging anything that touches auth, env handling, file uploads, LLM prompts, terraform, or external API calls — or whenever the user asks for a "security review".
model: inherit
tools: Read, Grep, Glob, Bash
---

You audit changes for security regressions specific to this repo.

## Threat model
- Cloud resource credentials leaking into committed files, logs, or prompts.
- Tenant isolation breaks.
- LLM prompt-injection from user-controlled inputs.
- Path traversal / SSRF in upload pipelines.
- Untrusted file execution.

## What to check on every diff
1. Secrets / env: grep for patterns (AccountKey=, BEGIN RSA, sk-, eyJ).
2. Terraform: reject changes under terraform/dev or terraform/prod unless explicitly requested.
3. API: new routes have authentication. User-supplied paths not used unsanitized in open() or Path().

「何を見るか」を脅威モデルとして列挙しておくと、チェック漏れが出にくくなります。「一般論を語らせる」よりも「このリポジトリで現実に起きるやつ」を並べるのがコツです。

5.3 pipeline-debugger — 特定サブシステムの専門デバッガ#

これは ドメイン特化 agent の代表例です。プロジェクトに「何度もデバッグしている特定サブシステム」（データパイプライン、ジョブキュー、認証基盤など）があるなら、それ専用の agent を立てると効果が高いです。

---
name: pipeline-debugger
description: Specialist in the multi-stage data pipeline. Use when a /run/* call fails, expected blob output is missing, the classifier behaves oddly, or specific module-loading code looks suspicious.
model: inherit
tools: Read, Grep, Glob, Bash
---

You debug the pipelines locally (emulator + docker-compose).

## What you know that other agents don't
- Three pipelines share Python module names so a custom loader swaps sys.path and sys.modules between stages.
- The classifier must remain idempotent and degrade gracefully when the LLM returns malformed JSON.
- Local everything must run against the emulator, not real cloud storage.
- Known bug: move_to_quarantine masks the real error when a default arg is wrong.

## Debug procedure
1. `make ps` to see which services are up.
2. `make logs` — pull the last 200 lines of the failing service.
3. Reproduce by curling the offending endpoint.
4. Trace from the FastAPI handler down.

ポイントは「他の agent が知らないこと」を system prompt に明示することです。「このサブシステムにはこういうクセがある」「このバグは既知」というドメイン知識を詰めておけば、デバッグの足が一気に速くなります。

5.4 test-writer — テストコードの追加だけ#

唯一 Write/Edit を渡す agent です。

---
name: test-writer
description: Writes pytest tests for the API and component tests for the frontend. Use when adding a new route, pipeline function, or frontend component, or when the user says "add tests".
model: inherit
tools: Read, Write, Edit, Grep, Glob, Bash
---

You write minimal, high-signal tests. No over-mocking, no fixtures the production code does not use.

## Conventions
- Tests live under tests/. Mirror the source layout.
- Use the framework's TestClient against the actual app.
- Do not mock the database when an integration path is being tested.
- Read existing nearby tests first to match style.

Write を渡す以上、system prompt で「やらないこと」を明示するのが重要です。「テストを書くためにプロダクションコードをいじらない」「フレームワークを勝手に追加しない」というガードを言葉で明示します。

6. 運用のコツ — subagent をスポイルさせない#

4 つ作ったとしても、運用を間違えるとメリットが出ません。踏みやすい落とし穴を並べておきます。

agent を作りすぎない。agent が 10 個を超えると、メイン Claude は「どの agent を呼ぶべきか」を判断するだけで token を使います。「1 週間使わなかった agent」は削ったほうが全体が軽くなります。

同じ agent を並列で走らせるときは context を現在の状態と揃える。例えば「API と frontend をそれぞれレビュー」したいときに、メインが 2 つの code-reviewer を並列で呼ぶと、より高速に結果が揃います。ただし prompt で scope を明示しないとダブってそれぞれ同じものを見てしまうので、「API 側だけ」「frontend 側だけ」と prompt で切るのがコツです。

「agent のサマリ」をそのまま信じない。subagent が「修正しました」と言ったとき、実際の diff をメインで見るステップを応じて入れます。agent のサマリは「それがやろうとしたこと」を記述するもので、「実際に何をやったか」とは一致しないことがあります。

メインと subagent の使い分けを明示する。「memory の読み書き」や「タスクの計画」はメインの仕事で、「大量ファイル読み込みを伴う調査」や「独立した評価」は subagent に投げる、というラインをチームで揃えておくと、メンバー間で使い方がばらつかなくなります。

Tips#

• description に言い換えを 3 つ以上入れると、ユーザーの言い回しにマッチしやすくなる
• proactively を付けるかは意識的に選ぶ。重い agent（security-reviewer 等）は明示起動限定もあり
• tools は最小で与える。Write/Edit を渡すのは test-writer のように「作るのが仕事」のときだけ
• 出力フォーマットを system prompt で規定して、メインが受け取るサマリを予測可能にする
• agent は「人を雇う」ように設計する。何をしてほしいか、何を NG とするかをジョブ記述レベルで書く
• 使われない agent は削る。agent 一覧自体がメインの context を食うので、一覧を軽めに保つ

まとめ#

• subagent の本質は「独立 context window で走り、サマリだけメインに返す」こと。「スクラッチスペース汚染」からメインを守るという設計思想
• frontmatter は name / description / model / tools の 4 つだけ押さえればよい
• description には「何をやるか」と「いつ呼ぶべきかの具体例」を両方記し、言い換えを 3 つ以上入れる
• tools は「やらせたくないこと」をコードで抑えるガードとして設計する
• code-reviewer / security-reviewer / pipeline-debugger / test-writer は中規模のプロジェクトでの定番テンプレート
• 運用では「作りすぎない」「サマリだけ信じない」「メインと subagent の境界をチームで揃える」の 3 点

次回予告#

連載最終回（第 4 回）は skill と slash command の使い分けに踏み込みます。

• どういう作業を command にし、どういう作業を skill にするかの判断軸
• disable-model-invocation: true の使いどころ — 「明示呼び出し限定」にしたいケース
• allowed-tools の正体（ツール制限ではなく事前承認）と、skill / command の副作用を本当に絞る手段
• argument-hint / スクリプト起動のパターン

参考リンク#

• Claude Code: Subagents
• Claude Code: Settings
• 連載第 1 回: Claude Code Harness 入門
• 連載第 2 回: hook で事故を未然に防ぐ