設計
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 の使いどころ、状況別のモデル選択
4 つの代表的な agent テンプレト（レビュー / セキュリティ / デバッグ / テスト作成）
subagent を雑に使っていて、本当に効果が出ているのかわからない人
全部メイン Claude でやっていて、長いセッションで重さを感じている人
チームで agent を定義したいが、テンプレが思いつかない人
Claude Code の Subagents ドキュメントを一度眺めている
.claude/agents/ に .md ファイルを置けば subagent が認識されることを知っている
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 軽いまま)
これは「人間のジュニアにだいたいの作業を任せ、結果だけ受け取るシニアエンジニア」の関係に似ています。
.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 が使えるツール。明示したものだけ使え、それ以外は使えません。「独走リスクをコードの側で抑える」ためのフィールドで、こちらも重要です。
一番誘惑に負けるのは 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」 という言い回しを入れると、ユーザーから明示的に頃まれなくても「そろそろこの agent を呼ぶといいタイミング」で Claude が自発的に使うようになります。
逆に、「明示的に言われたときだけ使ってほしい」 agent にはこの言い回しを入れません。security-reviewer は重いので明示起動に限定してもよい、という選択もあります。
ユーザーは一つのコンセプトを 1 語で言わないことが多いので、description には「review」「second opinion」「is this safe to merge」 のように 言い換えを 3 つ以上 記しましょう。ストック評価で「どれか 1 つでもマッチさせる」設計です。
tools フィールドは、agent に「そもそもやらせない」ことを仕様として明示します。
| agent | tools | 意図 |
|---|---|---|
| code-reviewer | Read, Grep, Glob, Bash | 読んで評言だけ。Write/Edit は渡さない — 「レビュー中に修正してしまう」を防ぐ |
| security-reviewer | Read, Grep, Glob, Bash | code-reviewer と同様。読み取り専門 |
| pipeline-debugger | Read, Grep, Glob, Bash | docker compose / curl / ls が走れればよい。Write は不要 |
| test-writer | Read, Write, Edit, Grep, Glob, Bash | 唯一 Write/Edit を渡す。テストファイルを作るのが仕事 |
レビュー系に Write を渡してしまうと、「ここの null チェックは足りない」と見つけて勝手に修正を始めることがあります。人間のレビュアーも「レビュー中にコミットしない」のがマナーですが、agent にも同じマナーをコードで強制します。
ある程度のサイズのプロジェクトだと、この 4 つはだいたい定番になります。
---
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 に返ってくるサマリが予測可能になります。
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().
「何を見るか」を脅威モデルとして列挙しておくと、チェック漏れが出にくくなります。「一般論を語らせる」よりも「このリポジトリで現実に起きるやつ」を並べるのがコツです。
これは ドメイン特化 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 に明示することです。「このサブシステムにはこういうクセがある」「このバグは既知」というドメイン知識を詰めておけば、デバッグの足が一気に速くなります。
唯一 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 で「やらないこと」を明示するのが重要です。「テストを書くためにプロダクションコードをいじらない」「フレームワークを勝手に追加しない」というガードを言葉で席けます。
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 に投げる、というラインをチームで揃えておくと、チームメンバー間で使い方が広がらなくなります。
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 / スクリプト起動のパターン
