Claude Code 内置 Explore 子代理提示词全解：只读、快速、并行的代码搜索 Agent 设计（基于 system_prompts_leaks 收录的 v2.1.211 原始抓取）

本篇解读 Explore.md —— Claude Code 内置 "Explore" 子代理的完整系统提示词：frontmatter 路由描述、只读约束、搜索工具指引与"快速返回"性能要求。读完你可以掌握 Claude Code 是如何把一个"只读搜索专家"子代理设计出来的：哪些字段控制它的调度与工具面，提示词正文如何多层级地锁死只读行为，以及这套设计对自写 .claude/agents/*.md 子代理的可借鉴之处。

1. Explore 是什么：Claude Code 内置的文件搜索专家

Explore 是 Claude Code（Anthropic 官方 CLI 智能体框架）内置的只读代码搜索子代理。根据仓库中收录的同版本主循环系统提示词 claude-code-opus-5.md，它出现在 Agent 工具的可用代理注册表中，注册表给出的调度描述为：

Explore: Read-only search agent for broad fan-out searches — when answering means sweeping many files, directories, or naming conventions and you only need the conclusion, not the file dumps. It reads excerpts rather than whole files, so it locates code; it doesn't review or audit it. Specify search breadth: "medium" for moderate exploration, "very thorough" for multiple locations and naming conventions. (Tools: All tools except Agent, Artifact, ExitPlanMode, Edit, Write, NotebookEdit)

一句话概括其职责边界："定位代码，而非审查代码"。它读取文件摘录（excerpts）而不是完整文件，因此擅长回答"X 在哪里定义 / 哪些文件引用了 Y / 某符号出现在哪些位置"这类问题，但不适合做代码评审、设计文档审计或跨文件一致性检查。

关于这份文档的采集来源，Explore.md 中的注释交代得很清楚：

• 内置 Explore 代理的提示词是按环境生成的（v2.1.211 二进制中的 gpg() 函数负责生成）；
• 文档正文是一次逐字的 MITM 抓包（2026-07-16，v2.1.211，macOS 原生构建）——即每个原生 macOS/Linux 会话实际渲染得到的提示词；
• frontmatter 中的两条描述（whenToUse 与 whenToUseLean）都存在于二进制内，只是服务于不同的提示词风格（见第 2 节）。

也就是说，这份文档不是"模板原件"，而是某个具体版本、具体构建渠道下真实下发到模型的系统提示词，这也是它作为一手研究材料价值最高的原因。

2. frontmatter 逐字段拆解

Explore.md 的 frontmatter 共 6 个字段，完整原文如下：

---
name: Explore
whenToUse: 'Fast read-only search agent for locating code. Use it to find files by pattern (eg. "src/components/**/*.tsx"), grep for symbols or keywords (eg. "API endpoints"), or answer "where is X defined / which files reference Y." Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: "quick" for a single targeted lookup, "medium" for moderate exploration, or "very thorough" to search across multiple locations and naming conventions.'
whenToUseLean: 'Read-only search agent for broad fan-out searches — when answering means sweeping many files, directories, or naming conventions and you only need the conclusion, not the file dumps. It reads excerpts rather than whole files, so it locates code; it doesn''t review or audit it. Specify search breadth: "medium" for moderate exploration, "very thorough" for multiple locations and naming conventions.'
disallowedTools: [Agent, Artifact, ExitPlanMode, Edit, Write, NotebookEdit]
model: inherit
omitClaudeMd: true
---

各字段的作用：

字段	值	作用
name	Explore	代理类型名，主循环通过 Agent 工具的 subagent_type 参数选中它
whenToUse	经典版路由描述	面向"经典提示词"模型渲染，用于让主循环模型决定何时该派 Explore
whenToUseLean	精简版路由描述	面向"lean 提示词"模型（按文档注释：Opus 4.8+ / Fable）渲染，措辞更短
disallowedTools	[Agent, Artifact, ExitPlanMode, Edit, Write, NotebookEdit]	工具黑名单，从工具层面禁止写操作与二次委派
model	inherit	默认继承父代理模型；文档注释补充：当主循环模型高于 opus 时，会被覆盖为 opus
omitClaudeMd	true	从字段命名看，表示该子代理不加载项目的 CLAUDE.md 上下文——搜索任务不需要项目级背景，省去 token 消耗（此为基于命名的推断）

两条 whenToUse 描述的核心信息可以归纳为三点：

1. 适用场景：按 glob 模式找文件（如 src/components/**/*.tsx）、按符号/关键词 grep（如 API endpoints）、回答"X 在哪定义 / 谁引用了 Y"；
2. 禁用场景：代码评审、设计文档审计、跨文件一致性检查、开放式分析——因为它"读取摘录而非完整文件，会漏掉读取窗口之外的内容"（will miss content past its read window）；
3. 调用约定：调用方必须显式指定搜索广度（search breadth）。

值得注意的一个细节：whenToUse 提供三档广度（quick / medium / very thorough），而 whenToUseLean 只保留两档（medium / very thorough）。这与 claude-code-opus-5.md 注册表中的描述一致——注册表使用的正是 lean 版本措辞，说明该版本的渲染管线选择了 lean 描述。

3. 提示词正文：只读约束是如何层层锁死的

正文（Explore.md 第 12 行起）先给出身份定义：

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 file creation of any kind)
- 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 to files
- Running ANY commands that change system state

禁止清单覆盖了 7 类行为：新建文件、修改文件、删除文件、移动/复制文件、在任何位置（包括 /tmp）创建临时文件、用重定向操作符（>、>>、|）或 heredoc 写文件、以及任何改变系统状态的命令。注意最后一条是兜底条款——前六条枚举的是具体手段，第七条则把所有"改状态"的企图一网打尽。

随后提示词给出了能力声明与收尾句：

Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.

这句话很关键：它不只说"不许改"，而是断言"你根本没有编辑工具，尝试会失败"。这体现了双保险设计：

• 提示词层面：自然语言禁令 + "尝试会失败"的预期设定，防止模型在 Bash 中绕道执行写操作（比如用 touch、echo > file 之类）；
• 工具层面：disallowedTools 中的 Edit、Write、NotebookEdit 直接移除了文件编辑工具，Agent 的移除则禁止它把任务再次委派出去（防止"套娃"子代理绕过约束）。

能力声明部分列出三项强项：

• 用 glob 模式快速找文件（Rapidly finding files using glob patterns）
• 用强大的正则搜索代码与文本（Searching code and text with powerful regex patterns）
• 读取并分析文件内容（Reading and analyzing file contents）

4. 环境差异：Bash 的 find/grep vs Glob/Grep 工具

"Guidelines" 小节（Explore.md 第 31–38 行）给出了本次抓取（macOS 原生构建）下的工具使用指引：

• 用 Bash 执行 find 做宽泛的文件模式匹配；
• 用 Bash 执行 grep 做带正则的文件内容搜索；
• 已知具体文件路径时用 Read；
• Bash 仅限只读操作：ls, git status, git log, git diff, find, grep, cat, head, tail；
• Bash 严禁用于：mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install，或任何文件创建/修改；
• 根据调用方指定的 thoroughness 级别调整搜索策略；
• 最终报告直接作为普通消息发出——不要试图创建文件。

文档注释（Explore.md）还揭示了这段指引的环境依赖性：

1. 在不带内置搜索的构建（npm 安装 / Windows）中，同一模板会渲染成 "Use Glob / Use Grep" 的指引（即引导使用 Glob/Grep 这两个专用工具，而非 Bash 的 find/grep）；
2. 在 Windows 上，只读命令清单会变成 PowerShell 等价写法；
3. 本次抓包得到的实际工具面为 13 项：Bash, Cron*, DesignSync, Enter/ExitWorktree, Monitor, PushNotification, Read, RemoteTrigger, ReportFindings, SendMessage, Skill, TaskStop, WebFetch, WebSearch——其中没有 Glob/Grep。

仓库中的归档工具定义可以为上述"原生构建用 Bash 的 find/grep"提供背景印证：

• glob-tool.md 注释指出：截至 2.1.211，Glob 已不在原生构建主代理的默认工具集中（自 ~2.1.117，2026 年 4 月起被经 Bash 调用的内置 bfs 取代），并给出了 Glob 工具的完整 JSON Schema（pattern 必填、path 可选）；
• grep-tool.md 同理：Grep（基于 ripgrep）也退出了主代理默认工具面，Schema 中 output_mode 支持 content / files_with_matches / count，head_limit 默认 250，还支持 -A/-B/-C 上下文、multiline 等参数；
• 两份归档文档均提到：这两个工具仍可通过完整的 --tools 白名单显式恢复给主代理。

这里需要谨慎说明一处口径差异：归档文档声称"搜索类子代理（Explore 等）仍然收到 Glob/Grep"（2026-07-16 对 Explore 子代理做过提取验证），而 Explore.md 的注释中列出的该次抓取工具面并不含 Glob/Grep。从两个文档的字面看，差异可能与构建渠道或抓取时的工具白名单有关；可以推断的是：主代理已剥离 Glob/Grep 是确定的版本事实，而 Explore 在不同构建中到底拿到"专用搜索工具"还是"Bash 版 find/grep"，由模板按环境渲染，这一点正是该提示词"按环境生成"机制的直接体现。

5. 搜索广度与"快速返回"的性能设计

Explore 的第二个设计支柱是速度。正文末尾的 NOTE 段（Explore.md）写道：

NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:

• Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations
• Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files

即它被明确要求"尽快返回"，手段是：聪明地规划搜索路径、尽可能在一条消息中发起多个并行的工具调用（并行 grep + 并行读文件）。这与主循环提示词中的调度指引（claude-code-opus-5.md 第 164 行）呼应：

When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.

搜索广度（search breadth） 则是把"搜多彻底"这件事从提示词里拿掉、交给调用方在任务描述中指定：

广度档位	语义（来自 whenToUse 原文）
quick	单次定向查找（仅经典版描述提供此档）
medium	中等程度的探索
very thorough	跨多个位置、多种命名约定地搜索

提示词正文要求 Explore "根据调用方指定的 thoroughness 级别调整搜索方法"（Adapt your search approach based on the thoroughness level specified by the caller）。这种"广度由调用方参数化、而非硬编码在提示词里"的做法，让同一份子代理定义能弹性适配从"查一个符号"到"全仓库扫命名约定"的谱系。

代价同样被写得很直白：它读的是摘录，读取窗口之外的内容会漏。所以注册表描述反复强调"你只需要结论，不需要文件内容转储"（you only need the conclusion, not the file dumps），而"审查/审计类"任务应交给别的能力——在本仓库收录的兄弟代理中，例如同样带只读约束块、但职责是"探索 + 设计实现计划"的 Plan 代理（它要求输出分步计划并列出 3–5 个 Critical Files），或工具面完整的 general-purpose 代理（Agent 工具未指定 subagent_type 时的默认值）。

6. 仓库内佐证：Explore 在多代理体系中的位置

结合 claude-code-opus-5.md 中 Agent 工具的 Schema，可以完整还原 Explore 的调度链路：

• 选型：subagent_type 参数选择代理类型，省略时落到 general-purpose（第 195 行）；
• 模型：调用方可用 model 参数覆盖（枚举 sonnet / opus / haiku / fable），其优先级高于代理定义 frontmatter 中的 model 字段；Explore 定义为 inherit，且按 Explore.md 注释，当主循环模型高于 opus 时会被覆盖为 opus（第 224–233 行）；
• 运行方式：子代理默认后台运行，完成后以通知送达结果；需要结果才能继续时传 run_in_background: false 同步执行（第 205、234–237 行）；
• 隔离：isolation: "worktree" 会为代理创建一个临时 git worktree（未改动则自动清理）——Explore 虽然极少需要，但机制对全体子代理可用（第 204、238–239 行）;
• 结果流转："The agent's final report is not shown to the user — relay what matters"——Explore 的终报不直接展示给用户，由主循环模型转述要点；这也解释了提示词为何强调"把最终报告直接作为普通消息发出来，不要创建文件"；
• 定义来源：每个代理类型的模型、推理努力与工具面都来自其定义——.claude/agents/*.md 的 frontmatter 或 SDK 的 agents 参数（第 203 行）。Explore 正是内置的其中一份。

从 agents 目录 的整体结构看，Explore 与 Plan.md、general-purpose.md、claude.md、claude-code-guide.md、statusline-setup.md 并列，共同构成内置代理族。其中 Plan 与 Explore 共享同一套 === CRITICAL: READ-ONLY MODE === 只读样板和 disallowedTools 黑名单——可以推断，"只读探索 + 工具面裁剪"是 Claude Code 内置代理中一个成型的模式：凡是不需要写盘的任务，都用 prompt 禁令 + 工具黑名单双保险收敛风险。

7. 工程启示：从 Explore 提炼的搜索子代理设计清单

把 Explore.md 的设计决策抽象出来，自写一个"只读搜索型"子代理（放在项目的 .claude/agents/*.md，按 claude-code-opus-5.md 所述 frontmatter 约定解析）时可以对照以下清单——每一条都能在上述原文中找到出处：

1. 路由描述写双向：whenToUse 既写"何时用"（glob 找文件、grep 符号、查定义/引用），也写"何时别用"（评审、审计、一致性检查），并用一句技术原因解释（读摘录、有读取窗口）；
2. 广度参数化：定义 2–3 档搜索广度词表，要求调用方在任务描述中指定，代理正文只负责"按级别调整"；
3. 只读双保险：提示词列出禁止行为清单（含 /tmp、重定向、heredoc、一切改状态命令的兜底条款），同时用 disallowedTools 移除 Edit/Write 等工具，并在提示词中明示"尝试编辑会失败"；
4. 命令白名单而非黑名单：给出 Bash 只读命令清单（ls, git status, git log, git diff, find, grep, cat, head, tail）+ 明令禁止清单（mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install）；
5. 速度即身份：开头或结尾声明"你是被期望尽快返回的 fast agent"，并给出具体手段——规划好再搜、单条消息内并行发起多个 grep/Read 调用；
6. 报告即消息：终报以普通消息形式返回，禁止落盘；主循环负责向用户转述关键结论；
7. 上下文裁剪：搜索任务不需要项目记忆时，omitClaudeMd: true 省掉 CLAUDE.md 加载（本字段语义为基于命名的推断）；模型用 inherit 并知晓高配模型会被钳制到 opus 的覆盖规则。

参考资料（均为本仓库内文件）

• Explore 子代理完整提示词（本文主体）
• Plan 子代理（同族只读样板对照）
• general-purpose 子代理（Agent 工具默认类型）
• claude 后台任务代理
• Claude Code 主循环系统提示词（Agent 工具 Schema 与代理注册表，v2.1.x）
• Glob 工具定义归档（含 2.1.211 工具面变迁注释）
• Grep 工具定义归档（含 2.1.211 工具面变迁注释）
• Anthropic 目录说明（各文件对应哪个产品）