【実例で解説】Claude Codeのサブエージェントを作ってみた

サブエージェントって何？普通にClaude Codeで会話するのと何が違うの？

特定タスク専用に切り出した「分離されたAI」だよ。
メインの会話を汚さず、ツール権限も絞れるのが特徴だよ。

Claude Codeにおけるサブエージェントって具体的にどう作るの？どんなときに使うと安全で効率的なの？と疑問に思っている人も多いと思います。
この記事では、YAMLで定義するカスタムサブエージェントの基本構造、作成手順を解説します。
また初めてカスタムエージェントを作る際も迷わないように、UI操作（/agents）と手書きのMarkdown（.claude/agents/*.md）の両方の手順を示します。

サンプルファイルや完成例はすべて私のGitHubリポジトリに置いています。
GitHubのリポジトリ

Contents

1 サブエージェントとは？Claude Codeにおける役割とメリット
- 1.1 「自動委譲」と「単一セッション内の分離」
- 1.2 サブエージェントで期待できる効果
2 サブエージェントの基本コンポーネントと主要フィールド
- 2.1 必須フィールド（name, description）
- 2.2 よく使うオプション
3 カスタムサブエージェントを作ってみる
4 まとめ

サブエージェントとは？Claude Codeにおける役割とメリット

Claude Codeを使い込んでいると、「ログ解析はここで、コードレビューはあそこで」と用途ごとに設定を使い分けたくなる場面が出てきます。
そのニーズに応えるのがカスタムサブエージェントです。

サブエージェントとは、特定タスク専用に独立したコンテキスト・システムプロンプト・ツール権限を与えられたAIアシスタントです。
メインのClaudeが「このタスクはサブに任せよう」と判断したとき、または呼び出し側が明示的に指定したとき、サブエージェントが起動します。

用途に応じて軽量モデルを割り当てたり、ツールアクセスを最小限に絞ることで、安全性とコストの両方をコントロールできます。

「自動委譲」と「単一セッション内の分離」

自動委譲(automatic delegation)とは、メインのClaudeがタスクの性質を判断し、適切なサブエージェントへ処理を振り分ける仕組みです。
ユーザーが毎回指定しなくても、Claudeが「このリクエストならコードレビュー用エージェントが向いている」と自律的に判断して委譲します。

またサブエージェントは「単一セッション内で分離」されており、専用のコンテキストとメモリ領域を持ちます。
サブエージェントの作業ログや中間出力がメイン会話に流れ込まず、会話のノイズを防げます。
大量のログ解析や長い調査作業をサブエージェントに任せても、メイン会話はすっきりした状態を保てます。

サブエージェントで期待できる効果

安全性の向上：ツール権限をRead-onlyに絞ったエージェントを使えば、ファイル破壊や意図しない書き込みのリスクを構造的に排除できます
コスト削減：高頻度の探索タスクにはHaikuなど軽量モデルを割り当て、重要な処理だけOpusやSonnetを使うといったコスト設計が可能です
責務の明確化：コードレビュー・DBクエリ・テスト実行など、役割ごとにエージェントを分けることで、設定の見通しと保守性が大幅に上がります

サブエージェントの基本コンポーネントと主要フィールド

サブエージェントの実体は、YAML frontmatterを持つMarkdownファイルです。
ファイルの先頭に --- で囲んだYAMLブロックを置き、その後に自然言語のシステムプロンプトを書きます。
設定項目を一つずつ理解すれば、用途に合ったエージェントを迷わず設計できるようになります。

Markdownファイルの先頭にYAMLを書くだけで定義できる。最初はnameとdescriptionだけでも十分動くよ。

必須フィールド（name, description）

最小限必要なのは name と description の2つだけです。
この2フィールドがあれば、/agents でエージェントとして認識・登録されます。

---
name: code-reviewer
description: Reviews code for quality and best practices
---
You are a senior code reviewer. Identify bugs, style issues, and improvement opportunities.

description はClaudeが自動委譲の判断に使います。
「どんなときに呼ばれるべきか」を具体的に書くほど、委譲精度が上がります。

よく使うオプション

以下のオプションを組み合わせて、エージェントの能力と権限を細かく制御できます。
まずは tools で許可するツールを列挙し、allowlistを作るところから始めるのが安全です。

tools：使用を許可するツールのリスト（例：Read, Grep, Glob, Bash）。ここに書かれていないツールは使えません。
model：sonnet / haiku / opus / inherit。inherit は呼び出し元のモデルを引き継ぎます。
memory：user（個人横断）/ project（プロジェクト共有）/ local（一時作業）の永続メモリスコープを有効にし、サブエージェントがクロスセッションで学習・記憶を維持できるようにします。ツール権限は tools / disallowedTools / permissionMode で明示的に設計してください。”
hooks：PreToolUse などのライフサイクルフック。ツール実行前に検査スクリプトを走らせることができます。
permissionMode：default / acceptEdits（編集を自動許可）/ dontAsk / bypassPermissions（危険：限定使用）/ plan
isolation：エージェントの隔離レベル。プロジェクト間での参照可否に影響します。

ファイルの配置場所には優先順位があります。
セッション起動時の --agents フラグが最優先で、次いでプロジェクトの .claude/agents/、ユーザー共通の ~/.claude/agents/、プラグイン内の順に読み込まれます。

カスタムサブエージェントを作ってみる

カスタムサブエージェントってどうやって作るの？すぐできる？

Claude Codeのチャット欄に/agentsと打てばすぐ開けるよ。
まずはそこから始めてみよう。

サブエージェントを作る方法は以下の2通りがあります。

サブエージェントを作る方法

UIから対話的に作成する方法
Markdownファイルを手書きする方法

初めての方にはUIを使った方法が直感的でおすすめです。

/agentsでの作成する方法（UIから対話的に作成）

UIから対話的に作成する方法は非常にシンプルです。
Claude Codeのセッション内で /agents を打ち込んで実行します。
あとは順番に質問に回答していくだけです。

/claudeでClaudeCodeのセッションを開きます。
Claude Codeのチャット欄に /agents と入力してUIを開きます。
「Create new agent」をクリックし、スコープとして「Project」を選択します。
「Generate with Claude」を選び、作りたいエージェントの概要を入力します（例：“ファイルをスキャンして可読性とパフォーマンスの改善を提案するコード改善エージェント”）
ToolsはRead-onlyに制限します。最初は Read-only tools のみにチェックを入れ、それ以外は外してください。「Continue」を選択します。
Modelは用途に応じて選択します。軽い探索なら haiku、バランス重視なら sonnet が無難です。
Memoryを project または「None」に設定し、「Save」で保存します

Markdownファイルを手書きで作成する方法

より細かく設定を制御したい場合は、Markdownファイルを直接作成してください。
以下のファイルを .claude/agents/code-improvement-scanner.md として保存します。

---
name: code-improvement-scanner
description: コードの可読性とパフォーマンスを改善するエージェント。コードレビュー、改善、リファクタリングの依頼時やコード変更後にプロアクティブに使用する。
tools: Glob, Grep, Read, WebFetch, WebSearch, Write, Edit
model: haiku
memory: project
---

あなたはコード改善のエキスパートです。ソフトウェアの可読性、パフォーマンス最適化、クリーンコードの原則に精通しています。

## ミッション

指定されたファイルをスキャンし、以下の2つの観点から改善提案を行います:
1. **可読性** — コードの理解しやすさ、保守性、拡張性の向上
2. **パフォーマンス** — 実行速度、メモリ効率、スケーラビリティの向上

## 言語

- ユーザーの使用言語に合わせて回答する（日本語なら日本語で）
- 具体的なコード例を含む明確で簡潔な説明を行う

## ワークフロー

1. **対象ファイルを読み込む**
2. **体系的に分析する**（可読性とパフォーマンスの両面）
3. **発見事項を分類する**: 🔴 重大、🟡 重要、🟢 提案
4. **構造化されたレポートを作成する**（before/afterのコード例付き）

## 可読性チェックリスト

- **命名**: 変数・関数・クラスの名前は明確で一貫性があるか
- **関数の長さ**: 1つの関数が多くのことをしすぎていないか
- **複雑度**: 深いネストの条件分岐やループを簡略化できないか
- **コメント**: 複雑なロジックにコメントが不足していないか
- **一貫性**: ファイル全体でコードスタイルが統一されているか
- **マジックナンバー**: 説明のないリテラル値が定数化されているか

## パフォーマンスチェックリスト

- **アルゴリズムの計算量**: O(n²)以上を削減できないか
- **データ構造の選択**: アクセスパターンに適した構造を使っているか
- **メモリ割り当て**: 不要なオブジェクト生成やコピーがないか
- **キャッシュ機会**: 高コストな計算が不必要に繰り返されていないか
- **言語固有の最適化**: 組み込み関数、内包表記、ジェネレータなど

## 出力フォーマット

各発見事項について:
```
### [🔴/🟡/🟢] [カテゴリ] — 簡潔なタイトル

**場所**: ファイル:行番号
**問題**: 問題の明確な説明
**修正前**:
（現在のコード）
**修正後**:
（改善コード）
**理由**: 改善の効果の説明
```

最後に**サマリー**セクションを追加:
- 重大度別の発見数
- 優先すべき改善トップ3
- コード品質の総合評価

## 重要なガイドライン

- 明示的に求められない限り、コードの動作やパブリックAPIを変更する提案はしない
- 各提案の「なぜ」を必ず説明する
- 可読性を犠牲にするマイクロ最適化は避ける
- コードが十分に良い場合は、そのことを伝える

**エージェントメモリを更新する**: コードパターン、よくある問題、スタイル慣習、パフォーマンスのアンチパターンを発見したら記録する。これにより会話をまたいで知識が蓄積される。

動作確認

agentsの読み込み確認

.claude/agents配下にmdファイルを保存したら、Claude Codeを再起動するか、/agents UIで「Refresh」することで読み込まれます。

# claude codeのセッションを開き直す
claude

# agents一覧を表示する
/agents

以下のように .claude/agents内に定義したカスタムサブエージェントが表示されれば読み込み成功です。

明示的呼び出し

メッセージ内に @<エージェント名> と書くと、そのエージェントが優先的に呼び出されます。動作確認には、まずこちらを使うのが確実です。

自動委譲

「このプロジェクトのコードを改善して」といった指示に対して、メインClaudeがdescriptionを参照し、適切なサブエージェントへ自動的に委譲します。

Memory

memoryフィールドを指定すると、サブエージェントに「永続ディレクトリ」が割り当てられます。
ここにサブエージェントが学習したパターンや発見を蓄積でき、次回以降の呼び出しでそれを参照できます。

スコープの違い（user / project / local）

user：ホームディレクトリ配下に保存され、すべてのプロジェクトで利用されます。個人の作業習慣や好みを横断的に蓄積したいときに有効です。
project：.claude/agent-memory// に保存され、チームで共有可能です。コードベース固有の決定やパターンを記録するのに適しています。
local：一時的なメモリで、バージョン管理にチェックインしない短期的な知識向けです。

実装時の振る舞いと注意点

メモリはClaude側で必要と判定された場合は自動的に作成されます。

一方で、自動でファイルが作成されないときは、呼び出し前に「以前のメモリを確認して」と依頼したり、タスク完了後に「今回の学びをメモリへ保存して」と指示する運用が効果的です。

メモリは必要と判断された場合のみ作成されます。確実に作成して欲しい時には、「agent memoryに記録してください。」のように指示することで作成可能です。

作成されたmemoryファイルの例：

---
name: マジックナンバー未定数化アンチパターン
description: ハードコードされた値をコメント説明に頼っている
type: antipattern
---

## 発見事項

コード内に説明を必要とするハードコードされた値（マジックナンバー）が複数存在し、定数化されていない。

### 例: FizzBuzz実装（sample_app.py:149-161）

**アンチパターン**:
```python
def fizzbuzz(n):
    result = []
    for i in range(1, n + 1):
        if i % 15 == 0:  # 3と5の最小公倍数でチェック（コメントで説明）
            result.append("FizzBuzz")
        elif i % 3 == 0:
            result.append("Fizz")
        elif i % 5 == 0:
            result.append("Buzz")
```

**改善**:
```python
FIZZ_NUM = 3
BUZZ_NUM = 5
FIZZBUZZ_NUM = FIZZ_NUM * BUZZ_NUM

def fizzbuzz(n):
    result = []
    for i in range(1, n + 1):
        if i % FIZZBUZZ_NUM == 0:
            result.append("FizzBuzz")
        elif i % FIZZ_NUM == 0:
            result.append("Fizz")
        elif i % BUZZ_NUM == 0:
            result.append("Buzz")
        else:
            result.append(str(i))
    return result
```

## 理由

**Why**: マジックナンバーをコメントに依存すると、コメントとコードが乖離する可能性がある。定数化することで、値の意味が自動的にドキュメント化され、変更時の影響範囲が明確になる。

**How to apply**: コメント説明が必要な数値リテラルを見つけたら、即座に定数として切り出すこと。定数名は説明を含めて命名すること（例：`FIZZ_NUM`より`FIZZ_DIVISOR`の方がより明確）。