AIエージェント入門第四章！エージェントの基本と仕事を任せる前に知っておきたいこと

AIエージェントが複雑なタスクをこなせるようになってきた今、「エージェントにエージェントを使わせる」仕組みが整ってきています。コンテキストを分離して並列に動かしたり、チームで協力させたりと、Claude Code・Cursor・Antigravity でそれぞれ個性的な設計が採用されています。

第四章では、組み込みエージェント・カスタムエージェントの定義方法・マルチエージェントの連携・リモート実行といった機能面を3ツールで比べたうえで、実運用で必ずぶつかる 「カスタムエージェントが呼ばれない問題」 と 「並列実行のコスト・暴走問題」 にも踏み込んでいきます。機能の華やかさだけでなく、エージェントを安全に・賢く・無駄なく動かすために知っておきたいポイントをセットでお届けします。

組み込みエージェント

まずは、各ツールが最初から用意しているエージェントです。

Claude Code には、Claude が状況に応じて自動的に使い分ける組み込みサブエージェントが3種類あります。

Explore — コードベースの検索・探索に特化した高速エージェントです。モデルは Haiku で、Write や Edit ツールへのアクセスが制限された読み取り専用です。「変更は不要、コードを把握したい」という場面で自動的に呼ばれます。探索結果がメイン会話のコンテキストに溜まらないよう、独立したウィンドウで動いて要約だけを返してくれます。
Plan — プランモード（読み取り専用の計画立案モード）のとき、コードベースを調査するために使われるエージェントです。モデルはメイン会話から継承します。
general-purpose — 探索と変更の両方が必要な複雑なタスク向けで、すべてのツールにアクセスできます。モデルもメイン会話から継承します。

このほかに statusline-setup・Claude Code Guide といったヘルパーエージェントもあり、特定の場面で自動的に使われます。

Cursor には、コードベースの探索・ターミナルコマンドの実行・ブラウザ操作に対応した Explore・Bash・Browser の3つの組み込みサブエージェントがあります。メインエージェントがタスクに応じてこれらを自動的に呼び出します。

Antigravity には、メインエージェントと、Web インタラクションに特化した Browser サブエージェントがあります。Browser サブエージェントはメインエージェントが Web 操作を必要とするときに自動的に呼び出され、異なるモデルと専用の指示で動作します。

参考リンク

カスタムエージェントの定義

自分でエージェントを定義する方法と、どこまでカスタマイズできるかを比べます。

定義ファイルの形式

Claude Code と Cursor はどちらも YAML フロントマター＋Markdown 本文のファイル形式でエージェントを定義します。フロントマターにメタデータや設定を書いて、本文にシステムプロンプトを書く形です。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. Analyze the code and provide
actionable feedback on quality, security, and best practices.

Google Antigravity は「純粋なMarkdownの階層構造（見出し）」を利用して定義するアプローチを採用しています。YAMLのような特殊な記法は必要なく、.agents/agents.md という単一のMarkdownファイル内に、自然言語と通常の見出しを使って複数のエージェント（ペルソナ）を一元管理できるのが特徴です。

# 🤖 The Autonomous Development Team

## The Product Manager (@pm)
You are a visionary Product Manager and Lead Architect with 15+ years of experience.

**Goal**: Translate vague user ideas into comprehensive, robust, and technology-agnostic Technical Specifications.
**Traits**: Highly analytical, user-centric, and structured. You never write code; you only design systems.
**Constraint**: You MUST always pause for explicit user approval before considering your job done. 

## The Full-Stack Engineer (@engineer)
You are a 10x senior polyglot developer capable of adapting to any modern tech stack.

**Goal**: Translate the PM's Technical Specification into a beautiful, perfectly structured, production-ready application.
**Traits**: You write clean, DRY, well-documented code.
**Constraint**: You strictly follow the approved architecture.

カスタマイズ項目の比較

Claude Code のフロントマターフィールドは特に豊富です。主なものを挙げると：

フィールド	内容
`name`	エージェントの識別子（小文字・ハイフン）
`description`	Claude がいつ委任するかを判断するための説明
`model`	`sonnet` / `opus` / `haiku` / `inherit`
`tools`	許可ツールの許可リスト
`disallowedTools`	禁止ツールの拒否リスト
`permissionMode`	権限モード（後述）
`maxTurns`	最大エージェントターン数
`memory`	クロスセッション永続メモリのスコープ
`background`	バックグラウンド実行するか（true/false）
`isolation`	`worktree` でgit worktree 分離実行
`mcpServers`	このエージェント専用の MCP サーバー設定
`hooks`	エージェントがアクティブな間だけ有効なフック
`skills`	起動時にコンテキストに注入するスキル

Cursor が持つフィールドは name・description・model・readonly・is_background の5つです。Claude Code と比べると設定項目は少ない分、シンプルに使えます。

スコープ（適用範囲）の階層

Claude Code は5段階あります。上から順に優先度が高くなります。

管理設定               ← 組織全体（最高優先）
--agents CLI フラグ    ← 現在のセッションのみ
.claude/agents/        ← プロジェクト単位（バージョン管理に含めてチーム共有可）
~/.claude/agents/      ← 全プロジェクト共通（ユーザーレベル）
プラグインの agents/    ← プラグインが有効な場合

Cursor は2段階です。

.cursor/agents/        ← プロジェクト単位（最高優先）
~/.cursor/agents/      ← 全プロジェクト共通（ユーザーレベル）

Antigravity は現在開いているワークスペース（プロジェクトディレクトリ）のみ。（.agents/agents.md）

参考リンク

マルチエージェント・チーム

複数のエージェントを同時に動かして協力させる仕組みです。3ツールでアーキテクチャが大きく異なります。

チームアーキテクチャ

Claude Code のエージェントチームは実験的機能で、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を設定すると有効になります。1つのセッションがチームリーダーとして機能し、複数のチームメンバーを生成して作業を調整します。特徴的なのは、チームメンバーが互いに直接メッセージを送り合える点です。

Cursor のサブエージェントは親→子の階層型です。親エージェントがサブエージェントを起動して作業を委任します。サブエージェントは非同期で動くため、親エージェントは処理を待たずに別の作業を進めることができます。また、サブエージェントがさらにサブエージェントを生成することもでき、ツリー構造での調整も可能です。

Antigravity は、Claude Code のようなエージェント同士の直接的なメッセージング（チャット）による連携機能は持ちません。その代わり、agents.md で定義した各エージェントがArtifactファイルを介して成果物を次のエージェントへ引き渡す、非同期のバケツリレー方式で連携します。

タスク依存関係管理（Claude Code独自）

Claude Code のエージェントチームには、共有タスクリストと依存関係管理の仕組みがあります。タスク間の依存関係を設定しておくと、前のタスクが完了するまで後続タスクを要求できないよう自動制御されます。ファイルロックで複数メンバーが同じタスクを同時取得しようとする競合も防がれます。

また、チームメンバーのセッションとの対話方法として、in-process モード（Shift+Down でサイクル）と分割ペインモード（tmux / iTerm2 で各メンバーを別ペインに表示）の2種類があります。

参考リンク

リモート実行

エージェントをクラウドや他のデバイスからリモートで動かす仕組みです。

クラウド・リモート実行

Claude Code はローカル CLI とクラウドの両方に対応しています。

Remote Control（claude remote-control / /remote-control）：ローカルで動いているセッションをブラウザやスマホからリモート操作できます。セッションはあくまでローカルマシン上で実行されるため、ファイルシステムや MCP サーバー・プロジェクト設定がそのまま使えます。進行中の作業を別デバイスから引き継ぎたい場面に向いています。
Claude Code on the web（claude.ai/code）：Anthropic 管理のクラウドインフラ上でセッションを実行します。ローカル環境のセットアップなしにタスクを起動したり、複数タスクを並列で走らせたりできます。
Slack 連携：Slack で @Claude にコーディングタスクをメンションすると Claude Code on the web のセッションが自動作成され、Slack のスレッドに進捗が通知されます。

Cursor は Cloud Agents でリモートのクラウド実行に対応しています。隔離された仮想マシン上でエージェントが動き、ローカル PC が接続されていなくても非同期で処理を続けます。Cursor エディタ・Web UI（cursor.com/agents）・Slack・Linear・GitHub など複数の入口から起動でき、複数エージェントを同時に走らせることもできます。PR のバグを自動検出・修正する BugBot も Cloud Agents の仕組みを活用しています。

Antigravity はローカルにインストールするデスクトップアプリです（macOS・Windows・Linux 対応）。エージェントもローカルで実行されます。クラウド・リモート実行の仕組みは現時点では用意されていません。

参考リンク

エージェントはいつ・誰が起動するのか

ここまで機能の詳細を見てきましたが、「そもそもエージェントって誰が呼び出すの？」という疑問が残るかもしれません。これは3ツールで設計思想がはっきり分かれています。

組み込みエージェントは AI が自動で呼び出す

Explore・Plan・Browser サブエージェントのような組み込みエージェントは、3ツールとも AI が自動で判断して呼び出します。ユーザーは「コードを調べて」と依頼するだけで、どのエージェントが動くかを意識する必要はありません。

カスタムエージェントも基本は AI が自動

Claude Code と Cursor のカスタムサブエージェントは、description フィールドを見て AI が「このタスクはこのエージェントに任せよう」と自律的に判断します。ユーザーが @ メンションや /エージェント名 で明示的に指名することもできますが、それは例外的な使い方です。Antigravity も agents.md でカスタムエージェントを定義できますが、呼び出しはワークフロー経由かユーザーが Agent Manager から手動で行う形です。

マルチエージェントだけはツールで差が出る

複数エージェントを協調させる場面では、3ツールの思想の違いが顕著に出ます。

Claude Code のエージェントチームは、ユーザーが「チームを組んで並列で調査して」と起点を与えれば、あとはリーダーエージェントがメンバーを生成・調整します。ユーザーが直接介入しなくても動き続けます。

Cursor はそもそもチームという概念がなく、親エージェントが子エージェントを呼び出すだけです。ユーザーは親に依頼するだけでOKです。

Antigravity は、複数エージェントを並列で稼働させたい場合、ユーザーがオーケストレーターとして Agent Manager から各エージェントにタスクを割り当てて起動します。エージェント同士が自律的に連携して動くのではなく、それぞれが独立した環境で個別のタスクを遂行します。進行状況の確認は Agent Manager のダッシュボード上などで行われ、人間の承認を都度求める設定だけでなく、エージェントに完全に任せて自律的に進めさせる（Always Proceed）設定など、柔軟な権限管理ができる設計です。

参考リンク

description フィールドの書き方が9割

カスタムエージェントを作って「全然呼ばれない…」と悩んだ経験はありませんか？実は、エージェントが自動委任されるかどうかは description フィールドの書き方 でほぼ決まります。ここはドキュメントだとサラッと流されがちですが、実用上もっとも重要な設計ポイントです。

なぜ description が決定的なのか

Claude Code・Cursor のカスタムサブエージェントは、ユーザーの依頼内容と各エージェントの description を AI が突き合わせて「どれに任せるか」を判断します。description が曖昧だったり、他のエージェントと差別化できていなかったりすると、せっかく作ったエージェントがいつまでも呼ばれません。逆に description さえ的確なら、ユーザーが意識しなくても勝手に最適なエージェントが選ばれます。

よくある失敗例

---
name: code-reviewer
description: Reviews code
---

これだと「コードのレビューを担当するエージェント」程度の情報しかなく、AI は いつ呼ぶべきか を判断できません。「コードを書いて」と言われたときに呼ぶべきか、「PR を作って」と言われたときか、「バグを直して」と言われたときか、どれにも該当しそうで、結局メインエージェントが自分で処理してしまいます。

Anthropic 推奨の書き方

公式ドキュメントが推奨するのは、「Use this agent when ...（このエージェントを使うのは〜のとき）」 という具体的なトリガー条件を含める書き方です。

---
name: code-reviewer
description: |
  Use this agent when the user has just finished writing or modifying code
  and wants a thorough review for bugs, security issues, and best practices.
  Especially useful after implementing a new feature, before opening a PR,
  or when the user explicitly asks for a code review. Do NOT use for
  initial code generation or for explaining existing code.
---

ポイントは3つです。

具体的なトリガー条件を列挙する — 「コードを書き終わった直後」「PR を開く前」など、シーンを明示する
他のエージェントとの境界を引く — 「初回のコード生成には使わない」「既存コードの説明には使わない」という否定形が効きます
ユーザーの動詞を含める — 「review」「check」「audit」など、ユーザーが言いそうな単語を入れておくと AI のマッチング精度が上がります

Antigravity の場合

Antigravity の agents.md は YAML フロントマターではなく Markdown の見出し構造でエージェントを定義しますが、考え方は同じです。**Goal**・**Traits**・**Constraint** の3点セットで「何をする人か・何をしない人か」を明示するのが推奨されています。第四章前半で見たペルソナ定義例の Constraint: You MUST always pause for explicit user approval のような 境界条件 を入れるのがコツです。

検証方法

書いた description が機能しているかは、実際にユーザー目線の依頼を投げて確かめるのが一番です。Claude Code なら /agents で一覧を見て、想定したシーンで Agent ツールが正しいエージェントを選ぶか試す。呼ばれない場合は description にトリガー条件を足す、を繰り返します。地味ですが、ここをサボると以降の運用が破綻します。

参考リンク

エージェントを並列で走らせる前に知っておきたい現実

ここまで「エージェントは並列に動かせて便利」という話をしてきましたが、実際に運用してみると刺さる 2つの現実 があります。これを知らずに走らせると請求書か PR 差分のどちらかでびっくりすることになります。

現実その1：並列実行はそのままコストに跳ね返る

サブエージェントを5つ並列で動かすと、API 料金は 単純に5倍 になります。さらに各エージェントは独自のコンテキストを持つので、同じファイルを5つのエージェントが別々に読めば、その分のトークンも全部別計上です。「並列で速くなった」の裏で、月末の請求書が3倍になっていた、というのはよくある話です。

Claude Code が組み込みの Explore エージェントに Haiku を使っているのは、まさにこのコスト最適化のためです。「探索だけなら速くて安いモデルで十分」という割り切りで、メイン会話のモデル（Sonnet / Opus）と分けています。カスタムエージェントを作るときも、model フィールドを意識的に使い分けるのが効きます。

探索・検索系：Haiku（速い・安い）
計画立案・レビュー系：Sonnet（バランス）
複雑な実装・難しい判断：Opus（高精度・高コスト）

Cursor もエージェントごとにモデルを指定でき、Antigravity は Settings からモデルを切り替えられます。「全部 Opus で並列5本」は気軽にやると痛い目を見ます。並列度 × モデル単価 × 各エージェントが読むトークン量 をざっくり見積もる癖をつけておくと安全です。

現実その2：エージェントは暴走する

もうひとつの現実が暴走です。サブエージェントは「もっと情報をくれ」「次はこれを試す」と動き続ける性質があり、放っておくと際限なく呼び出しが続くことがあります。よくあるパターンは次の3つ。

無限ループ系：サブエージェントが親に質問を返し、親がまたサブエージェントを呼ぶ、を繰り返す
暴走編集系：bypassPermissions で動かしていたら、気づいたら 50 ファイル書き換わっていた
過剰な再試行系：失敗したコマンドを何度も再実行して、そのたびに新しい仮説を立てて試す

各ツールにはこの暴走を止めるための仕組みが用意されています。

Claude Code：maxTurns フィールドでエージェントの最大ターン数を制限できます。permissionMode: plan を使えば書き込みそのものを禁じられます。さらに Esc キーで実行中のエージェントを即座に中断できます
Cursor：Stop hook と loop_limit でセッションのループ回数に上限を設けられます。サブエージェントの定義に readonly: true を入れておけば書き込みも防げます
Antigravity：Terminal Command Auto Execution を Request Review にしておけば、危険なコマンドのたびに人間の承認が入ります。Agent Manager から個別エージェントを停止することもできます

実用的な指針は 「初回は必ず Request Review・plan モードで動かし、振る舞いを観察してから Auto に切り替える」 です。新しいエージェントをいきなり bypassPermissions で並列5本走らせるのは、中身も知らない npm パッケージを sudo npm install -g するのと同じくらいリスキーだと思っておいたほうがいいです。

そしてもうひとつ大事なのが ファイル衝突対策 です。複数のサブエージェントが同じファイルを書き換えると後勝ちで上書きされてしまいます。Claude Code の isolation: worktree や Cursor のバックグラウンド実行時の git worktree 強制、Antigravity のワークスペース単位の分離は、まさにこの問題への解答です。並列度を上げたいなら、worktree やワークスペース分離をセットで使うのが鉄則です。

参考リンク

まとめ

エージェント機能はどのツールも進化が早い領域ですが、設計思想の違いがそのまま使い勝手の差に出ています。

Claude Code はカスタマイズの幅が最も広く、maxTurns・permissionMode・model・isolation: worktree など、暴走対策とコスト最適化のための細かいツマミが一通り揃っています。実験的なエージェントチーム機能では P2P 通信やタスク依存関係管理まで踏み込んでいて、CI/CD 連携も充実。「エージェントを厳密にコントロールしながら、安全に並列で走らせたい」チームに向いています。

Cursor はシンプルな設計で、バックグラウンド実行とサブエージェントの並列実行が自然にできます。バックグラウンド実行時に git worktree が自動で使われるのはファイル衝突対策として地味に効いています。「難しい設定は不要、サブエージェントを手軽に並列で動かしたい」中規模チームにちょうどよい作りです。

Antigravity はエージェントの自律性とペルソナ設計を重視した独自路線です。agents.md のペルソナ定義 + ワークフロー + Artifact によるバケツリレーで「自律型開発パイプライン」を構築します。Agent Manager によるダッシュボード型の運用と、ワークスペース単位の厳格な分離が特徴で、人間がオーケストレーターとして複数エージェントを束ねるスタイルに合っています。

そして、どのツールを選ぶにしても忘れてはいけないのが 「description の書き方」と「コスト・暴走対策」 です。エージェントを賢く呼ばせるのは description 次第ですし、並列度とモデル選択を雑に決めると請求書か PR 差分のどちらかでびっくりすることになります。ツールの機能比較に目が行きがちですが、実運用でモノを言うのはこの2点です。新しいエージェントを作ったら、まずは plan モード・Request Review で振る舞いを観察してから自動化レベルを上げる、を習慣にするのがおすすめです。

このブログを検索

blog.kaname.dev