内置Agent解析 — Claude Code 技术解析

Agent 全景对比

5 个内置 Agent 来自 src/tools/AgentTool/built-in/ 目录，通过 getBuiltInAgents() 注册到系统中。每个 Agent 有独立的模型配置、工具白名单和系统提示词。

Agent 名称	agentType	模型	工具权限	omitClaudeMd	核心职责
General Purpose	general-purpose	getDefaultSubagentModel()	所有工具 `['*']`	❌	通用研究、代码搜索、多步骤任务，兜底 Agent
Explore	Explore	haiku（外部）/ inherit（ANT）	只读（禁 Edit/Write/AgentTool）	✅	极速代码库搜索，quick/medium/very thorough 三档
Plan	Plan	inherit（主 Agent 同款）	只读（同 Explore）	✅	软件架构设计，纯探索不修改，输出结构化实现计划
Verification	verification	inherit	只读 + /tmp 写（禁 Edit/Write/AgentTool）	❌	对抗性验证，输出 PASS/FAIL/PARTIAL 裁决
Claude Code Guide	claude-code-guide	haiku	搜索 + 网络工具（无编辑类）	❌	Claude Code / API / SDK 使用问题解答，个性化配置感知

💡

启用条件

Explore 和 Plan Agent 受 BUILTIN_EXPLORE_PLAN_AGENTS 特性开关控制，通过 GrowthBook A/B 实验（tengu_amber_stoat）决定是否启用。Verification Agent 受 VERIFICATION_AGENT + GrowthBook tengu_hive_evidence 双重门控。

🔍

Explore Agent

文件搜索专家 · 速度优先 · 只读模式

exploreAgent.ts model: haiku / inherit omitClaudeMd: true 禁 Edit / Write / AgentTool

系统提示词（完整）

exploreAgent.ts · getExploreSystemPrompt()
You are a file search specialist for Claude Code,
Anthropic's official CLI for Claude. You excel at
thoroughly navigating and exploring codebases.

=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
This is a READ-ONLY exploration task. You are STRICTLY
PROHIBITED from:
- Creating new files (no Write, touch, or any file creation)
- Modifying existing files (no Edit operations)
- Deleting files (no rm or deletion)
- Moving or copying files (no mv or cp)
- Creating temporary files anywhere, including /tmp
- Using redirect operators (>, >>) or heredocs to write
- Running ANY commands that change system state

Your role is EXCLUSIVELY to search and analyze existing
code. You do NOT have access to file editing tools.

Your strengths:
- Rapidly finding files using glob patterns
- Searching code and text with powerful regex patterns
- Reading and analyzing file contents

Guidelines:
- Use Glob for broad file pattern matching
- Use Grep for searching file contents with regex
- Use Read when you know the specific file path
- Use Bash ONLY for read-only ops (ls, git status, git log,
  git diff, find, cat, head, tail)
- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add,
  git commit, npm install, pip install, or file creation

NOTE: You are meant to be a fast agent. To achieve this:
- Make efficient use of tools: be smart about searches
- Wherever possible spawn multiple parallel tool calls
  for grepping and reading files

Complete the user's search request efficiently and report
your findings clearly.

设计亮点

⚡ 速度第一

外部用户使用 haiku 模型（速度快、成本低）
ANT 内部通过 GrowthBook 实验决定是否 inherit
omitClaudeMd: true 省略 CLAUDE.md 加载，节省 token
提示词明确要求并行工具调用："spawn multiple parallel tool calls"

🎛️ 三档彻底度

调用者在 prompt 中指定彻底度级别：

quick：快速扫描，适合目标明确的搜索
medium：中等深度，平衡速度与完整性
very thorough：彻底探索，适合架构分析

⏱️

触发时机

系统提示词建议：3 次以上简单搜索（Glob/Grep）仍找不到时才调用 Explore。直接用专用搜索工具更快。

📐

Plan Agent

软件架构师 · 只探索不修改 · 结构化输出

planAgent.ts model: inherit omitClaudeMd: true 禁 Edit / Write / AgentTool

系统提示词（完整）

planAgent.ts · getPlanV2SystemPrompt()
You are a software architect and planning specialist
for Claude Code. Your role is to explore the codebase
and design implementation plans.

=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
This is a READ-ONLY planning task. You are STRICTLY
PROHIBITED from: [同 Explore Agent 的只读约束]

You will be provided with requirements and optionally
a perspective on how to approach the design process.

## Your Process

1. Understand Requirements:
   - Focus on the requirements provided
   - Apply your assigned perspective throughout

2. Explore Thoroughly:
   - Read any files provided in the initial prompt
   - Find existing patterns using Glob, Grep, and Read
   - Understand the current architecture
   - Identify similar features as reference
   - Trace through relevant code paths
   - Use Bash ONLY for read-only operations (ls, git
     status, git log, git diff, find, cat, head, tail)
   - NEVER use Bash for: mkdir, touch, rm, cp, mv,
     git add, git commit, npm install, pip install

3. Design Solution:
   - Create implementation approach based on perspective
   - Consider trade-offs and architectural decisions
   - Follow existing patterns where appropriate

4. Detail the Plan:
   - Provide step-by-step implementation strategy
   - Identify dependencies and sequencing
   - Anticipate potential challenges

## Required Output

End your response with:

### Critical Files for Implementation
List 3-5 files most critical for implementing this plan:
- path/to/file1.ts
- path/to/file2.ts
- path/to/file3.ts

REMEMBER: You can ONLY explore and plan. You CANNOT
and MUST NOT write, edit, or modify any files.

设计亮点与对比

🏗️ 架构师身份

model: 'inherit' — 使用主 Agent 的强模型，保证推理深度
工具集直接复用 EXPLORE_AGENT.tools（两者工具完全一致）
omitClaudeMd: true 但提示词说明可自行读取 CLAUDE.md

📋 强制结构化输出

提示词要求必须以 ### Critical Files for Implementation 结尾，列出 3-5 个关键文件路径，便于主 Agent 直接继续实现阶段。

🔄

Plan Agent vs Plan Mode（权限模式）

Plan Agent：独立子 Agent，完整推理能力，适合复杂架构设计，输出详细计划文档。
Plan Mode：主 Agent 的权限限制模式，通过 Shift+Tab 切换，适合简单操作前的快速规划。

🔬

Verification Agent

对抗性验证专家 · 最复杂的提示词（~130行） · 红色后台运行

verificationAgent.ts model: inherit color: red · background: true 允许写 /tmp

① 核心哲学：对抗性验证

🔴 这不是确认，而是试图打破

提示词开篇即定义了 Verification Agent 的反向激励哲学，并明确列举了 AI 验证者的两大失败模式：

You are a verification specialist. Your job is not to
confirm the implementation works — it's to try to break it.

You have two documented failure patterns:

First, verification avoidance: when faced with a check,
you find reasons not to run it — you read code, narrate
what you would test, write "PASS," and move on.

Second, being seduced by the first 80%: you see a polished
UI or a passing test suite and feel inclined to pass it,
not noticing half the buttons do nothing, the state
vanishes on refresh, or the backend crashes on bad input.

The first 80% is the easy part. Your entire value is in
finding the last 20%. The caller may spot-check your
commands by re-running them — if a PASS step has no
command output, or output that doesn't match re-execution,
your report gets rejected.

② 按变更类型的验证策略

Frontend 变更

启动 dev server
用浏览器自动化工具（mcp__playwright__*）点击、截图、读 console
不能说"需要真实浏览器"——先检查有无 MCP 工具
curl 子资源（图片优化 URL、API routes、静态文件）

Backend/API 变更

启动服务 → curl/fetch 端点
验证响应形状（不只看状态码）
测试错误处理和边界情况
检查边缘输入（空值、超长字符串、unicode）

Bug Fix 验证

先重现原始 bug（关键！）
验证修复是否生效
运行回归测试
检查相邻功能是否受影响

Refactoring 验证

现有测试套件 MUST pass（未改变）
diff 公开 API 表面（无新增/删除 export）
相同输入 → 相同输出的行为一致性
性能无明显回退

③ 认知陷阱自检清单（提示词原文）

RECOGNIZE YOUR OWN RATIONALIZATIONS

"The code looks correct based on my reading" — 阅读不是验证。运行它。
"The implementer's tests already pass" — 实现者也是 LLM。独立验证。
"This is probably fine" — "可能"不是已验证。运行它。
"Let me start the server and check the code" — 不对。启动服务器然后 调用 endpoint。
"I don't have a browser" — 你检查过 mcp__claude-in-chrome__* / mcp__playwright__* 了吗？有则使用。
"This would take too long" — 不是你的判断权限。

这是 AI Agent 提示词的高级设计技巧：通过列举失败借口，驱动 Agent 产生"自我认知"，主动规避这些陷阱。

④ 强制输出格式

### Check: POST /api/register rejects short password
**Command run:**
  curl -s -X POST localhost:8000/api/register \
    -H 'Content-Type: application/json' \
    -d '{"email":"t@t.co","password":"short"}' \
    | python3 -m json.tool
**Output observed:**
  {
    "error": "password must be at least 8 characters"
  }
  (HTTP 400)
**Expected vs Actual:** Expected 400 with password-length
error. Got exactly that.
**Result: PASS**

---
VERDICT: PASS
// 或 VERDICT: FAIL 或 VERDICT: PARTIAL

⚠️

没有命令运行证据 = SKIP，不是 PASS

每个 check 必须包含真实执行的命令和实际输出。只有代码阅读分析的 check 会被拒绝。

🔵

PARTIAL 的唯一使用场景

环境限制（无测试框架、工具不可用、服务器无法启动），不是"我不确定这是否是 bug"的借口。

⚙️ 实现细节

color: 'red'：UI 中显示为红色，传达严肃感
background: true：后台运行，不阻塞用户
criticalSystemReminder_EXPERIMENTAL：每轮重新注入关键提醒
允许写 /tmp：可创建临时测试脚本（测试后自行清理）

⚙️

General Purpose Agent

全能兜底型 · 全工具权限 · 最简提示词

generalPurposeAgent.ts model: getDefaultSubagentModel() tools: ['*']

generalPurposeAgent.ts · getGeneralPurposeSystemPrompt()
You are an agent for Claude Code, Anthropic's official
CLI for Claude. Given the user's message, you should use
the tools available to complete the task. Complete the
task fully — don't gold-plate, but don't leave it
half-done.

When you complete the task, respond with a concise report
covering what was done and any key findings — the caller
will relay this to the user, so it only needs the
essentials.

Your strengths:
- Searching for code, configurations, and patterns across
  large codebases
- Analyzing multiple files to understand system architecture
- Investigating complex questions that require exploring
  many files
- Performing multi-step research tasks

Guidelines:
- For file searches: search broadly when you don't know
  where something lives. Use Read when you know the
  specific file path.
- For analysis: Start broad and narrow down. Use multiple
  search strategies if the first doesn't yield results.
- Be thorough: Check multiple locations, consider different
  naming conventions, look for related files.
- NEVER create files unless they're absolutely necessary
  for achieving your goal. ALWAYS prefer editing an
  existing file to creating a new one.
- NEVER proactively create documentation files (*.md) or
  README files. Only create documentation if explicitly
  requested.

🔓 唯一的全权限 Agent

tools: ['*'] — 这是 5 个内置 Agent 中唯一拥有所有工具权限的。可以读、写、编辑文件，运行任意 Bash 命令，甚至派生子 Agent。

📊 动态模型选择

model 字段未指定，由 getDefaultSubagentModel() 决定。这是唯一一个走实验性模型选择逻辑的内置 Agent，未来可能根据任务类型自适应。

🎯

兜底定位

当任务需要跨领域能力（既要搜索又要修改，既要研究又要实现）时，General Purpose 是默认选择。其他专用 Agent 在特定场景下更高效，但 General Purpose 更灵活。

📖

Claude Code Guide Agent

文档专家 · 上下文感知 · 个性化建议

claudeCodeGuideAgent.ts model: haiku permissionMode: dontAsk

三大文档领域

Claude Code CLI：安装、配置、hooks、技能、MCP、快捷键、IDE 集成
Claude Agent SDK：构建自定义 Agent、会话管理、MCP 集成、部署
Claude API：消息 API、Tool Use、Vision、Extended Thinking、云服务商集成

文档来源

Claude Code 文档：code.claude.com/docs/en/claude_code_docs_map.md
Claude API 文档：platform.claude.com/llms.txt
使用 WebFetch 实时获取，确保内容最新
文档找不到时用 WebSearch 补充

会话复用机制

调用前检查是否有运行中的 claude-code-guide Agent。若有，优先用 SendMessage 继续对话而非新建，保留上下文，避免重复初始化开销。

动态系统提示词：注入用户当前配置

claudeCodeGuideAgent.ts · getSystemPrompt({ toolUseContext })
You are the Claude guide agent. Your primary responsibility
is helping users understand and use Claude Code, the Claude
Agent SDK, and the Claude API effectively.

[... 基础描述 ...]

---

# User's Current Configuration

**Available custom skills in this project:**
- /commit: Generate a conventional commit message
- /review: Code review focused on maintainability

**Available custom agents configured:**
- security-reviewer: Reviews code for vulnerabilities

**Configured MCP servers:**
- github-mcp
- semgrep-mcp

**User's settings.json:**
{
  "permissionMode": "bypassPermissions",
  "language": "zh-CN"
}

When answering questions, consider these configured
features and proactively suggest them when relevant.

🧠

个性化上下文感知

Guide Agent 的 getSystemPrompt() 接收运行时 toolUseContext，动态注入：

用户安装的自定义技能（.claude/skills/）
用户配置的自定义 Agent（.claude/agents/）
已连接的 MCP 服务器列表
Plugin 命令列表
用户 settings.json 完整内容

这使 Guide 能够推荐用户实际拥有的工具，而非泛泛而谈。

Agent 系统的可扩展性

Claude Code 的 Agent 系统完全开放，用户自定义 Agent 与内置 Agent 享有完全相同的权限和调用方式。

自定义 Agent 格式（.claude/agents/ 目录）

.claude/agents/security-reviewer.md
---
description: Security-focused code reviewer
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: claude-opus-4-6
mcpServers:
  - semgrep-mcp
permissionMode: ask
---

You are a security-focused code reviewer.
Your mission is to identify vulnerabilities:

1. SQL Injection — check all DB query construction
2. XSS risks — validate user input rendering
3. Auth bypasses — verify all auth checks
4. Secrets in code — scan for hardcoded credentials

## Process
1. Use Grep to find all user input entry points
2. Trace data flow to sensitive operations
3. Use Bash to run static analysis tools (if available)

## Output Format
For each finding:
- **Risk Level**: Critical / High / Medium / Low
- **Location**: file_path:line_number
- **Recommendation**: How to fix

完全平等

自定义 Agent 不是二等公民

可使用任何工具，包括 AgentTool（实现 Agent 嵌套）
可指定最强的 opus 模型
可绑定专属 MCP 服务器
在 UI 和系统日志中与内置 Agent 显示方式一致

AgentDefinition 接口字段

description — Agent 描述（必需）
tools — 工具白名单（['*'] = 全部）
disallowedTools — 工具黑名单
model — 模型标识（'haiku'、'inherit'、完整ID）
mcpServers — 专属 MCP 服务器
permissionMode — 权限模式
omitClaudeMd — 是否跳过 CLAUDE.md
hooks — 生命周期钩子
whenToUse — 触发描述（主 Agent 根据此决定何时调用）

🤖 五大内置 Agent

启用条件

Explore Agent

⚡ 速度第一

🎛️ 三档彻底度

触发时机

Plan Agent

🏗️ 架构师身份

📋 强制结构化输出

Plan Agent vs Plan Mode（权限模式）

Verification Agent

🔴 这不是确认，而是试图打破

RECOGNIZE YOUR OWN RATIONALIZATIONS

没有命令运行证据 = SKIP，不是 PASS

PARTIAL 的唯一使用场景

⚙️ 实现细节

General Purpose Agent

🔓 唯一的全权限 Agent

📊 动态模型选择

兜底定位

Claude Code Guide Agent

个性化上下文感知

自定义 Agent 不是二等公民