Claude Codeカスタムサブエージェントの作り方｜.claude/agents/で専用AIワーカーを定義する

Claude Codeのカスタムサブエージェントは、.claude/agents/ディレクトリにMarkdownファイルを配置するだけで、特定の業務に特化した専用AIワーカーを定義できる機能です。——「コードレビュー専門」「デバッグ専門」「データ分析専門」など、役割ごとにエージェントを分離することで、指示の再現性と品質の安定性が向上します。各サブエージェントはカスタムシステムプロンプト、特定のツールアクセス、独立した権限を備えた独自のコンテキストウィンドウで実行されます。

あわせて読みたい

• Claude Code Hooksで開発ワークフローを自動化する方法

• Claude Code × Git Worktree｜並列開発で安全にブランチ分離する方法

• Claude Codeのパーミッションモード完全ガイド

この記事でわかること

Claude Codeでカスタムエージェントを構築したいエンジニアに向けた記事です。

• .claude/agents/ディレクトリの基本構造と、カスタムサブエージェントの作成手順 — サブエージェントは、ClaudeCodeに「専門的な役割」を与えるための仕組みです。
• フロントマターの全フィールド（name、description、tools、model、memory、isolation等）の設定方法 — を設定すると、サブエージェントは一時的なgitworktreeで実行され、リポジトリの分離されたコピーが提供されます。
• isolation（worktree分離）とmemory（永続記憶）の設計判断基準 — フィールドは、会話をまたいで存続する永続ディレクトリをサブエージェントに提供します。
• 実務で使えるカスタムサブエージェント3パターンの具体的な定義例 — ClaudeCodeには、以下の組み込みサブエージェントが含まれています。
• Hooks・MCP・スキルとの連携方法 — サブエージェントのフロントマター内にを定義すると、そのサブエージェントがアクティブな間だけ実行されるライフサイクルフックを設定できます。

カスタムサブエージェントとは

サブエージェントは、Claude Codeに「専門的な役割」を与えるための仕組みです。通常のClaude Codeは汎用的なAIアシスタントとして動作しますが、サブエージェントを定義すると、特定のタスクに最適化された振る舞い・知識・制約を持つ専門家として動作します。

サブエージェントが役立つ主なシーンは以下の通りです。

• コンテキストの保持: 探索と実装をメインの会話から分離し、メインコンテキストを圧迫しない

• 制約の強制: サブエージェントが使用できるツールを制限し、意図しない操作を防ぐ

• 設定の再利用: ユーザーレベルのサブエージェント（~/.claude/agents/）をプロジェクト横断で再利用

• コスト制御: Haikuなどの高速・低コストモデルにタスクをルーティング

Claudeは各サブエージェントのdescriptionフィールドを使用して、タスクを委譲するかどうかを自動判断します。明確なdescriptionを書くことが、適切な委譲の鍵になります。

組み込みサブエージェント

Claude Codeには、以下の組み込みサブエージェントが含まれています。

これらに加えて、以下で説明するカスタムサブエージェントを独自に作成できます。

基本的な使い方

エージェント定義ファイルの作成

カスタムサブエージェントは .claude/agents/（プロジェクトレベル）または ~/.claude/agents/（ユーザーレベル）にMarkdownファイルとして配置します。

.claude/
├── CLAUDE.md
├── settings.json
└── agents/
    ├── code-reviewer.md     ← コードレビュー専門
    ├── debugger.md          ← デバッグ専門
    └── data-scientist.md    ← データ分析専門

/agentsコマンドでの作成

/agentsコマンドを使うと、インタラクティブにサブエージェントを作成・管理できます。

/agents

「Create new agent」を選択し、Project-level（.claude/agents/）またはUser-level（~/.claude/agents/）を選択します。「Generate with Claude」を選ぶと、説明文からシステムプロンプトと設定を自動生成してくれます。

サブエージェント定義ファイルの構造

サブエージェントファイルは、YAMLフロントマターで設定を行い、その後のMarkdown本体がシステムプロンプトになります。

---
name: code-reviewer
description: Expert code review specialist. Use proactively after code changes.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- No exposed secrets or API keys
- Proper error handling
- Good test coverage

フロントマター全フィールド一覧

isolation（worktree分離）の設計

isolation: worktreeを設定すると、サブエージェントは一時的なgit worktreeで実行され、リポジトリの分離されたコピーが提供されます。

---
name: experimental-refactor
description: Experimental refactoring that needs isolation from main working tree
isolation: worktree
---

worktree分離が有効な場合、サブエージェントがファイルを変更しても、メインのワーキングツリーには影響しません。サブエージェントが変更を加えなかった場合、worktreeは自動的にクリーンアップされます。

設計判断の基本方針: 「このサブエージェントの変更がメインブランチに影響を与えるリスクがあるか」を基準に判断します。コードレビューのような読み取り専用タスクにはworktreeは不要です。実験的なリファクタリングや並列ブランチでの作業にはisolation: worktreeが有効です。

memory（永続記憶）の設計

memoryフィールドは、会話をまたいで存続する永続ディレクトリをサブエージェントに提供します。

memoryが有効な場合、サブエージェントのシステムプロンプトにメモリディレクトリの読み書き指示が自動的に追加されます。メモリディレクトリのMEMORY.mdの最初の200行もコンテキストに注入されます。

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

推奨のデフォルトスコープはuserです。サブエージェントの知識が特定のコードベースにのみ関連する場合は、projectまたはlocalを使用します。

実務での活用パターン

パターン1: SEO記事レビュー専門エージェント

BtoBマーケティングでブログ記事を量産する場合、品質の一貫性を保つことが課題になります。レビュー専門サブエージェントを定義すれば、全記事に同じ基準でレビューを適用できます。

---
name: seo-reviewer
description: SEO記事の品質を評価する専門エージェント。記事のレビュー依頼時に使用。
tools: Read, Glob, Grep
model: sonnet
memory: project
---

# SEO記事レビュー専門エージェント

**あなたはSEO記事の品質レビューを行う専門家です。**

あなたはSEO記事の品質レビューを行う専門家です。

### レビュー基準
#### コンテンツ品質
- 3,000文字以上であること
- H2/H3の見出し構造が適切であること
- です/ます調で統一されていること
- 実名事例のみ使用（匿名A社/B社は禁止）

#### SEO最適化
- メタディスクリプション120文字以内
- 主要キーワードがH1とH2に含まれていること
- 内部リンクが3本以上含まれていること
- FAQセクションが3問以上あること

Before: レビューのたびに評価基準を口頭で伝え直し、レビュアーによって評価のブレが発生。

After: Claudeがタスク内容からseo-reviewerサブエージェントに自動委譲し、一貫したレビューが実行される。

パターン2: HubSpot API操作専門エージェント

HubSpot CRMの設定作業を自動化する場合、APIの仕様やレート制限、プロパティの命名規則など、守るべきルールが多数あります。

---
name: hubspot-operator
description: HubSpot APIを使ったCRM設定・データ操作を行う専門エージェント
tools: Bash, Read, Write, Glob
model: inherit
memory: user
---

# HubSpot API操作専門エージェント

あなたはHubSpot CRMの設定を自動化する専門家です。

#### API操作ルール
- レートリミット: 10秒間に100リクエスト以内
- PATCH後は必ずGETで反映を確認
- 日本語テキストの文字化けをGETレスポンスで検証

#### プロパティ命名規則
- グループ名: snake_case
- プロパティ名: snake_case
- 表示名: 日本語（正式名称）

Before: HubSpot APIの仕様やレート制限を毎回プロンプトに記載。漏れがあるとAPIエラーや意図しない設定変更が発生。

After: Claudeがタスク内容を判断してhubspot-operatorに委譲し、APIルールが常に適用された状態で安全に操作できる。

パターン3: デバッグ専門エージェント

エラーの根本原因を分析し、修正まで行うサブエージェントです。コードレビューと異なり、Editツールを含めてバグ修正を可能にしています。

---
name: debugger
description: Debugging specialist for errors and test failures. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
model: inherit
---

# デバッグ専門エージェント

あなたはエラーの根本原因分析と修正の専門家です。

#### デバッグプロセス
1. エラーメッセージとスタックトレースの解析
2. 再現手順の特定
3. 障害箇所の分離
4. 最小限の修正の実装
5. 修正の動作確認

#### 出力フォーマット
- 根本原因の説明
- 診断の根拠
- 具体的なコード修正
- テストアプローチ
- 再発防止の推奨事項

Before: エラー調査の出力がメインコンテキストを圧迫し、デバッグ完了後の作業に必要なコンテキストが失われる。

After: デバッグ作業がサブエージェントの独立したコンテキストで完結し、要約のみがメイン会話に返される。

サブエージェントの呼び出しと実行

自動委譲

Claudeはリクエスト内容とサブエージェントのdescriptionを照合して、自動的にタスクを委譲します。積極的な委譲を促すには、descriptionに「Use proactively」と記載します。

特定のサブエージェントを明示的に使いたい場合は、以下のように指示します。

Use the code-reviewer subagent to look at my recent changes

フォアグラウンドとバックグラウンド実行

• フォアグラウンド: 完了までメイン会話をブロック。権限プロンプトや質問がユーザーに渡される
• バックグラウンド: メイン作業と並行して実行。background: trueを設定するか、実行中にCtrl+Bでバックグラウンドに移行

---
name: test-runner
description: Run test suite in background
background: true
---

CLIフラグでの一時的なサブエージェント定義

セッション限定のサブエージェントを--agentsフラグでJSON形式で渡すこともできます。ディスクに保存されないため、クイックテストや自動化スクリプトに便利です。

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Hooks・MCP・スキルとの連携

Hooksとの連携

サブエージェントのフロントマター内にhooksを定義すると、そのサブエージェントがアクティブな間だけ実行されるライフサイクルフックを設定できます。

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

この例では、PreToolUseフックでBashコマンドを実行前に検証し、SQLの書き込み操作（INSERT/UPDATE/DELETE等）をブロックしています。

MCPサーバーとの連携

mcpServersフィールドで、サブエージェント専用のMCPサーバーを定義できます。メイン会話には影響せず、サブエージェントの開始時に接続、終了時に切断されます。

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

スキルのプリロード

skillsフィールドで、スタートアップ時にスキルコンテンツをサブエージェントのコンテキストに注入できます。

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

サブエージェント設計のベストプラクティス

命名規則

1エージェント1責務の原則

カスタムサブエージェントは「1つの専門領域」に特化させるのが鉄則です。「レビューもテスト作成もドキュメント更新もできるエージェント」を作ると、CLAUDE.mdと変わらない汎用的な指示になり、サブエージェントの利点が失われます。

ツールアクセスの最小化

最初は必要最小限のツールだけを付与し、必要に応じて追加するアプローチを推奨します。読み取り専用タスクにはRead, Glob, Grepのみ、コード修正が必要なタスクにはEditを追加、といった段階的な設計が安全です。

バージョン管理へのチェックイン

プロジェクトレベルのサブエージェント（.claude/agents/）はGitにコミットして、チーム全体で共有・改善できるようにしましょう。ただし、APIキーやトークンなどの機密情報はエージェント定義に直接書かず、環境変数で参照する設計にしてください。

まとめ

他のHubSpot Hubやツールとの連携・統合も視野に入れることで、さらに大きな効果が期待できます。

まずは自社の現状を棚卸しし、最も効果が見込める領域から第一歩を踏み出してみてください。

属人化を防ぎ、チーム全体で再現可能な仕組みとして標準化することが成功の鍵です。

自社の業務フローや要件に応じて、段階的にカスタマイズしていくことをおすすめします。

• Claude Codeのカスタムサブエージェントは、.claude/agents/にMarkdownファイルを配置するだけで、業務特化型の専用AIワーカーを定義できる仕組みです
• フロントマターのtools・model・memory・isolation・hooksを適切に設定することで、セキュリティを担保しながら専門的なタスクを自動化できます
• SEO記事レビュー、HubSpot API操作、デバッグなど、繰り返し発生する業務ほど、サブエージェント化の効果が大きくなります

• *Claude Codeの全コマンド一覧はClaude Codeチートシートをご覧ください
• AI活用の全体像はAI活用完全ガイドで解説しています

よくある質問（FAQ）

Q1. カスタムサブエージェントとCLAUDE.mdの違いは何ですか？

CLAUDE.mdはプロジェクト全体に適用される共通ルールを定義するファイルです。カスタムサブエージェントは特定の役割に特化した振る舞いを定義するファイルです。CLAUDE.mdが「チーム全体のルールブック」なら、カスタムサブエージェントは「個々のメンバーのジョブディスクリプション」に相当します。サブエージェントはCLAUDE.mdのルールを継承しませんが、独自のシステムプロンプト内で必要なルールを記述できます。

Q2. サブエージェントの定義ファイルはGit管理すべきですか？

はい、プロジェクトレベル（.claude/agents/）のサブエージェントはGit管理を推奨します。チームメンバー全員が同じエージェント定義を使えるようになります。ユーザーレベル（~/.claude/agents/）は個人の環境に保存されるため、Git管理の対象外です。いずれの場合も、APIキーやトークンなどの機密情報はエージェント定義に直接書かず、環境変数で参照する設計にしてください。

Q3. サブエージェントは他のサブエージェントを生成できますか？

いいえ、サブエージェントは他のサブエージェントを生成できません。ネストされた委譲が必要な場合は、メイン会話からサブエージェントをチェーン（順序立てて使用）するか、スキルを使用してください。ただし、claude --agentsでメインスレッドとして起動したエージェントは、toolsフィールドにAgent(worker, researcher)のように記述することで、特定のサブエージェントの生成を許可できます。

Q4. memoryのデータはどこに保存されますか？

memoryのスコープによって保存先が異なります。userスコープは~/.claude/agent-memory/{エージェント名}/に、projectスコープは.claude/agent-memory/{エージェント名}/に、localスコープは.claude/agent-memory-local/{エージェント名}/に保存されます。projectスコープはGitにコミットしてチームで共有できますが、顧客データや機密情報が含まれる場合は.gitignoreに追加してください。

参考リンク

• Claude Code サブエージェント公式ドキュメント

• HubSpotナレッジベース