最近、Claude Codeのサブエージェントについて調査＆実験をしたので結果をまとめます。
サブエージェントとは？
サブエージェントは、Claude Codeの中で動く専門化されたAIです。
普段のClaude Codeは「何でも屋」ですが、サブエージェントは特定のタスクだけを担当します。例えば、
- コードレビュー専門のエージェント
- テスト作成専門のエージェント
などが良く例にあがります。
メイン会話との違い
| 項目 | メイン会話 | サブエージェント |
|---|---|---|
| コンテキスト | 共有 | 独立 |
| 役割 | 汎用 | 専門特化 |
| ツール | すべて利用可能 | 制限可能 |
| 並列実行 | 不可 | 可能 |
特に重要なのは「独立したコンテキスト」です。サブエージェントはメイン会話のトークンを消費しないため、長い会話の途中でも効率的にタスクを実行できます。 イメージとしては、サブエージェントはサブルーチンやWeb Workerに似た側面を持っているといえます。
- メインスレッドとはトークン計算が完全に別
- サブエージェントが大量のファイルを読んだり、長いコードを生成しても、メインのコンテキストは消費されない
- メインは指示を出した後、結果のサマリーだけを受け取る
つまり、長い会話の途中でも「コンテキストが足りなくなる」心配なく、タスクを委任できるが魅力です。 また、コンフリクトに気をつければ非同期で複数のサブエージェントを走らせることもできます（10本まで）。
習作「avatar-designer エージェント」
習作としてアバターを作成するサブエージェントを作成してみました。
ファイルの配置場所
.claude/
└── agents/
└── avatar-designer.md 👈 このファイル！
ファイルの中身
--- name: avatar-designer description: シンプルで可愛らしいSVGアバターをReactコンポーネント(.tsx)として作成。出力先は src/renderer/src/components/[Name]Avatar.tsx。アバター量産時に並列で呼び出す。 tools: Read, Write, Glob model: sonnet skills: avatar-design permissionMode: acceptEdits --- あなたはSVGアバター作成の専門家です。OniAvatarと同じテイストで、シンプルで可愛らしいアバターを作成します。 ## 入力形式 依頼時に以下の情報を受け取ります： キャラクター名: [Name] モチーフ: [猫/犬/うさぎ/くま/鬼/etc] カラー: [メインカラー] (オプション) 特徴: [追加の特徴] (オプション) ## 作業手順 1. まず `src/renderer/src/components/OniAvatar.tsx` を読んで参考実装を確認 2. `.claude/skills/avatar-design/SKILL.md` のデザイン原則を確認 3. 指定されたモチーフに基づいてアバターを設計 4. `src/renderer/src/components/[Name]Avatar.tsx` にコンポーネントを作成 ## 品質基準 必ず以下を守ること： ### シンプルさ - 基本図形のみ（ellipse, circle, polygon, path, line） - パーツは5〜8個以内 - 色は3〜5色以内 ### 目のバランス（最重要） - 白目: rx:6〜8, ry:7〜9 - 黒目: rx:3〜4, ry:4〜5 - 黒目サイズ = 白目サイズ × 0.5〜0.6 ### 禁止事項 - 複雑なグラデーション - filter効果の多用 - 写実的な表現
YAMLフロントマターの解説
ファイル冒頭の---で囲まれた部分がYAMLフロントマターです。ここでエージェントの基本設定を行います。
必須フィールド
| フィールド | 説明 | 例 |
|---|---|---|
name |
エージェント名（小文字、数字、ハイフン） | avatar-designer |
description |
何をするエージェントか。Claudeの選択判断に使用される | シンプルで可愛らしいSVGアバターを... |
オプションフィールド
| フィールド | 説明 | 例 |
|---|---|---|
tools |
使用可能なツール | Read, Write, Glob |
model |
使用するモデル | sonnet, opus, haiku |
skills |
自動読み込みするスキル | avatar-design |
permissionMode |
権限モード | acceptEdits |
skillsは効いているのかいないのかわかりませんが、一応書いてます。 多分効いてません。（後述）
各フィールドを深掘り
tools - 使えるツールを制限する
サブエージェントが使えるツールを明示的に指定できます。
tools: Read, Write, Glob
avatar-designerの場合： - Read - 参考実装（OniAvatar.tsx）を読む - Write - 新しいアバターコンポーネントを作成 - Glob - ファイルを検索
Bashを含めていないため、シェルコマンドは実行できません。必要最小限のツールだけ許可することで、安全性が高まります。
利用可能なツール一覧
| ツール | 説明 |
|---|---|
| Read | ファイル読み取り |
| Edit | ファイル編集（部分変更） |
| Write | ファイル作成・上書き |
| Glob | パターンマッチング検索 |
| Grep | コンテンツ検索 |
| Bash | シェルコマンド実行 |
| WebFetch | URL取得 |
| WebSearch | Web検索 |
| Task | 別のサブエージェント呼び出し |
model - 使用するモデルを選ぶ
タスクの複雑さに応じてモデルを選択できます。
| 値 | 説明 | 用途 |
|---|---|---|
haiku |
高速・低コスト | シンプルな検索、探索 |
sonnet |
バランス型 | 日常的なコーディング |
opus |
高精度 | 複雑な推論、分析 |
inherit |
メインと同じ | 品質を揃えたい場合 |
avatar-designerではsonnetを使用しています。SVGの生成は創造的なタスクですが、決められたルールに従う定型作業でもあるため、sonnetで十分です。
skills - スキルを自動読み込み
skills: avatar-design
この設定により、.claude/skills/avatar-design/SKILL.mdが自動的に読み込まれます。
前述の通り、ここは無視されている気がしています。
スキルとは？ デザイン原則やチェックリストなど、詳細な指示を別ファイルにまとめたものです。エージェント定義ファイルを短く保ちつつ、詳細なルールを参照できます。のちに簡単に解説します。
permissionMode - 権限を設定する
permissionMode: acceptEdits
| モード | 説明 |
|---|---|
default |
通常の権限確認あり |
plan |
読み取り専用 |
acceptEdits |
編集を自動承認 |
bypassPermissions |
すべての権限をバイパス |
avatar-designerはacceptEditsを設定しています。アバターファイルの作成時に毎回確認を求められると面倒なため、編集操作を自動承認しています。
本文（プロンプト）の書き方
YAMLフロントマターの後が、エージェントへの指示本文です。
良いプロンプトの構成
## 役割の定義 あなたはSVGアバター作成の専門家です。 ## 入力形式 どんな情報を受け取るか ## 作業手順 1. 何をする 2. 何をする 3. 何をする ## 品質基準 守るべきルール ## 禁止事項 やってはいけないこと ## 出力形式 完了時に何を報告するか
ポイント
具体的な数値を入れる
- 「シンプルに」ではなく「パーツは5〜8個以内」
- 「バランスよく」ではなく「黒目サイズ = 白目サイズ × 0.5〜0.6」
参照先を明示する
- 「参考実装を見て」ではなく「
src/renderer/src/components/OniAvatar.tsxを読んで」
- 「参考実装を見て」ではなく「
禁止事項を明記する
- AIは「やっていいこと」より「やってはいけないこと」を明示した方が従いやすい
スキル（skills）との連携
これまで、スキルの説明を後回しにしてきましたが、エージェントスキルという機能です。
avatar-designerエージェントには skills: avatar-design という設定があります。（無視されている気がします）
さらに作業手順の中に、「.claude/skills/avatar-design/SKILL.md のデザイン原則を確認」と書いてあるので、さすがに.claude/skills/avatar-design/SKILL.md を読み込んでいると信じています。（作業終了後にClaudeCodeに確認すると、読み込んでますと言ってます）
スキルとは？
スキルは詳細なルールやガイドラインを別ファイルにまとめたものです。
エージェント定義ファイル（.md）に全部書くと長くなりすぎるため、詳細は別ファイルに分離します。
.claude/
├── agents/
│ └── avatar-designer.md 👈 エージェント定義
└── skills/
└── avatar-design/
└── SKILL.md 👈 詳細なデザインルール
スキルを直接呼び出すこともできるのですが、トークン消費量を分けたかったのでサブエージェント経由で呼んでいます。 また、前述の通り並列に呼び出せるようになるので、複数のアバターを10体まで一気に作成できるようになるのも大きな利点です。
avatar-design スキルの中身
実際のSKILL.mdを見てみましょう。
--- name: avatar-design description: シンプルで可愛らしいSVGアバター/アイコンを作成。「アバター作って」「アイコン作って」「キャラ作って」などで発動。 --- シンプルで可愛らしい、再現性のあるSVGアバターを作成する。 ## 技術仕様 - **形式**: インラインSVG（React/TSXコンポーネント） - **viewBox**: `0 0 100 100`（正方形、計算しやすい） - **サイズ対応**: props で small/medium/large を受け付ける ## デザイン原則 ### 1. シンプルさ | 要素 | ルール | |------|--------| | **図形** | 基本図形のみ使用（ellipse, circle, polygon, path, line） | | **パーツ数** | 顔のパーツは5〜8個以内 | | **色数** | 3〜5色以内 | ### 2. 目の設計（最重要） 目はキャラクターの印象を決める最重要パーツ。 **推奨比率**: - 白目 rx:6〜8, ry:7〜9 - 黒目 rx:3〜4, ry:4〜5 - 黒目サイズ = 白目サイズ × 0.5〜0.6 ### 3. カラーパレット // 暖色系キャラ（鬼、狐など） const warm = { main: '#e74c3c', // 赤 mainDark: '#c0392b', // 濃い赤 accent: '#2c3e50', // 濃いグレー } // ナチュラル系（くま、犬など） const natural = { main: '#d4a574', // ベージュブラウン mainDark: '#b8956e', } ## 禁止事項 - 複雑なグラデーション - filter効果の多用 - 写実的な表現 - パス座標の小数点以下2桁以上
こんな感じです。
--
サブエージェントの使い方
方法1: 自動選択（推奨）
リクエスト内容に応じて、Claudeが自動的にエージェントを選択します。
猫のアバターを作って
→ Claudeがdescriptionを見て「avatar-designerを使いますか？」と提案
方法2: 明示的に指定
avatar-designer エージェントで猫のアバターを作って
まとめ
| 項目 | 内容 |
|---|---|
| 配置場所 | .claude/agents/エージェント名.md |
| ファイル形式 | Markdown + YAMLフロントマター |
| 必須フィールド | name, description |
| オプション | tools, model, skills, permissionMode |
| 呼び出し方 | 自動選択 or 明示的に指定 |
| 並列実行 | 可能 |
サブエージェントが向いているケース
- 同じタスクを繰り返し実行する
- 特定のルールに従った出力が必要
- メイン会話のコンテキストを節約したい
- 並列で複数タスクを実行したい
サブエージェントが向いていないケース
- 1回限りの単発タスク
- 文脈依存の判断が多いタスク
- メイン会話との密な連携が必要
結果
こんな感じのアバターが並列に量産できるようになりました。
これを元に鬼コーチアプリをつくってみました。
鬼コーチアプリをつくりました。
— 君塚史高 (@ki_230) 2025年12月29日
基本的になにを相談しても超親身にコーチングしてくれるのですが、来年の話をしてしまったときのみ大爆笑されます。鬼なので。 pic.twitter.com/v9TssVGNVz
今回は以上です。
