Claude Code を使い込んでいくと、ひとつの会話の中で「コードを書く」「レビューする」「日本語を校正する」「外部仕様を調べる」といった性質の異なる作業が混ざってきます。これらを全部メインの会話で処理すると、コンテキストが膨らみ、指示も曖昧になりがちです。そこで効くのが subagent (サブエージェント) です。

この記事では、FIXIT が実プロジェクトで運用している subagent の設計方針と、実際に効果が出た役割分担パターンを紹介します。定義の書き方から、コンテキストとコストを抑える設計、陥りやすいミスまで、一次情報で解説します。

subagent とは — メインの会話を汚さず役割を切り出す仕組み

subagent は、メインの会話とは別のコンテキストを持つ「専任エージェント」を定義し、特定のタスクをそこに委譲する仕組みです。メインのエージェントが「この作業はレビュー担当に任せよう」と判断すると、subagent が独立したコンテキストで処理し、結果だけをメインに返します。

ポイントは、subagent の内部でやり取りした大量の中間情報がメインの会話に流れ込まない、という点です。たとえばコードレビューでは、対象ファイルを何本も読み込み、行ごとに検討した思考の過程が発生します。これをメインの会話で全部やると、その後の作業に必要なコンテキストが中間情報で埋め尽くされてしまいます。subagent に切り出せば、メインに返るのは「指摘事項のリスト」だけになり、会話が汚れません。

役割分担のメリットは、おおむね次の 3 つに整理できます。ひとつは、いま述べたコンテキストの分離。ふたつめは、役割ごとに専用のシステムプロンプトと参照ファイルを与えられること。みっつめは、独立した複数の subagent を並列で走らせて待ち時間を短縮できることです。「人間のチームで専門職に仕事を割り振る」感覚に近いと考えると、設計の勘所がつかみやすくなります。

subagent 定義の書き方と呼び出し方

subagent は、リポジトリ直下の .claude/agents/ か、ユーザー全体で使う ~/.claude/agents/ に Markdown ファイルとして置きます。チームで共有したいものはリポジトリ側、個人用のものはユーザー側に置くのが基本です。

ファイルは frontmatter とシステムプロンプト本文で構成します。最小構成は次のようなイメージです。

---
name: code-reviewer
description: 差分のコードレビューを専任で行う。バグ・設計・命名の観点で指摘する。
tools: Read, Grep, Glob, Bash
---
 
あなたはシニアエンジニアとして、与えられた差分をレビューします。
観点はバグの有無、設計の妥当性、命名とテストの過不足の 3 点に絞ります。
指摘は「ファイル名:行番号 / 重要度 / 内容 / 修正案」の形式で、
重要度の高い順に箇条書きで返してください。問題がなければ「指摘なし」と返します。

description はメインのエージェントが「どんなときにこの subagent を呼ぶか」を判断する材料になります。ここを曖昧に書くと、呼んでほしい場面で呼ばれなかったり、逆に余計な場面で呼ばれたりします。tools で渡すツールを絞ると、レビュー専任なのにファイルを書き換えてしまう、といった事故を構造的に防げます。レビュー担当には書き込み系のツールを渡さない、という設計が効きます。

呼び出し方は二通りあります。ひとつは、メインのエージェントが description を見て自動的に委譲する形。もうひとつは、人間が「code-reviewer subagent で差分を見て」と明示的に指名する形です。確実に走らせたいときは指名、普段の流れに任せたいときは自動委譲、と使い分けます。システムプロンプトは過不足なく書くのがコツで、長すぎるとそれ自体がコンテキストを食い、判断もぶれます。役割と出力形式を端的に書くのが結果的に安定します。

実用パターン 1: コードレビュー専任エージェント

最初に効果を実感しやすいのが、レビュー専任の subagent です。実装を書いたエージェントと同じコンテキストでセルフレビューをさせると、自分の書いたコードに引っ張られて「問題なし」に寄りがちです。新しいコンテキストを持つ別エージェントにレビューさせると、第三者の視点に近い指摘が出やすくなります。

設計の勘所は、観点を絞ることです。「全部見て」と頼むと指摘が散漫になります。バグ、設計、命名とテスト、といった具合に観点を 3 つ程度に固定し、出力形式も「重要度つきの箇条書き」と決めておくと、メインのエージェントが受け取った後に修正へつなげやすくなります。さらに、レビュー担当には Read 系のツールだけを渡し、書き込みを禁止しておくと、レビューと修正の責任が混ざりません。指摘を受けてどう直すかはメインのエージェントが判断する、という分業が成立します。

実用パターン 2: 日本語校正・文体チェック (japanese-editor)

FIXIT のメディアやドキュメントは、表記ゆれや AI 文体を防ぐために textlint と prh による校正パイプラインを敷いています。その人間的な判断部分を担うのが japanese-editor という校正専任の subagent です。

この subagent には、社内の文体ガイドと表記ルール (たとえば「AI 駆動開発」「Claude Code」のスペース表記、「リプレイス」「税抜」といった用語) をシステムプロンプトで参照させ、原稿に対して表記ゆれ・冗長表現・不自然な機械翻訳調の言い回しを指摘させます。textlint が機械的に拾えるルールはツール側に任せ、subagent には「読み手に伝わるか」「文体が記事のトーンに合っているか」といった、ルール化しづらい部分を任せるのがすみ分けの肝です。

校正を専任エージェントに切り出す利点は、執筆エージェントとは独立した目で原稿を読める点にあります。書いた本人 (本人エージェント) は自分の文章を肯定しがちですが、校正だけを役割とするエージェントは遠慮なく直しを入れます。出力は「指摘箇所と修正案の対」に固定しておくと、執筆側がそのまま反映しやすくなります。校正パイプラインの自動化そのものは Claude Code の hooks で品質を底上げする実用パターン と組み合わせると、commit 前の textlint と subagent による校正レビューを二段構えにできます。

実用パターン 3: 調査・リサーチの並列化

外部ライブラリの仕様調査、複数候補の比較、既存コードベースの横断的な調べものは、subagent の並列実行が効く領域です。たとえば「3 つのライブラリ候補をそれぞれ調べて比較したい」というとき、調査担当の subagent を 3 つ並列で走らせ、各自が独立したコンテキストで深掘りし、結果のサマリだけをメインに返す、という構成が組めます。

並列化のメリットは待ち時間の短縮だけではありません。それぞれの subagent が大量のドキュメントやソースを読み込んでも、その中間情報はメインの会話に流れ込まないため、最終的に手元に残るのは比較に必要な要約だけになります。メインのエージェントは、その要約を突き合わせて意思決定に集中できます。

調査系 subagent を設計するときは、出力の粒度をそろえることが重要です。「結論」「根拠 (出典やコード箇所)」「注意点」といった項目を決めておくと、複数の subagent から返ってきたサマリを横並びで比較しやすくなります。粒度がばらつくと、せっかく並列で集めた情報を人間が再整理する羽目になり、効果が薄れます。

コンテキストとコストへの影響を抑える設計

subagent は便利ですが、無計画に使うとコストが膨らみます。subagent はそれぞれ独立したコンテキストを持つため、起動のたびにシステムプロンプトと与えた情報が読み込まれ、トークンを消費します。設計で意識したいのは次の点です。

まず、subagent に渡す入力を絞ること。「リポジトリ全体を見て」ではなく、対象の差分やファイル群を明示して渡すと、無駄な読み込みが減ります。次に、返ってくる出力を要約に寄せること。中間の思考過程をそのまま返させるのではなく、結論と根拠だけを定型で返させると、メインのコンテキストへの流入が最小限になります。

軽い作業まで何でも subagent にするのは逆効果です。数行の確認や単純な置換は、メインの会話でそのまま処理したほうが、起動コストを払わずに済みます。「コンテキストを分離する価値があるか」「並列化で時間を稼げるか」を判断基準にし、価値が出る作業だけを切り出すのが、コストと効果のバランスを取る勘所です。CLAUDE.md の整備とも関係が深く、プロジェクト共通の前提は CLAUDE.md に書くべき項目 側にまとめておくと、各 subagent のシステムプロンプトを薄く保てます。

カスタムコマンド・hooks との組み合わせ

subagent は単体でも使えますが、カスタムコマンドや hooks と組み合わせると、定型ワークフローとして固定化できます。

たとえば「PR を出す前にレビュー subagent を走らせる」という流れは、カスタムコマンドにまとめておくと、毎回同じ手順を再現できます。コマンド側に「差分を取得し、code-reviewer subagent に渡し、指摘を反映する」という一連のステップを書いておけば、人間は一語打つだけで定型レビューが走ります。カスタムコマンドの作り方は Claude Code のカスタムコマンド で扱っていますが、subagent との相性は非常によいです。

hooks との組み合わせも有効です。commit 前に textlint を走らせる hook と、japanese-editor subagent による校正を二段構えにすると、機械的なルール違反は hook で止め、文体や読みやすさは subagent が見る、という役割分担が成立します。機械にできることは機械に、判断が要ることは subagent に、という線引きを最初に決めておくと、ワークフロー全体がすっきりします。

導入の勘所と陥りやすい設計ミス

最後に、実際に運用して見えてきた陥りやすいミスを挙げておきます。

ひとつめは、subagent を作りすぎることです。役割を細かく分けすぎると、メインのエージェントが「どれを呼ぶべきか」を毎回判断しきれず、かえって挙動が不安定になります。まずはレビュー・校正・調査といった効果の大きい数個から始め、必要になったら増やすのが安全です。

ふたつめは、description が曖昧で呼ばれない、あるいは過剰に呼ばれることです。description は「どんな入力が来たときに、何をする subagent か」を具体的に書くと、自動委譲の精度が上がります。期待どおりに呼ばれないときは、まず description を疑うのが近道です。

みっつめは、出力形式を決めずに使うことです。subagent の返り値が毎回ばらつくと、メインのエージェントがそれを解釈する手間が増え、せっかく分離したコンテキストの利点が薄れます。出力のフォーマットをシステムプロンプトで固定しておくのが、地味ですが効果の大きい設計です。

そして、ツール権限を絞ることを忘れないでください。レビュー専任に書き込み権限を渡したままだと、指摘ついでにコードを書き換えてしまう事故が起きます。役割に必要なツールだけを tools に列挙する、という小さな手間が、運用の安定に直結します。

subagent は、Claude Code を「ひとりの万能エージェント」から「役割を持ったチーム」へと進化させる仕組みです。コードレビュー、日本語校正、並列リサーチといった効果の大きいところから切り出し、コンテキストとコストを意識しながら育てていくと、AI 駆動開発の品質と速度が両立しやすくなります。

FIXIT では、こうした subagent の設計や校正パイプラインを実プロジェクトで運用しています。AI 駆動開発の進め方やチーム導入について相談したい方は、お問い合わせ からお気軽にご連絡ください。