概要: 連載第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 の使いどころ、状況別のモデル選択
• 4 つの代表的な agent テンプレト（レビュー / セキュリティ / デバッグ / テスト作成）

対象読者

• subagent を雑に使っていて、本当に効果が出ているのかわからない人
• 全部メイン Claude でやっていて、長いセッションで重さを感じている人
• チームで agent を定義したいが、テンプレが思いつかない人