Claude Code 的 claude-code-guide 子代理解剖：四域知识库、文档驱动检索流程与防"凭记忆作答"设计

2026-09-03 16:11:19作者：江焘钦

Extracted system prompts from Anthropic - Claude Fable 5, Opus 5, Claude Design, Claude Code. OpenAI - ChatGPT GPT-5.6-Sol, Codex. Google - Gemini 3.5 Flash, 3.1 Pro, Antigravity. xAI - Grok, Cursor, Copilot, VS Code, Perplexity, and more. Updated regularly.

项目地址：https://gitcode.com/GitHub_Trending/sy/system_prompts_leaks

system_prompts_leaks 仓库收录了 Claude Code 内置子代理 claude-code-guide 的完整系统提示（Anthropic/claude-code/agents/claude-code-guide.md）。该代理专职回答用户关于 Claude Code CLI、Claude Agent SDK、Claude API 与 Claude Tag（Claude in Slack）四类问题，其核心设计是"先抓取官方文档地图、再回答"的文档驱动流程，并配以防训练数据过时的显式规则。本文逐段拆解该代理的 frontmatter 配置、四域职责边界与三个易混淆概念的区分、文档源端点、七步检索流程和作答准则，并结合主系统提示中的代理注册清单说明它在 Claude Code 中的真实定位与调用方式。

一、frontmatter 元数据：一个"只读、免询问、跑在 Haiku 上"的咨询代理

该代理文件采用 Claude Code 自定义代理（custom agent）的标准格式，正文之前的 YAML frontmatter 定义了触发条件、工具白名单、模型与权限模式（claude-code-guide.md）：

---
name: claude-code-guide
whenToUse: Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about: (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API (formerly Anthropic API) - Messages API ..., Tool Runner (`client.beta.messages.tool_runner`) ..., Managed Agents ...; (4) Claude Tag (Claude in Slack) - what it is, setting it up for a Slack workspace, `/install-slack-app`. **IMPORTANT:** Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can continue via SendMessage.
tools: Bash, Read, WebFetch, WebSearch
model: haiku
permissionMode: dontAsk
---

各字段的含义与设计意图：

whenToUse：这是父代理调用该子代理前的"路由说明书"。它把触发场景枚举为四类问题（Claude Code / Agent SDK / Claude API / Claude Tag），并用典型问法（"Can Claude...", "Does Claude...", "How do I..."）作为模式示例。末尾的 IMPORTANT 段落要求：在 spawn 新代理之前，先检查是否已存在正在运行或最近完成的 claude-code-guide 实例，若有则通过 SendMessage 继续既有会话，而不是重复创建——这是对子代理"可复用、可续接"生命周期的一次显式约束。
tools: Bash, Read, WebFetch, WebSearch：工具白名单刻意最小化。WebFetch 与 WebSearch 承担"抓取官方文档"的核心职责；Read 与 Bash（配合文档中提到的 Glob、Grep 语义）用于检查本地工程中的 CLAUDE.md、.claude/ 目录等项目文件；没有 Write/Edit，说明它是纯咨询型代理，不修改用户代码。
model: haiku：指定跑在 Haiku 级别模型上。文档抓取是机械性的检索-摘要工作，用更小更快的模型控制延迟与成本，而把"回答质量"的保证交给"以官方文档为准"的规则，而不是更大的模型。
permissionMode: dontAsk：免询问权限模式。抓取文档、读本地文件这类只读操作不需要逐个向用户弹确认，保证问答流程不被打断。

二、角色定位与四大知识域

正文开头一句话定调（claude-code-guide.md#L9）："You are the Claude guide agent"，首要职责是帮助用户理解并有效使用 Claude Code、Claude Agent SDK 与 Claude API。随后文档明确划出四个知识域，每个域都附带了精确的范围描述。

域 1：Claude Code（CLI 工具）

覆盖安装、配置、hooks、skills、MCP 服务器、键盘快捷键、IDE 集成、settings 与工作流（claude-code-guide.md#L13）。这一域对应日常使用者问"某个 slash 命令怎么用""hook 怎么写"的场景。

域 2：Claude Agent SDK

文档对该域的定义信息密度很高（claude-code-guide.md#L15），要点如下：

Agent SDK 是"把 Claude Code 打包成库"：Python 包名为 claude-agent-sdk，TypeScript 包名为 @anthropic-ai/claude-agent-sdk；
它携带完整的 Claude Code harness（agent loop、上下文管理、会话、hooks、子代理、权限、MCP）外加内置工具——Read、Write、Edit、Bash、Glob、Grep、WebSearch、WebFetch——因此代理无需自己实现工具执行逻辑；
部署方式：你自己托管（You host and deploy it）；
文档特别强调它与 Anthropic API SDK 的 Tool Runner 是不同包，也不是 Managed Agents（后者是 Anthropic 托管、按会话提供沙箱）。并给出一条作答纪律：与 Tool Runner 对比时，必须点明包名和内置工具清单，不得把 Managed Agents 的特性（托管沙箱、memory stores）安到 Agent SDK 头上。

域 3：Claude API（原 Anthropic API）

该域同样强调"多个 surface（接口面）的精确区分"（claude-code-guide.md#L17）：

Messages API：直接请求/响应式调用；
Tool Runner（client.beta.messages.tool_runner）与手动 tool-use 循环：围绕你自己定义的工具跑 agent 循环。文档特意说明 Tool Runner"不是裸循环"——它提供每轮 hooks，支持 human-in-the-loop 审批（approval gates）、错误拦截、结果改写与重试，"这些不需要你降级到手动循环才能实现"；
Managed Agents：服务器托管的有状态代理，配 Anthropic 管理的沙箱，"创建一次 agent、启动多个引用它的 session"。

文档在此域中连续使用了三处"Do not conflate"级别的防混淆指令，构成一张三概念对照关系（整理自原文）：

维度	Tool Runner（Claude API SDK）	Claude Agent SDK	Managed Agents
工具来源	你定义的工具	内置工具（Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch）+ 自定义	平台侧能力（Skills + MCP 等）
Harness 范围	循环 + 每轮 hooks（审批/拦截/改写/重试/流式）	完整 Claude Code harness（会话、hooks、子代理、权限、MCP）	托管沙箱内的有状态会话
部署方	你自行托管	你自行托管	Anthropic 托管

文档还给了两条硬性规则：不要把 Claude API 的 Tool Runner 与 Claude Agent SDK 混为一谈——它们是不同产品；不要把 Agent SDK 与 Managed Agents 混为一谈——前者只有 harness、由你托管，后者由 Anthropic 托管部署。

域 4：Claude Tag（Claude in Slack）

Claude 以"组织内的同事"身份在 Slack 频道工作，每个线程背后是一个远端 Claude Code 会话。文档明确了四个必答点（claude-code-guide.md#L19）：它是什么；组织负责人如何启用（Admin settings → Claude Tag，或在 Slack 中 @Claude connect）；/install-slack-app 命令——仅在 Claude.ai 订阅者会话中可用，当它缺席时，组织负责人需通过 Admin 设置或 Slack 中的 @Claude connect 启用；以及其配置方式。

三、文档源端点：四类问题对应四个抓取入口

该代理最重要的部分是其"Documentation sources"清单（claude-code-guide.md#L21-L55）。每个文档域绑定了一个可抓取的索引端点，并附上该端点能回答的问题范围：

Claude Code 文档：端点 https://code.claude.com/docs/en/claude_code_docs_map.md（Claude Code 文档地图）。适用问题包括：安装与上手、Hooks（命令执行前后）、自定义 skills、MCP 服务器配置、IDE 集成（VS Code、JetBrains）、settings 文件与配置、键盘快捷键、子代理与插件、沙箱与安全。
Claude Agent SDK 文档：同一个 Claude Code 文档地图端点。文档中有一条非常醒目的易错点警告：Agent SDK 文档位于 code.claude.com 的 Claude Code 文档地图中，而不在 platform.claude.com 的 Claude API 文档里——"对任何 Agent SDK 问题都要抓取这个 URL，platform.claude.com 的索引里并不列出 Agent SDK 页面"。该端点覆盖：SDK 概览与上手（两个包名）、内置工具与 agent loop、代理配置与自定义工具、会话管理与权限、MCP 集成、自托管与部署（再次强调"你托管——Anthropic 不托管 Agent SDK 应用"）、成本追踪与上下文管理。
Claude API 文档：端点 https://platform.claude.com/llms.txt。覆盖 Messages API 与流式、工具调用（function calling）与 Anthropic 定义的工具（computer use、代码执行、web search、文本编辑器、bash、programmatic tool calling、tool search tool、context editing、Files API、结构化输出）、Tool Runner（原文再次强调：审批门、错误拦截、结果改写、重试与流式都不需要手动循环）、Managed Agents（服务器托管有状态代理、Anthropic 管理的沙箱、SSE 事件流、Skills + MCP、文件挂载）、prompt caching、视觉/PDF/引用、扩展思考与结构化输出、远程 MCP 服务器的 MCP connector、云厂商集成（Bedrock、Vertex AI、Foundry）。
Claude Tag / Claude in Slack 文档：端点 https://claude.com/docs/llms.txt。文档注明这些页面不在上面的 Claude Code 文档地图里，它们位于 claude.com 文档域；建议先抓概述页 https://claude.com/docs/claude-tag/overview.md，再按需抓具体页面。

从端点命名规律（.../llms.txt、.../docs_map.md）可以推断，这套设计面向的是"给 LLM 看的文档索引"：先抓轻量索引拿到候选页面清单，再二次抓取具体页面，而不是让代理去翻 HTML 站点。

四、七步检索流程：先定位域，再抓文档，最后才作答

"Approach" 部分定义了固定的工作流（claude-code-guide.md#L57-L64）：

判断用户问题落在哪个域（四域之一）；
用 WebFetch 抓取对应的文档地图/索引；
从索引中识别最相关的文档 URL；
抓取具体的文档页面；
基于官方文档给出清晰、可执行的指引；
若文档未覆盖该主题，改用 WebSearch；
在相关时用 Read、Glob、Grep 引用本地工程文件（CLAUDE.md、.claude/ 目录）。

流程的关键特征是把"抓取官方文档"放在"作答"之前、把 WebSearch 降级为文档覆盖不足时的兜底、把本地文件引用限定为"相关时"。也就是说，该代理被设计为一个**检索优先（retrieval-first）**的回答器：训练知识只用于理解问题措辞，答案的事实来源必须是当次抓取到的文档。

五、防过时与防幻觉准则：对"凭记忆作答"的显式封杀

"Guidelines" 部分是整篇提示中最有工程价值的段落（claude-code-guide.md#L66-L76），逐条拆解：

官方文档永远优先于假设（"Always prioritize official documentation over assumptions"）。
承认训练数据会过时，且不得"静默作答"：原文直说"你关于 Claude Code 命令、flag 与设置的训练数据可能已经过时"。如果 WebFetch 或 WebSearch 失败、无法触达文档，不允许悄悄用记忆回答，而必须：告知用户"我没能触达文档"、给出你手头最好的答案、并明确标注它可能过时，同时附上指向官方文档（code.claude.com 文档）的链接。这是把"检索失败"从静默降级变成显式声明。
Claude Tag 必须在线查：Claude Tag 比训练数据更新，且替代了早期按用户的 "Claude in Slack" 应用，因此"绝不凭记忆回答 Claude Tag 问题——先抓取上述 Claude Tag 文档"。
回答保持简洁、可执行；有帮助时附具体示例或代码片段；回答中引用确切的文档 URL。
主动发现特性：主动建议相关的命令、快捷键或能力，帮助用户发现功能，而非只做被动问答。
结尾还规定了兜底出口：当找不到答案或该特性不存在时，引导用户到官方 issue 仓库（anthropics/claude-code 的 issues）反馈（claude-code-guide.md#L75-L76）。

这套规则与 model: haiku 的配置组合起来看意图明显：用一个较小、更快、更便宜的模型 + 强检索流程，替代"用大模型硬记 CLI 细节"的传统做法；准确性不依赖参数规模，而依赖"抓取—核对—标注"的流程纪律。

六、在主系统提示中的注册：路由描述如何驱动父代理调用

这个子代理并不是孤立文件。在 Claude Code 各版本的主系统提示中（如 claude-code-fable-5.1.md、claude-code-opus-5.md），系统会在 ## Agents 一节列出所有可用代理类型及工具绑定。例如 claude-code-fable-5.1.md 中的注册条目把 whenToUse 全文注入父代理的系统提示，并注明 (Tools: Bash, Read, WebFetch, WebSearch)——即父代理看到的正是 frontmatter 中那份路由描述，这是父代理决定"何时该把问题交给 claude-code-guide"的唯一依据。

两个值得注意的版本演进细节：

范围在扩展：Fable 5 与 5.1 的注册条目比本文分析的独立代理文件多了一个域 (5)：claude plugin eval（编写与运行插件评测套件、其 JSON/报告、沙箱、CI、early-access 启用）以及 /skill-doctor 报告（对比见 claude-code-fable-5.md 与 claude-code-fable-5.1.md 的 Agents 小节）。
会话续接约束随注册条目下发：所有版本的条目都保留了那条 IMPORTANT 指令——spawn 前先检查是否有可续接的 claude-code-guide 实例。配合 SendMessage 机制，父代理可以对既有 guide 会话追加问题，保留其已抓取的文档上下文。

同一提示中还并列注册了其他内置代理，可对照理解分工：claude（兜底代理）、Explore（只读扇出搜索）、Plan（架构规划）、general-purpose（通用多步任务）、statusline-setup（状态栏配置，见 Anthropic/claude-code/agents/ 目录）。claude-code-guide 在其中是唯一绑定 Web 工具、唯一以"答产品问题"为职责的代理。

另外，仓库内的调试技能 Anthropic/claude-code/skills/debug/SKILL.md 在其 Instructions 中也建议"考虑启动 claude-code-guide 子代理来理解相关的 Claude Code 特性"（第 3 步），说明该代理还被其他内置能力当作"官方文档问答器"复用。

七、从该代理设计可提炼的实践要点

子代理的价值在于窄职责 + 强流程：claude-code-guide 不写代码、不探索仓库，只做"域判定 → 抓索引 → 抓页面 → 作答"，工具白名单（Bash, Read, WebFetch, WebSearch）与 dontAsk 权限模式都服务于这条流水线。
把"文档端点"写进提示是检索式问答的基础设施：为每个知识域绑定明确的索引端点（llms.txt / docs map），并对易混淆的端点归属（Agent SDK 文档在 code.claude.com 而非 platform.claude.com）给出显式纠偏，直接降低抓错源的概率。
防过时规则比防幻觉规则更关键：对"CLI 命令、flag、设置"这类高频变动信息，提示词的做法是禁止静默降级到记忆，而是强制"声明未触达文档 + 标注可能过时 + 附官方链接"三件套；对训练数据中根本不存在的较新功能（Claude Tag），则完全禁止凭记忆作答。
概念防混淆要写成成对指令：文档用"必须点明包名与内置工具""不得把托管沙箱特性安到 Agent SDK 头上"等成对表述锁定 Tool Runner / Agent SDK / Managed Agents 三个产品的边界，这类表述对约束 LLM 输出有直接作用。