Claude Code カスタムエージェントを使えば、SEOライターやセキュリティ監査員など専門特化型のAIアシスタントを自作できます。.claude/agents/にMarkdownファイルを置くだけで定義でき、Claude が自動的に適切なエージェントへ委譲してくれます。本記事では、エージェント定義ファイルの書き方から実用テンプレートまで徹底解説します。
関連記事: 生成AIカテゴリの記事一覧
Claude Code カスタムエージェントとは？できることの概要
カスタムエージェントは、特定の種類のタスクを処理する専門特化型のAIアシスタントです。各エージェントは独立したコンテキストウィンドウで動作します。また、カスタムシステムプロンプトと制限されたツールアクセスを持ちます。
Claudeがエージェントの説明に合致するタスクに出会うと、自動的にそのエージェントに委譲します。つまり、ユーザーが意識しなくても適切な専門家が動き出す仕組みです。
カスタムエージェントで実現できること
- コンテキストの分離：探索・実装・テストをメインの会話から切り離し、コンテキストウィンドウを節約できます
- ツール制限の強制：SEOレビュアーには読み取り専用ツールのみ、デプロイエージェントにはBashのみ、といった制約をかけられます
- 設定の再利用：プロジェクトをまたいで同じエージェントを使い回せます
- コストの最適化：軽い作業にはHaikuモデルを割り当て、料金を抑えられます
組み込みエージェントと自作エージェントの関係
Claude Code には、最初から Explore（コードベース探索用）、Plan（計画立案用）、General-purpose（汎用タスク用）の3種類が組み込まれています。これらに加えて、自分でカスタムエージェントを作成できます。
例えば、このブログの執筆環境では wp-article-writer（記事執筆）や wp-seo-reviewer（SEO最適化）といったエージェントを定義しています。そのため、複雑な記事生成ワークフローを自動化できています。
エージェント定義ファイルの構造と書き方
エージェント定義ファイルは、YAMLフロントマターとMarkdown本文の2つのパートで構成されます。具体的には、フロントマターが設定情報を担い、Markdown本文がシステムプロンプトになります。
フロントマターの全フィールド解説
以下がエージェント定義ファイルの基本構造です。
---
name: code-reviewer # 必須。小文字とハイフンのみ
description: "コードの品質とセキュリティをレビューする。コード変更後に積極的に使用"
tools: # 省略時は全ツールを継承
- Read
- Grep
- Glob
- Bash
model: sonnet # sonnet / opus / haiku / inherit（デフォルト）
permissionMode: acceptEdits # default / acceptEdits / dontAsk / bypassPermissions / plan
maxTurns: 10 # エージェントの最大ターン数
---
あなたはシニアコードレビュアーです。
コードの品質、セキュリティ、ベストプラクティスに焦点を当ててレビューしてください。各フィールドの役割を整理します。
| フィールド | 必須 | 説明 |
|---|---|---|
name | はい | 小文字とハイフンのみで構成する一意の識別子 |
description | はい | Claudeがこのエージェントへ委譲するかを判断する説明文。具体的に書くほど自動委譲の精度が上がる |
tools | いいえ | 使用可能なツールのリスト。省略時はすべてのツールを継承 |
model | いいえ | 使用するモデル。sonnet / opus / haiku / inherit から選択 |
permissionMode | いいえ | 権限の扱い方。acceptEdits（編集を自動承認）が最も実用的 |
maxTurns | いいえ | エージェントの最大ターン数。無限ループを防ぐ安全弁として有効 |
memory | いいえ | 永続メモリのスコープ。user / project / local から選択 |
skills | いいえ | 起動時にコンテキストへ注入するスキルのリスト |
descriptionの書き方がカギ
Claudeは description フィールドを読んで、タスクを委譲するかどうかを判断します。そのため、この説明文の品質が自動委譲の精度を左右します。
効果的なdescriptionの書き方には、2つのポイントがあります。まずいつ使うべきかを明示すること、そして「積極的に使用」のような能動的な表現を加えることです。
例えば、「コードをレビューする」よりも「コード変更後に積極的に使用。品質・セキュリティ・ベストプラクティスをレビューする」と書いたほうが、自動委譲の頻度が上がります。
権限モードの選び方
permissionMode は、エージェントが権限プロンプトをどう扱うかを制御します。実用的な場面での選び方を示します。
- default：すべての操作で確認プロンプトが出る。安全だが手間がかかる
- acceptEdits：ファイル編集を自動承認する。コードレビューや記事執筆に最適
- dontAsk：権限プロンプトを自動拒否する。読み取り専用エージェントに向いている
- bypassPermissions：すべての権限チェックをスキップする。自動化スクリプト向けだが慎重に使うこと
- plan：読み取り専用の調査モード。コードを変更せず分析だけ行う場合に有効
.claude/agents/ディレクトリの設定と配置ルール
エージェント定義ファイルの配置場所によって、有効になるスコープが変わります。適切な場所を選ぶことが、チーム共有や個人設定の使い分けのポイントです。
配置場所と優先度
| 場所 | スコープ | 優先度 | 主な用途 |
|---|---|---|---|
.claude/agents/ | 現在のプロジェクト | 高（プロジェクト固有） | チームで共有するエージェント |
~/.claude/agents/ | すべてのプロジェクト | 低（グローバル） | 個人用のエージェント |
プロジェクト固有のエージェントはバージョン管理にコミットすることを推奨します。チームメンバーと同じエージェントを共有でき、開発ワークフローの統一につながります。
ファイル命名と読み込みのタイミング
エージェント定義ファイルは エージェント名.md という形式で保存します。例えば、code-reviewer.md や seo-writer.md のように名付けます。
ただし、手動でファイルを追加した場合は注意が必要です。エージェントはセッション開始時に読み込まれます。そのため、新しく追加したファイルをすぐに反映させるには、/agents コマンドを実行するか、セッションを再起動してください。
/agentsコマンドを活用する
Claude Codeのセッション内で /agents と入力すると、エージェント管理のインタラクティブインターフェースが開きます。具体的には、以下の操作が可能です。
- 利用可能なすべてのエージェント（組み込み・ユーザー・プロジェクト）を一覧表示する
- ガイド付きセットアップまたはClaude生成を使って新規エージェントを作成する
- 既存エージェントの設定やツールアクセスを編集する
- 不要なエージェントを削除する
また、claude agents（非インタラクティブ）を実行すると、設定済みエージェントをソース別にグループ化して一覧表示できます。
スキルとエージェントの違いを理解する
Claude Code には スキル（Skills） と カスタムエージェント（Agents） という2つの拡張機能があります。どちらもMarkdownファイルで定義しますが、動作の仕組みは根本的に異なります。この違いを理解することが、適切な選択のカギです。
関連記事: CLAUDE.mdの書き方ガイド
コンテキストの扱いが最大の違い
スキルはメイン会話のコンテキスト内で実行されます。一方、エージェントは独立したコンテキストウィンドウで実行されます。これが最も本質的な違いです。
スキルはレシピ本のようなイメージです。必要なときにめくって参照し、そのままメインの会話の流れで作業を続けます。つまり、会話履歴へのアクセスがあり、過去のやり取りを踏まえて動作できます。
エージェントは専門の同僚への委譲に近いイメージです。別のコンテキストウィンドウで独立して動作し、メイン会話の履歴を引き継ぎません。そのため、大量の出力を生成するタスクをメインの会話から切り離すのに適しています。
スキルとエージェントの比較表
| 観点 | スキル（Skills） | エージェント（Agents） |
|---|---|---|
| 実行コンテキスト | メイン会話のコンテキスト内 | 独立したコンテキストウィンドウで実行 |
| 会話履歴へのアクセス | あり | なし（新鮮なコンテキストのみ） |
| 起動方法 | /スキル名 でユーザーが直接起動 | Claudeが自動委譲、または明示的に依頼 |
| ファイル構造 | SKILL.md（ディレクトリ形式） | エージェント名.md（単一Markdownファイル） |
| 用途 | 再利用可能なプロンプト・ワークフロー | 独立したコンテキストが必要な専門タスク |
| ネスト | context: fork でエージェントとして実行可 | サブエージェントは子エージェントを生成不可 |
どちらを選ぶべきか
スキルが向いているケースは以下の通りです。
- ユーザーが明示的に呼び出したい再利用可能なワークフローがある場合
- メインの会話コンテキストを参照しながら作業する必要がある場合
- 複数のエージェントに同じ知識・ルールを共有したい場合
一方、エージェントが向いているケースは次のとおりです。
- テスト実行やログ解析など、大量の出力を生成するタスクを切り離したい場合
- 特定のツールのみに制限した専門家ロールを持たせたい場合
- Claudeに自動的にタスクを委譲させたい場合
なお、スキルとエージェントは組み合わせて使うこともできます。エージェントの skills フィールドにスキル名を指定すると、そのスキルの内容がエージェントのコンテキストへ注入されます。これにより、専門エージェントにドメイン知識を持たせることが可能です。
実用テンプレート集：Claude Code カスタムエージェントの作成例
実際の活用イメージをつかんでもらうために、3つの実用テンプレートを紹介します。それぞれコピーして使えるようにしています。
SEO専門ライターエージェント
技術ブログの記事をYoast SEO基準で執筆する専門エージェントです。読み取り・書き込みツールのみに制限し、不要な操作ができないよう設定します。
---
name: seo-article-writer
description: "SEOに最適化された技術ブログ記事を執筆する。新規記事の執筆依頼時に積極的に使用"
tools:
- Read
- Write
- WebSearch
- WebFetch
model: sonnet
permissionMode: acceptEdits
maxTurns: 20
---
あなたはSEO専門の技術ブログライターです。
## 執筆ルール
- フォーカスキーフレーズを導入文の最初の100文字以内に含める
- H2見出しにキーフレーズまたは同義語を最低1つ入れる
- 1文は40文字以内を目標とする
- 転換語（そのため、具体的には、一方で、また等）を積極的に使う
- 導入文は100〜200文字にまとめる
## 出力形式
WordPressのGutenbergブロック形式（<!-- wp:paragraph -->等）で出力することセキュリティ監査エージェント
コードベースのセキュリティリスクを検出する読み取り専用エージェントです。Writeツールを除外することで、意図しないファイル変更が起こらないよう設計しています。
---
name: security-auditor
description: "コードのセキュリティリスクを監査する。デプロイ前やコードレビュー時に積極的に使用"
tools:
- Read
- Grep
- Glob
- Bash
model: sonnet
permissionMode: dontAsk
maxTurns: 15
---
あなたはセキュリティ専門のコード監査官です。
## 監査対象
- ハードコードされたシークレットやAPIキー
- SQLインジェクションの可能性がある箇所
- 入力バリデーションの欠如
- 認証・認可の実装ミス
- 脆弱な依存パッケージ
## レポート形式
問題を以下の優先度で分類してレポートする:
1. 重大（Critical）：即座に修正が必要
2. 警告（Warning）：早期の対応を推奨
3. 提案（Info）：改善を検討
各問題には、ファイルパス・行番号・修正例を含めることDB設計レビューエージェント
データベーススキーマとクエリのレビューに特化したエージェントです。読み取りのみに限定し、誤ってデータを変更しないよう安全設計にしています。
---
name: db-designer
description: "データベーススキーマ設計・SQLクエリの品質をレビューする。マイグレーションファイル追加時や設計レビュー時に使用"
tools:
- Read
- Grep
- Glob
model: sonnet
permissionMode: plan
maxTurns: 10
---
あなたはデータベース設計の専門家です。
## レビュー観点
- 正規化の適切さ（第3正規形を目標とする）
- インデックスの設計（クエリパターンに合致しているか）
- 外部キー制約の欠如
- N+1問題を引き起こしやすいクエリパターン
- 大量データでのパフォーマンス懸念
## アドバイス方針
問題点を指摘するだけでなく、具体的な改善案のSQLを提示すること。
パフォーマンス改善の場合は、EXPLAIN結果の読み方も説明することカスタムエージェントのベストプラクティスとTips
実際にカスタムエージェントを作り始めると、いくつかのつまずきポイントがあります。ここでは実践的なTipsをまとめます。
エージェントを小さく単機能に保つ
「なんでもできるエージェント」を作りたくなる気持ちは自然ですが、実は逆効果です。各エージェントは1つの特定タスクに特化させることで、自動委譲の精度が上がります。
例えば、「コードレビューとデプロイを両方やる」エージェントよりも、「コードレビュー専用」と「デプロイ専用」を分けるほうが賢明です。理由は2つあります。まず責務が明確になることで、descriptionの説明が書きやすくなります。次に、ツール制限も最小権限の原則に沿って設定できます。
descriptionに「いつ使うか」を明記する
Claudeはdescriptionをもとに自動委譲するかを判断します。そのため、「何をする」だけでなく「いつ使うべきか」を書くことが重要です。
具体的には、「コード変更後に積極的に使用」「デプロイ前に必ず実行」のようなトリガーを含めましょう。また、「proactively」に相当する「積極的に」という表現を加えると、自動委譲の頻度が上がります。
永続メモリで学習を蓄積する
memory フィールドを使うと、エージェントが発見した知識をセッションをまたいで保持できます。例えば、コードレビュアーエージェントに memory: user を設定すると、過去のレビューで発見したパターンやコーディング規約を蓄積できます。
---
name: code-reviewer
description: "コードの品質をレビューする。コード変更後に積極的に使用"
tools:
- Read
- Grep
- Glob
model: sonnet
memory: user
---
コードをレビューする前に、メモリを確認して過去に発見したパターンを参照してください。
レビュー完了後は、発見した新しいパターンや規約をメモリに保存してください。スコープの使い分けは次のとおりです。プロジェクトをまたいで使いたい知識には user、プロジェクト固有の知識には project、バージョン管理に含めたくない場合は local を選びます。
並列実行の効率と「見えにくさ」という盲点
リサーチ系のエージェントは複数を並列で動かせます。そのため、情報収集の量と効率が大幅に上がります。また、model: haiku を割り当てることで、軽量なタスクに低コストのモデルを使えます。
ただし、一つ盲点があります。エージェントが独立したコンテキストで動くため、Claude Code のコンソール画面に活動状況が現れにくいのです。特に Cowork アプリでは複数のコンソールを分けて表示できないため、裏でエージェントが動いているのかどうかが視覚的に確認しにくい場面があります。
実際に使ってみると「静かに動いているな」と感じることも多いです。進捗が気になる場合は、出力ファイルの生成状況を確認するか、エージェントの出力を明示的にファイルに書き出す設計にすると確認しやすくなります。
関連記事: Claude Code Coworkの詳細解説
あわせて読みたいおすすめ書籍
Claude CodeのカスタムエージェントやAIエージェント開発をさらに深めたい方には、以下の書籍がおすすめです。
まとめ：Claude Code カスタムエージェントで開発効率を高める
本記事では、Claude Code カスタムエージェントの定義方法から実用例まで解説しました。要点を整理します。
- カスタムエージェントは
.claude/agents/にMarkdownファイルを置くだけで定義できる - フロントマターの
nameとdescriptionは必須。descriptionの品質が自動委譲の精度を左右する - スキルはメイン会話内で動作し、エージェントは独立したコンテキストで動作する——この違いが選択のポイント
- プロジェクト固有のエージェント（
.claude/agents/）はチームとバージョン管理で共有できる - エージェントは単機能に保ち、ツールを最小権限に絞るのがベストプラクティス
memoryフィールドを活用すると、エージェントがセッションをまたいで知識を蓄積できる
まずは小さなエージェントから作り始めてみましょう。コードレビュアーやSEOチェッカーなど、繰り返し行う専門タスクをエージェント化することで、開発フローの自動化が進みます。より詳しい生成AI活用の情報は、生成AIカテゴリもご覧ください。
コメント