ゼロから育てる Claude Code サブエージェント

現在 Gaji-Labo では、チームがより高いパフォーマンスを発揮して成果を最大化出来るよう、Claude Code をはじめとしたAIエージェントの活用を強く推進しています。AIの有効活用によるアウトプットの品質向上は、Gaji-Labo が事業として提供するスタートアップ支援やプロダクトチーム支援のための強力な駆動力になります。

去る2025年7月に、Claude Code にサブエージェントという機能が新たに追加されました。サブエージェントはメインセッションから分離された子プロセスとして働き、優れた専門性を持たせることができます。その特性から、Claude Code のアウトプットの質を大きく向上させることが期待できます。

この記事では、サブエージェントの作り方、そしてチューニングの方法を実践してみましょう。

サブエージェントとはなにか

Claude Code のサブエージェントは、特定のタスクを専門的に処理するためのエキスパートアシスタントです。

例えば、コードレビューを専門とするサブエージェントが定義されているとしましょう。

Claude Code のメインセッションでコードレビューを依頼すると、 Claude Code が判断してそのサブエージェントに処理を委任します。タスクを委任されたサブエージェントは、メインセッションから独立したコンテキストでタスクを実行して、結果をメインセッションに報告をします。つまり、主流から枝分かれして働く機能ですね。

サブエージェントは次のような特徴を持ちます :

• その処理のエキスパートとして定義されるので、精度の高いアウトプットができる
• 振る舞いや使用ツールなどを独自にカスタマイズできる
• メインセッションのコンテキストを汚染しない
• メインセッションから独立して働くので思考リソースの節約になる

サブエージェントの設定は、カスタムスラッシュコマンドのような他の機能と同様に .claude/agents に markdown 書式で定義されます。振る舞いを自分向けに細かくカスタマイズでき、ファイルをプロジェクトチーム内で共有すれば開発プロセスの再現性を高めることもできます。

サブエージェントはいつ動くか

上で述べているように、Claude Code はメインセッションに投げられたプロンプトを解釈し、必要だと判断したタイミングでサブエージェントを呼び出します。

その際に判断材料にされるのが、サブエージェントの description の内容です。 description に記述された「こういう場面でこのサブエージェントを使いなさい」という指示をもとにして、サブエージェントを適切な場面で使用する仕組みになっています。

しかしご存知のように、AIの再現性というものはそこまで信頼のおけるものではないので、指示に書いてあったとしても使ってほしい場面で必ず使用してくれるわけではありません。期待通りに使用してもらうためにはチューニングが必要になりますが、それについてはまた後述するとします。

サブエージェントをゼロから作成する

それでは早速サブエージェントをゼロから作成してみましょう！

Claude Code にはサブエージェントを管理・作成するための /agents という組み込みスラッシュコマンドが用意されており、はじめはそれを使って作成することが推奨されています。

「Create new agent」> 「Project or Personal」 > 「Generate with Claude (recommend)」
と進むと、「このエージェントがすべきことと、いつ使われるべきか」の入力を促されます。

ここにプロンプトを打ち込むと、Claude Code が良い感じのサブエージェントを自動的に生成してくれます。今回は例として機能開発計画専任のフロントエンドエンジニアになってもらおうと思います。

あなたは既存のフロントエンドアプリケーションに機能を追加するための開発計画を専門に作成するシニアエンジニアです。あなたのゴールは、メインセッションから「新しい機能を実装してほしい」という指示を受け取った際に、既存のコードベースと技術スタックを最大限に活用した、具体的な実装計画を提示することです。

このプロンプトは Gemini に相談して作成してもらったものです。

サブエージェントの役割は出来るだけフォーカスされていた方が、より精度の高いアウトプットを期待できます。プロジェクト初期開発、既存のコードベースに基づいた新規機能開発、バグ修正のサブエージェントは、ひとつのエンジニアサブエージェントとせずに目的別で用意しておくと良いでしょう。

一分程度待機したあとで、使用可能なツールを選択し、使用するモデルを選択すればプロトタイプの完成です。命名も適切なものを考えてくれます。今回は feature-implementation-planner という名前をつけてくれました。

サブエージェントを育てる

はじめのプロトタイプは極めて一般的なサブエージェントとして作られます。そのプロトタイプを、自分のチームやプロジェクトに特化させたものへとチューニングを重ねることで、パフォーマンスやアウトプットの精度が向上していくはずです。

基本として、Claude Code のチューニング（つまりプロンプトの編集）は Claude Code 自身にやってもらいます。本人たちの方が、効果的に働くプロンプトをよく知っているでしょう。

はじめに Claude Code にレビューしてもらう

はじめにやることは、作ったサブエージェントを Claude Code 自身にレビューしてもらうことです。

> @.claude/agents/feature-implementation-planner.md をレビューして改善点をあげてください

このような大雑把な指示であがってくる改善点は、サブエージェントを全方向に改善するアイデアであることが多いです。しかし、サブエージェントに求めるものはジェネラリストではなくスペシャリストです。指向性を持たせて高い性能を発揮させるため、自分がエージェントに求める方向にフォーカスして改善点を絞ると良いです。

今回はこのように指示してみます。

> 必要な改善案にしぼりたいので、その判断のために必要な情報を一問一答形式で質問して整理してください。

こうして指向性を持った改善案を適用させることで、目的がフォーカスされたシャープなサブエージェントに磨き上がるはずです。

コードベースをもとにした開発計画を徹底させる

サブエージェントにみられる挙動のひとつとして、時折既存のコードベースを無視して自分の想像する構成をもとに計画を進めてしまうことがあります。コードベースを無視した開発計画は役に立ちません。この指示は100%遵守してほしいので、改善をお願いしてみましょう。

> @.claude/agents/feature-implementation-planner.md このサブエージェントが計画を立てる際に、最高優先度で既存コードベースに基づいて考えるような改善案を提案してください。

この指示に対して Claude Code は、既存コードベースの分析を「最優先タスク」としてマークし、分析に「最低10分費やす」といった明確な基準を示してくれました。しかし大小様々なタスクがあるなかで毎回杓子定規に10分費やすのはナンセンスで、スピード感を損なうおそれがあるので、もう少し柔軟な設定をお願いしました。

> 常に分析に10分費やすのではなく、タスクの難易度や規模によって分析時間を調整してください。

Claude Code はタスクの複雑度に応じた推奨時間を設定してくれました。

  - タスクの複雑度に応じた推奨時間：
    - 簡単なタスク：3-5分
    - 標準的なタスク：5-10分
    - 複雑なタスク：10-15分

期待に反する挙動を抑える

上で述べたコードベースの例のように、サブエージェントがこちらの期待に反した動きを見せることは実によくあることです。そんな時、その場でエージェントを責めたり詰めたりするのはナンセンスです。次の新しいセッションではそんなことは綺麗さっぱり忘れられてしまうからです。

二度とその行動をしてほしくないならば、プロンプトにどのように追記すればそれをしなくなるのか、アイデアを提示させてサブエージェント自体を改善することが建設的です。

> 〇〇をさせないためにサブエージェントにどのように記述すれば良いか、改善案を提案してください。この改善点は最優先で遵守するようにしてください。

残念なことに、明示的に指示してあったとしてもエージェントはうっかり同じ失敗をします。しかし、「最優先」、「必須」のような強い表現で記述されていれば、少なくとも発生頻度は激減するはずです。サブエージェントに改善をお願いする時に強い表現を使ってもらえるように、優先度を明確に伝えておくのは良いプラクティスだと思います。

「サブエージェントがおかしな動きをする」という発見は、実は改善のチャンスです。（ニンゲンのワークフローがそうであるように！）改善ポイントを発見するためにも、運用試験を兼ねて手頃なタスクを実際にまわしてみると良いでしょう。

適切なタイミングで使われるようにする

サブエージェントを作ったはいいが、使ってほしいタイミングで使ってもらえないということも、とてもよくあることです。多くの場合、これはサブエージェントが「いつ使われるべきものなのか」をうまくアピールできていないからなので、使われるべき場面を強い表現で定義しておきます。

> @.claude/agents/feature-implementation-planner.md を適切なタイミングで使用させるための改善案を提案してください

この改善案を適用させると、 use PROACTIVELY や MUST BE USED といったとても強力なキーワードを description に盛り込んでくれます。これによりエージェントは、このサブエージェントを使うべきタイミングを理解することができ、適切にサブエージェントにタスクを渡すことができるようになるのです。

しかしエージェントは気まぐれなので、これでも必ず使ってくれるようにはなりません。より確実にサブエージェントを使ってもらうために指名するという方法もあります。

例えばこのように :

> feature-implementation-planner エージェントを使用して https://xxxxx に記載された機能の実装計画を立ててください

毎回この長いプロンプトを打ち込むのは面倒なので、サブエージェントを指名して使ってくれるカスタムスラッシュコマンドを作っておくと便利です。 /plan-feature コマンドとして、 Claude Code に作ってもらいましょう。

> feature-implementation-planner エージェントを使って機能開発の計画を立てるカスタムスラッシュコマンドを plan-feature という名前で作成してください。

こんな感じのものを出力してくれます :

---
name: plan-feature
description: フロントエンド機能の実装計画を作成する
---

機能実装の詳細な計画を作成するため、feature-implementation-plannerエージェントを起動します。

このエージェントは以下を行います：
1. 既存コードベースの分析（最大5分）
2. 段階的な実装計画の作成（MVP → 本実装 → 最適化）
3. 具体的なコードスニペット付きタスクの提供
4. 既存コンポーネントとパターンの再利用を優先

（後略）

このカスタムスラッシュコマンドも Claude Code 自身にレビューをさせて改善すれば、さらに精度を高められるでしょう。

おわりに

サブエージェントは、プロジェクトのワークフローを細かく分解したタスクを任せられる専任のエージェントです。

エキスパートとして精度の高いアウトプットを出しつつも、司令塔であるメインセッションとはコンテキストを別としているため、お互いに邪魔をせず、高品質な成果を生み出します。それはまるで、 Claude Code の中でひとつのチームが形成されているかのようです。ニンゲンはそのAIチームを制御することで、自分ひとりでは実現できないような非常に高いパフォーマンスを発揮できるようになるでしょう。

AIが高度になるにつれ、ニンゲンが活躍するレイヤーが少しずつシフトしつつあることを強く実感させられます。サブエージェントという機能は、その流れを支える基礎になるものなのではないでしょうか。

Gaji-Labo フロントエンドエンジニア向けご案内資料