Agents Troubleshooting Task Tool FAQ

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

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

2026年1月15日 • 12 分で読める • 著者：Claude World

Claude CodeのTask toolとagentを使用していると、いくつかの典型的な問題に遭遇することがあります。本ガイドでは、最もよくある問題とその解決策を解説します。

よくある問題のカテゴリ

カテゴリ典型的な症状よくある原因
起動の問題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：モデルが利用できない

問題：指定したモデルが利用できない（例：Opusは特別なアクセスが必要）。

解決策：

// 代わりにSonnetを使用（デフォルトで利用可能）
Task({
  subagent_type: "general-purpose",
  model: "sonnet",  // "opus" ではなく
  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 したと思い込んでいる。

解決策：

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

// 後で結果を確認
TaskOutput({ task_id: taskId, block: true })

問題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を順番に呼び出しており、同時に呼び出していない。

悪い例：

// これは順次実行される
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が多すぎて、リソースが枯渇している。

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

// 悪い例：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)"
})

原因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 (haiku)general-purpose
コードレビューcode-reviewerExplore
セキュリティ監査security-auditorcode-reviewer
テスト分析test-runnergeneral-purpose
デバッグdebuggerExplore
リファクタリングrefactor-assistantgeneral-purpose

例

// ❌ 誤り：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のバージョン
    • オペレーティングシステム
    • 完全なエラーメッセージ
    • 再現手順
    • 最小限の再現可能な例

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

エラーコード意味解決策
ENOSPパスが見つからないファイルパスが正しいか確認
EACCESパーミッション拒否ファイルのパーミッションを確認
ETIMEDOUT実行timeoutタスクのスコープを小さくするか、thoroughnessを下げる
ENOMEMメモリ不足並列agentの数を減らす
ECONNREFUSEDAPI接続失敗ネットワーク接続とAPI Keyを確認

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

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

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

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