Agents Troubleshooting Task Tool FAQ

Agentトラブルシューティングガイド：よくある問題と解決策

Claude Code Agentを使用する際によく発生する問題と対処法。timeout、結果の不完全性、並列実行の失敗など、代表的なケースを網羅。

• 更新日： • 12 分で読める • 著者：Claude World

Claude Codeの**Agent tool**（v2.1.63より前の名称はTask tool。以下のTask({...})の例は、引き続き使えるこの別名を使っています）とagentを使用していると、いくつかの典型的な問題に遭遇することがあります。本ガイドでは、最もよくある問題とその解決策を解説します。

2026年10月21日更新： Claude Code v2.1.305 に合わせ、subagent がデフォルトでバックグラウンド実行になったこと、TaskOutput の削除（v2.1.277）、組み込みの Explore agent が Haiku ではなくメイン会話のモデルで動作すること、haiku が Haiku 5.5 を指すようになったことを反映し、モデル選択・同時実行数の上限・エラーに関する説明を現行の挙動に更新しました。

よくある問題のカテゴリ

カテゴリ典型的な症状よくある原因
起動の問題Agentが起動しない、即座に失敗するパーミッション、設定、パスのエラー
Timeoutの問題Agentが時間がかかりすぎるコンテキストが大きすぎる、タスクが複雑すぎる、リソース制限
結果の問題結果が不完全または不正確プロンプトが曖昧、コンテキスト不足
並列実行の問題Agentが並列で動かない呼び出しパターンが誤り、リソースの競合
パフォーマンスの問題遅い、メモリ使用量が高いモデルの選択、タスク設計の問題

問題1：Agentが起動しない、または即座に失敗する

症状

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore auth module"
})
// Error: "Failed to start agent" または即座にエラーが発生

原因と解決策

原因1：作業ディレクトリが誤っている

問題：現在のディレクトリがプロジェクトのルートではない。

解決策：

# プロジェクトルートにいるか確認
pwd
# /Users/you/projects/my-app のようなパスが表示されるはず

# 違う場合は正しいディレクトリへ移動
cd /path/to/your/project

原因2：Gitリポジトリが初期化されていない

問題：一部のagent機能はgitの履歴を必要とする。

解決策：

# Gitリポジトリを初期化
git init
git add .
git commit -m "Initial commit"

原因3：ファイルのパーミッション

問題：Claude Codeがプロジェクトのファイルを読めない。

解決策：

# ファイルのパーミッションを確認
ls -la

# 必要な場合は修正
chmod -R +r ./

原因4：モデルが利用できない

問題：指定したモデルを利用できない。組織のavailableModels許可リストで除外されている、クラウドプロバイダーのアカウントで有効化されていない、またはClaude Codeのバージョンがモデルの要件より古い（Opus 5.5はv2.1.280以降、Sonnet 5.5はv2.1.284以降、Haiku 5.5はv2.1.293以降が必要）といったケースです。Opus自体に特別なアクセスは不要で、Opus 5.5はPro、Max、Team、EnterpriseとAnthropic APIのデフォルトモデルです。

解決策：バージョンがそのモデルに対応していないというエラーならclaude updateを実行します。組織が制限しているモデルの場合、Claude Codeは許可されたモデルでそのagentを実行し、通知を表示します。各agentが実際に使っているモデルは/tasksで確認できます。

// プランやプロバイダーで許可されたモデルを指定するか、
// `model` を省略してメイン会話のモデルを使う
Task({
  subagent_type: "general-purpose",
  model: "sonnet",  // Anthropic API では Sonnet 5.5
  prompt: "Your task"
})

問題2：AgentのExecution Timeout

症状

Agentが期待以上の時間（例：2分以上）を要し、結果が返ってこない。

原因と解決策

原因1：タスクのスコープが広すぎる

問題：プロンプトが曖昧で、agentがプロジェクト全体をスキャンしてしまう。

悪い例：

Task({
  subagent_type: "Explore",
  prompt: "Analyze everything about this codebase"  // 広すぎる
})

良い例：

Task({
  subagent_type: "Explore",
  prompt: "Explore authentication module (thoroughness: medium). Find JWT handling and session management."
})

原因2：Thoroughnessが高すぎる

問題：very thoroughレベルは小さいスコープには適切だが、プロジェクト全体には時間がかかりすぎる。

解決策：

// 大きなスコープにはmediumまたはquickを使用
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore entire codebase structure (thoroughness: quick)"
})

// 小さなスコープにはvery thoroughを使用
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Deep dive into auth/login.ts (thoroughness: very thorough)"
})

原因3：コンテキストが大きすぎる

問題：Agentが処理しなければならないファイルが多すぎる。

解決策：タスクを分割する

// 悪い例：全モジュールを一度に処理
Task({ prompt: "Analyze all API endpoints" })

// 良い例：個別に処理
Task({ prompt: "Analyze user-related API endpoints" })
Task({ prompt: "Analyze payment-related API endpoints" })
Task({ prompt: "Analyze admin-related API endpoints" })

原因4：バックグラウンドタスクの確認忘れ

問題：Agentがバックグラウンドで動いているのに、timeout したと思い込んでいる。何も設定していなければ、Claudeがメイン会話から起動するagentはバックグラウンドで開始されるため（インタラクティブなターミナルセッションではv2.1.232以降）、トランスクリプトが静かなのは通常、agentがまだ作業中だからです。

解決策：/tasksを実行すると、実行中および完了直後のagentと、それぞれが使っているモデルを確認できます。結果は後のターンで完了通知としてClaudeに届き、それより前に進捗を尋ねると、Claudeはagentがまだ実行中だと報告します。

// バックグラウンドタスクを開始
Task({
  subagent_type: "security-auditor",
  model: "sonnet",
  prompt: "Comprehensive security audit",
  run_in_background: true
})

// TaskOutput は v2.1.277 で削除：結果は完了通知で届く。
// 進捗は /tasks で確認し、停止は /tasks で x を押す
// （Claude は TaskStop を使う）。

問題3：Agentが不完全な結果を返す

症状

Agentが期待する内容を含まない結果を返したり、質問の一部にしか答えない。

原因と解決策

原因1：プロンプトが曖昧

問題：Agentが何を探すべきか判断できていない。

悪い例：

Task({
  prompt: "Look at the auth code and tell me what you think"  // 曖昧すぎる
})

良い例：

Task({
  prompt: `
    Analyze authentication module (src/auth/).
    Report specifically on:
    1. JWT secret storage (how is it stored?)
    2. Session management (what strategy?)
    3. Password hashing (which algorithm?)

    Format as a bulleted list.
  `
})

原因2：1回のリクエストに質問が多すぎる

問題：プロンプトにリクエストが多すぎて、agentが一部を見落としている。

解決策：複数のリクエストに分割する

// 悪い例：すべてを一度に聞く
Task({
  prompt: "Analyze auth, payments, user management, admin panel, and reporting"
})

// 良い例：個別に聞く
Task({ prompt: "Analyze authentication system" })
Task({ prompt: "Analyze payment system" })
Task({ prompt: "Analyze user management" })

原因3：コンテキストが不足している

問題：Agentがニーズを理解するための十分なコンテキストがない。

解決策：背景情報を追加する

Task({
  prompt: `
    Context: We're migrating from REST to GraphQL.
    Current state: All endpoints are in src/api/v1/

    Task: Find all REST endpoints and list which ones still need migration.
  `
})

原因4：探索スコープが適切でない

問題：Explore agentのthoroughnessレベルが合っていない。

解決策：

// 素早い概要にはquickを使用
Task({
  subagent_type: "Explore",
  prompt: "List all files in src/auth/ (thoroughness: quick)"
})

// 深い分析にはmediumまたはvery thoroughを使用
Task({
  subagent_type: "Explore",
  prompt: "Analyze authentication flow in detail (thoroughness: medium)"
})

問題4：並列AgentがParallel実行されない

症状

複数のagentを起動したはずなのに、並列ではなく順次実行されているように見える。

原因と解決策

原因1：呼び出しパターンが誤っている

問題：ループの中でTaskを順番に呼び出しており、同時に呼び出していない。これで順次実行になるのはフォアグラウンドで動くagentだけで、Claudeが各結果を待ってから次を呼び出すためです。何も設定していなければ、Claudeがメイン会話から起動するagentは現在デフォルトでバックグラウンドで開始され、並行して動きます（インタラクティブなターミナルセッションではv2.1.232以降）。それでもClaudeはclaude -pとAgent SDKではagentを待機でき、インタラクティブセッションでもCLAUDE_CODE_FORK_SUBAGENT=0でforkモードをオフにすれば待機できます。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1を設定すると、すべてのagentを待機します。

悪い例：

// これは順次実行される
const agents = ['auth', 'payment', 'user']
for (const topic of agents) {
  Task({ prompt: `Analyze ${topic}` })  // 順次実行
}

良い例：

// これは並列実行される
Task({ prompt: "Analyze auth" })
Task({ prompt: "Analyze payment" })
Task({ prompt: "Analyze user" })
// すべてが同時に起動され、並列で実行される

原因2：リソースの競合

問題：同時に実行するagentが多すぎて、リソースが枯渇している。さらにClaude Codeは、1つのセッションで20個のagentが実行中になると新たな起動を拒否します（Concurrent subagent limit reached。上限はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSで変更可能）。また、どのagentもメイン会話と同じ利用上限を消費します。

解決策：並列数を制限する

// 悪い例：10個の並列agent
for (let i = 0; i < 10; i++) {
  Task({ prompt: `Task ${i}` })
}

// 良い例：バッチ実行（1バッチあたり3〜5個）
// バッチ1
Task({ prompt: "Task 1" })
Task({ prompt: "Task 2" })
Task({ prompt: "Task 3" })
// 完了を待ってからバッチ2
Task({ prompt: "Task 4" })
Task({ prompt: "Task 5" })
Task({ prompt: "Task 6" })

原因3：Agentに依存関係がある

問題：後のagentが前のagentの結果に依存している。

解決策：フェーズ実行を行う

// フェーズ1：並列探索（独立）
Task({ prompt: "Map file structure" })
Task({ prompt: "Find API endpoints" })
Task({ prompt: "List database models" })
// 完了を待つ

// フェーズ2：フェーズ1の結果を活用
Task({ prompt: "Based on structure found, analyze auth flow" })

問題5：Agentのパフォーマンスが低い、またはメモリ使用量が高い

症状

Agentの動作が遅い、またはシステムのメモリ使用量が急増する。

原因と解決策

原因1：モデルの選択が誤っている

問題：シンプルなタスクに高コストなモデルを使用している。

解決策：適切なモデルを選ぶ

// 悪い例：シンプルな検索にOpusを使用
Task({
  subagent_type: "Explore",
  model: "opus",  // コストが高すぎる
  prompt: "Find login function"
})

// 良い例：シンプルな検索にHaikuを使用
Task({
  subagent_type: "Explore",
  model: "haiku",  // 高速かつ低コスト
  prompt: "Find login function (thoroughness: quick)"
})

ExploreのデフォルトはもうHaikuではありません。v2.1.198以降、組み込みのExplore agentはメイン会話のモデルで動作し、Pro、Max、Team、EnterpriseとAnthropic APIではデフォルトでOpus 5.5になります（メインセッションがClaudeのサブスクリプションまたはAnthropic ConsoleアカウントでFableを使っている場合、ExploreはOpusを使います）。検索を低コストに保つには、上の例のようにmodel: "haiku"を渡すか、model: haikuを指定した独自のExplore agentを定義します。Anthropic APIではhaikuは現在Haiku 5.5を指し、Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry、Claude Platform on AWSでは引き続きHaiku 4.5です。

原因2：コンテキストの過負荷

問題：Agentが不要なファイルを大量に読み込んでいる。

解決策：スコープを絞る

// 悪い例：モノリポ全体を探索
Task({
  prompt: "Analyze entire monorepo"
})

// 良い例：特定のパッケージに集中
Task({
  prompt: "Analyze packages/auth/ only"
})

原因3：重複した作業

問題：複数のagentが同じファイルを繰り返し分析している。

解決策：タスクを調整する

// 悪い例：繰り返しの探索
Task({ prompt: "Analyze auth for security" })
Task({ prompt: "Analyze auth for performance" })
Task({ prompt: "Analyze auth for code quality" })
// 3回も同じファイルを読み込んでいる

// 良い例：作業を分担する
Task({ prompt: "Explore auth module (thoroughness: medium)" })
// その結果を異なる分析に活用する

原因4：Explore agentを使っていない

問題：ファイル検索にgeneral-purpose agentを使用している。

解決策：

// 悪い例：general-purposeでファイル検索
Task({
  subagent_type: "general-purpose",
  prompt: "Find all files with 'auth' in the name"
})

// 良い例：Explore agentでファイル検索
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Find all auth-related files (thoroughness: quick)"
})

問題6：Agentタイプの選択が誤っている

症状

結果が期待と異なる、またはagentがタスクに適していないように見える。

Agentの選択ガイド

タスク正しいAgent誤ったAgent
ファイル検索Explore（model: "haiku"を指定）general-purpose
コードレビューcode-reviewerExplore
セキュリティ監査security-auditorcode-reviewer
テスト分析test-runnergeneral-purpose
デバッグdebuggerExplore
リファクタリングrefactor-assistantgeneral-purpose

組み込みなのはExplore、Plan、general-purpose（と少数の補助agent）だけです。code-reviewer、security-auditor、test-runner、debugger、refactor-assistantは、.claude/agents/や~/.claude/agents/で自分で定義するか、pluginから導入するカスタムagentです。Claudeがそれらを見つけられない場合はfrontmatterを確認してください。nameがない、nameはあるがdescriptionがない、またはYAMLをパースできないファイルは、セッション内に何のメッセージも出さずにスキップされます。claude plugin validate .claude/agentsでパースできないfrontmatterを検出でき、claude --debugではスキップの理由の多くがデバッグログに記録されます。レビュー用には、Claude Codeに/code-review（エイリアス/review）と/security-reviewも組み込まれています。

例

// ❌ 誤り：ExploreでセキュリティAudit
Task({
  subagent_type: "Explore",
  prompt: "Check for security vulnerabilities"
})

// ✅ 正しい：security-auditorでセキュリティ監査
Task({
  subagent_type: "security-auditor",
  model: "sonnet",
  prompt: "Audit for security vulnerabilities"
})

問題7：Agentの結果が理解しにくい

症状

Agentが整理されていない形式で結果を返したり、ワークフローに組み込みにくい。

解決策

解決策1：特定のフォーマットをリクエストする

Task({
  prompt: `
    Analyze the authentication module.

    Format your response as:
    ## Overview
    [2-3 sentences]

    ## Findings
    - [Bullet point 1]
    - [Bullet point 2]

    ## Recommendations
    1. [Recommendation 1]
    2. [Recommendation 2]
  `
})

解決策2：JSON出力をリクエストする

Task({
  prompt: `
    List all API endpoints.

    Respond in this JSON format:
    {
      "endpoints": [
        {"path": "/api/users", "method": "GET", "auth": true},
        {"path": "/api/users", "method": "POST", "auth": true}
      ]
    }
  `
})

解決策3：段階的に結果を収集する

// フェーズ1：生データを収集
const rawData = Task({ prompt: "List all endpoints" })

// フェーズ2：整形する
Task({
  prompt: `
    Format this data as a markdown table:
    ${rawData}

    Columns: Path, Method, Auth Required, Description
  `
})

診断ツールとテクニック

テクニック1：段階的な単純化

Agentが失敗する場合は、タスクを段階的に単純化する：

// ステップ1：最小限のタスク
Task({ prompt: "List files in src/" })

// ステップ2：少し複雑に
Task({ prompt: "List files in src/auth/" })

// ステップ3：本来のタスク
Task({ prompt: "Analyze auth module structure" })

テクニック2：Verboseモードの活用

問題を診断する際は、より多くのコンテキストを追加する：

Task({
  prompt: `
    [VERBOSE MODE]
    I'm trying to understand why X fails.

    Please:
    1. List all files you examined
    2. Show your reasoning step-by-step
    3. Report any errors encountered

    Task: [your actual task]
  `
})

テクニック3：比較テスト

異なるagentを同時に使って結果を比較する：

// Agent 1
const result1 = Task({
  subagent_type: "Explore",
  prompt: "Find all auth functions"
})

// Agent 2
const result2 = Task({
  subagent_type: "general-purpose",
  prompt: "Find all auth functions"
})

// 結果の違いを比較する

サポートを求めるタイミング

上記の解決策で問題が解決しない場合：

  1. Claude Codeのバージョンを確認：

    claude --version

    最新バージョンを使用していることを確認してください。

  2. GitHub Issuesを確認： https://github.com/anthropics/claude-code/issues

  3. コミュニティに参加：

  4. バグを報告： 報告時には以下を含めてください：

    • Claude Codeのバージョン
    • オペレーティングシステム
    • 完全なエラーメッセージ
    • 再現手順
    • 最小限の再現可能な例

クイックリファレンス：よくあるエラーコード

エラーコード意味解決策
ENOENTパスが見つからないファイルパスが正しいか確認
EACCESパーミッション拒否ファイルのパーミッションを確認
ETIMEDOUT実行timeoutタスクのスコープを小さくするか、thoroughnessを下げる
ENOMEMメモリ不足並列agentの数を減らす
ECONNREFUSEDAPI接続失敗ネットワーク接続とAPI Keyを確認
Agent '…' would be spawned with zero toolsagentのtoolsリストのどの項目も利用可能なツールに一致しないツール名を修正するか、toolsを削除してデフォルトのツールセットを継承する
Concurrent subagent limit reachedすでに20個のagentが実行中（デフォルトの上限）一部の完了を待つか、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSを引き上げる
Agent terminated early due to an API error利用上限やサーバーエラーでagentが途中終了した根本のエラーを解消してから、Claudeに再試行またはagentの再開（resume）を依頼する

予防のためのベストプラクティス

問題を避けるためのベストな方法：

  1. 小さなタスクから始める：まずシンプルなタスクをテストし、agentが正しく動作することを確認する
  2. 適切なモデルを使用する：検索にはHaiku（Anthropic APIではHaiku 5.5）、日常的な実装にはSonnet 5.5、難しい推論にはOpus 5.5（デフォルトモデル）
  3. プロンプトを明確に保つ：求めることを具体的に指定する
  4. フェーズに分けて作業する：Explore → Analyze → Implement
  5. リソースを監視する：メモリとCPUの使用量に注意する
  6. 作業結果を保存する：定期的にgitへcommitし、進捗を失わないようにする

他の問題に遭遇した場合は、Discordの#helpチャンネルで質問してください。コミュニティがお手伝いします！