Agent 疑難排解指南：常見問題與解決方案

使用 Claude Code 的 Task tool 和 agents 時，你可能會遇到一些常見問題。本指南涵蓋最頻繁的問題及其解決方案。

常見問題分類

類型	典型症狀	常見原因
啟動問題	Agent 無法啟動、立即失敗	權限、配置、路徑錯誤
逾時問題	Agent 執行時間過長	Context 過大、任務複雜、資源限制
結果問題	結果不完整、不正確	Prompt 模糊、Context 不足
平行問題	Agents 未平行執行	錯誤的呼叫方式、資源競爭
效能問題	速度慢、記憶體消耗大	模型選擇、任務設計

問題 1：Agent 無法啟動或立即失敗

症狀

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore auth module"
})
// 錯誤: "Failed to start agent" 或立即返回錯誤

可能原因與解決方案

原因 1：工作目錄錯誤

解決：

# 確認你在專案根目錄
pwd
# 應該看到專案路徑，例如 /Users/you/projects/my-app

# 如果不在，切換到正確目錄
cd /path/to/your/project

原因 2：Git Repository 未初始化

問題：某些 agent 功能需要 git 歷史記錄。

解決：

# 初始化 git repo
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 執行逾時

症狀

Agent 執行超過預期時間（例如 2 分鐘以上），沒有返回結果。

可能原因與解決方案

原因 1：任務範圍太廣

問題：Prompt 太模糊，導致 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：使用過高的徹底程度

問題：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：Context 過大

問題：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 在背景執行，你以為逾時了。

解決：

// 啟動背景任務
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：Prompt 模糊

問題：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：單次請求太多問題

問題：Prompt 包含太多要求，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：Context 不足

問題：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 的徹底程度等級不當。

解決：

// 對快速概覽使用 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：Parallel Agents 沒有平行執行

症狀

你啟動了多個 agents，但它們似乎依序執行而非平行。

可能原因與解決方案

原因 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：資源競爭

問題：太多 agents 同時執行，導致資源不足。

解決：限制平行數量

// 壞：10 個平行 agents
for (let i = 0; i < 10; i++) {
  Task({ prompt: `Task ${i}` })
}

// 好：分批執行（每批 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：Agents 有相依性

問題：後面的 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：Context 過載

問題：Agent 載入了太多不必要的檔案。

解決：縮小範圍

// 壞：探索整個 monorepo
Task({
  prompt: "Analyze entire monorepo"
})

// 好：聚焦特定套件
Task({
  prompt: "Analyze packages/auth/ only"
})

原因 3：重複工作

問題：多個 agents 重複分析相同的檔案。

解決：協調任務

// 壞：重複探索
Task({ prompt: "Analyze auth for security" })
Task({ prompt: "Analyze auth for performance" })
Task({ prompt: "Analyze auth for code quality" })
// 三次讀取相同檔案

// 好：分工
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-reviewer`	`Explore`
安全稽核	`security-auditor`	`code-reviewer`
測試分析	`test-runner`	`general-purpose`
除錯	`debugger`	`Explore`
重構	`refactor-assistant`	`general-purpose`

範例

// ❌ 錯誤：用 Explore 做安全稽核
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"
})

// 比較結果差異

何时尋求幫助

如果以上解決方案都無法解決你的問題：

檢查 Claude Code 版本：
```
claude --version
```
確保使用最新版本。
查看 GitHub Issues： https://github.com/anthropics/claude-code/issues
加入社群：
- Claude World Taiwan Discord
- #help 頻道
回報 Bug：在回報時包含：
- Claude Code 版本
- 作業系統
- 完整的錯誤訊息
- 重現步驟
- 最小可重現範例

快速參考：常見錯誤碼

錯誤碼	含義	解決方案
`ENOSP`	找不到指定路徑	檢查檔案路徑是否正確
`EACCES`	權限被拒絕	檢查檔案權限
`ETIMEDOUT`	執行逾時	縮小任務範圍或降低徹底程度
`ENOMEM`	記憶體不足	減少平行 agents 數量
`ECONNREFUSED`	API 連線失敗	檢查網路連線和 API Key

預防性最佳實踐

避免問題的最佳方法：

從小任務開始：先測試簡單任務，確認 agent 正常工作
使用適當的模型：Haiku 用於搜尋，Sonnet 用於推理
保持 Prompt 清晰：明確說明你想找什麼
分階段工作：探索 → 分析 → 實作
監控資源：留意記憶體和 CPU 使用量
保存工作結果：定期提交 git，避免遺失進度

遇到其他問題？在 Discord 的 #help 頻道提問，社群很樂意協助！