Claude Codeエージェント作成方法｜.claude/agentsの使い方

Claude Codeのカスタムサブエージェントは、.claude/agents/ディレクトリにMarkdownファイルを配置するだけで作成できます。「コードレビュー専門」「デバッグ専門」「データ分析専門」など役割ごとにAIワーカーを分離することで、指示の再現性と品質の安定性が向上します。

「同じレビュー観点を、記事やコードを見るたびに毎回プロンプトへ書き直している」「デバッグの調査ログがメインの会話を埋めてしまい、次の作業に必要なコンテキストが失われる」「複雑な操作を任せたら、意図しないコマンドまで実行されてしまった」——Claude Codeを個人利用からチーム運用に広げていく過程で、こうした声が出てくることは少なくないのではないでしょうか。

カスタムサブエージェントとは、.claude/agents/にMarkdownファイルを配置するだけで作成できる、特定の業務に特化した専用AIワーカーです。各サブエージェントは独自のシステムプロンプト、限定されたツールアクセス、独立したコンテキストウィンドウを持つため、役割ごとに指示を分離できます。

この記事でわかること

これからClaude Codeにカスタムサブエージェントを組み込みたいエンジニア・チームリーダーの方に向けて、設計の考え方から具体的な定義ファイルの書き方までをまとめました。

• .claude/agents/の基本構造と作成手順 — ディレクトリ配置とMarkdownファイルの書き方、/agentsコマンドでの対話的な作成方法を解説します。
• フロントマターの全フィールドの意味と設定基準 — tools・model・permissionModeなど各項目が何を制御するのかを整理します。
• isolation（worktree分離）とmemory（永続記憶）の使い分け — どちらを設定すべきかの判断基準を具体的に示します。
• 実務で使えるカスタムサブエージェント3パターン — SEO記事レビュー・HubSpot API操作・デバッグの各定義例をBefore/Afterで紹介します。
• Hooks・MCP・スキルとの連携方法 — サブエージェント単位でセキュリティ制約や専門知識を追加する設定を解説します。

Claude Codeを個人利用からチーム運用へ広げたい方、指示のブレやコンテキスト圧迫に課題を感じている方に向けて書いています。最後まで読むと、自社の業務に合わせたカスタムサブエージェントを設計し、.claude/agents/に定義できるようになります。

なぜカスタムサブエージェントが必要なのか

Claude Codeは標準の状態でも汎用的なAIアシスタントとして動作しますが、レビュー・デバッグ・データ分析といった性質の異なるタスクを同じ会話の中で切り替えると、指示のブレやコンテキストの圧迫が起きやすくなります。カスタムサブエージェントは、この「1つの会話に全部を詰め込む」運用の限界を、役割の分離という形で解決するアプローチです。

汎用エージェントに全部任せることの限界

汎用的なClaude Codeにレビューもデバッグもドキュメント更新も任せてしまうと、タスクごとに評価基準や制約を毎回プロンプトで伝え直す必要が出てきます。担当者によって指示の粒度が変わると、レビュー結果の品質にもブレが生じます。これは、口頭やメモでルールを都度共有する運用が属人化しやすいのと同じ構造です。

カスタムサブエージェントが解決する3つの課題

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

• コンテキストの保持 — 探索と実装をメインの会話から分離し、メインコンテキストを圧迫しません。
• 制約の強制 — サブエージェントが使用できるツールを制限し、意図しない操作を防ぎます。
• コスト制御 — Haikuなどの高速・低コストモデルにタスクをルーティングできます。

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

Claude Codeの一連の流れの中での位置づけ

サブエージェントは単体の便利機能というより、メイン会話→サブエージェントへの委譲→独立したコンテキストでの実行→要約のみをメインに返す、という一連のフローの一部として機能します。この一気通貫の流れを意識して設計すると、メインの会話は常に「次に何をするか」の判断に集中でき、詳細な調査ログや修正の試行錯誤はサブエージェント側に閉じ込められます。

組み込みサブエージェントとカスタムサブエージェントの違い

Claude Codeには、最初からいくつかのサブエージェントが組み込まれています。まずはこの標準機能で足りる部分と、足りない部分を切り分けることが、カスタムサブエージェント設計の出発点になります。

Explore・Plan・General-purposeの役割

組み込みサブエージェントで足りない部分

組み込みの3種類は、いずれも汎用的な探索・実行を目的としたものであり、「自社のSEO基準でレビューする」「自社のHubSpot API運用ルールに従って操作する」といった、業務固有のルールは反映されていません。こうした業務特化の役割は、これから解説するカスタムサブエージェントとして自分たちで定義する必要があります。ここでも、どのような専門エージェントを何個作るべきかは、チームやプロジェクトによって最適な形が異なります。

.claude/agents/でカスタムサブエージェントを作る手順

カスタムサブエージェントは、.claude/agents/（プロジェクトレベル）または~/.claude/agents/（ユーザーレベル）にMarkdownファイルとして配置します。まずは手動でファイルを作る方法と、対話的に作成する/agentsコマンドの両方を押さえておくと、以降の設計がスムーズになります。

ディレクトリ構成とファイル配置

.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」を選ぶと、説明文からシステムプロンプトと設定を自動生成してくれます。

上の画面は、claude --versionの実行結果に続けて、/agentsコマンドとターミナルのclaude --agentsコマンドを並べたものです。

フロントマターとシステムプロンプトの基本構造

サブエージェントファイルは、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

フロントマターの全フィールドを理解する

フロントマターの各フィールドは、そのサブエージェントが「何をできて、何をできないか」を決める設定項目です。全フィールドを一度に使う必要はありませんが、どのフィールドが何を制御するのかを把握しておくと、目的に応じた過不足のない設計ができます。

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

ツールと権限を絞るフィールド

permissionModeは、AIにどこまで自律的な操作を任せるかを決める項目です。ファイルの書き換えや外部への送信など、影響範囲の大きい操作を含むサブエージェントにはdefaultやplanを設定し、実行前に人間が確認できるようにしておくことをおすすめします。すべてを自動実行に任せる設計は、意図しない変更のリスクを高めます。

実行環境を制御するフィールド

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"
  }
}'

上の画面は、claude --helpを実行し、--agentsフラグの説明行をgrepで抜き出した実行結果です。

isolation（worktree分離）とmemory（永続記憶）の設計基準

isolationとmemoryは、どちらも設定しなくてもサブエージェントは動作します。ただし、変更の影響範囲を限定したい場合や、会話をまたいで知識を蓄積させたい場合には、この2つのフィールドが効いてきます。判断に迷いやすい項目なので、基準を分けて整理します。

isolationを使うべきケース・使わなくていいケース

isolation: worktreeを設定すると、サブエージェントは一時的なgit worktreeで実行され、リポジトリの分離されたコピーが提供されます。worktree分離が有効な場合、サブエージェントがファイルを変更しても、メインのワーキングツリーには影響しません。サブエージェントが変更を加えなかった場合、worktreeは自動的にクリーンアップされます。

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

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

memoryのスコープ選択

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

memoryが有効な場合、サブエージェントのシステムプロンプトにメモリディレクトリの読み書き指示が自動的に追加されます。メモリディレクトリのMEMORY.mdの最初の200行もコンテキストに注入されます。推奨のデフォルトスコープはuserです。サブエージェントの知識が特定のコードベースにのみ関連する場合は、projectまたはlocalを使用します。

判断基準のまとめ

実務で使えるカスタムサブエージェント3パターン

ここからは、具体的な定義例を3つ紹介します。いずれも「レビュー基準やAPI操作ルールを口頭で伝え直すのではなく、定義ファイルに落とし込んで仕組み化する」という考え方が共通しています。担当者が変わっても同じ基準が適用される状態を作ることが、サブエージェント化の本質的な価値です。

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

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

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

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

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

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

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

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

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

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ルールが常に適用された状態で安全に操作できる。

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

エラーの根本原因を分析し、修正まで行うサブエージェントです。コードレビューと異なり、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: デバッグ作業がサブエージェントの独立したコンテキストで完結し、要約のみがメイン会話に返される。

Hooks・MCP・スキルとの連携で専門性を高める

サブエージェントは単体でも機能しますが、Hooks・MCP・スキルと組み合わせることで、安全装置や専門知識をサブエージェント単位で持たせられます。プロジェクト全体に共通するCLAUDE.mdのルールとは別に、特定の役割だけに適用したい制約がある場合に有効です。

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と変わらない汎用的な指示になり、サブエージェントの利点が失われます。いきなり全業務をサブエージェント化するのではなく、まずは効果が見込める1つの業務（例えばコードレビュー）から着手し、効果を確認しながら段階的にサブエージェントを増やしていくアプローチをおすすめします。

ツールアクセスの最小化とバージョン管理

最初は必要最小限のツールだけを付与し、必要に応じて追加するアプローチが安全です。読み取り専用タスクにはRead, Glob, Grepのみ、コード修正が必要なタスクにはEditを追加、といった段階的な設計をおすすめします。プロジェクトレベルのサブエージェント（.claude/agents/）はGitにコミットして、チーム全体で共有・改善できるようにしましょう。ただし、APIキーやトークンなどの機密情報はエージェント定義に直接書かず、環境変数で参照する設計にしてください。

向かないケース（正直な限界）

サブエージェントは万能ではありません。サブエージェントは他のサブエージェントを生成できないため、ネストした委譲が必要な場合はメイン会話からのチェーン利用やスキルの活用を検討する必要があります。また、確度の判断や設計の意思決定そのものをサブエージェントに丸ごと任せるのではなく、影響範囲の大きい操作はpermissionModeで人間の確認を挟む設計にしておくことが安全です。理想的なサブエージェントの構成は、チームの開発フローやコードベースによって異なるため、自社の運用に合わせて調整していく前提で設計するとよいでしょう。

よくある質問

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のカスタムサブエージェントは、.claude/agents/にMarkdownファイルを配置するだけで、業務特化型の専用AIワーカーを定義できる仕組みです。フロントマターのtools・model・memory・isolation・hooksを目的に応じて設定することで、権限を絞りながら専門的なタスクを任せられます。SEO記事レビュー、HubSpot API操作、デバッグのように、繰り返し発生し、かつ評価基準が明確な業務ほど、サブエージェント化の効果が大きくなります。

まずは自社の業務の中で「毎回同じ基準を伝え直している」作業を1つ棚卸しし、そこからサブエージェント化を試してみることをおすすめします。次の3ステップで着手できます。

1. 繰り返し発生している業務を1つ選び、評価基準やルールを箇条書きで書き出す
2. /agentsコマンドでプロジェクトレベルのサブエージェントを作成し、書き出したルールをシステムプロンプトに反映する
3. 実際にタスクを依頼してClaudeが自動委譲するかを確認し、descriptionやtoolsを調整する

CRMを活用した業務効率化やAIとの連携に関するご相談は、CRM特化型コンサルティングのHubSpotゴールドパートナーのStartLinkまでお気軽にお問い合わせください。

あわせて読みたい

• Claude Code Hooksで開発ワークフローを自動化する方法
• Claude Code × Git Worktree｜並列開発で安全にブランチ分離する方法
• Claude Codeのパーミッションモード完全ガイド