企业官网建设流程全解析

"这东西有什么用"聊到"它底下是怎么跑的"，一篇讲完。

目录

入门篇

1. 一个比喻理解 SubAgent
2. SubAgent 解决的三个核心问题
3. 你可能已经在使用了
4. 什么时候该用，什么时候不该用

实践篇

1. 三步创建自定义 SubAgent
2. 配置文件完全指南
3. 前台、后台与恢复
4. 最佳实践：Prompt 怎么写

原理篇

1. 为什么 SubAgent 是一个微型会话
2. 两条路径的设计取舍：专业化 vs 缓存效率
3. 权限模型：单向棘轮原则
4. 工具池设计：最小权限原则的实际落地
5. 生命周期管理
6. Agent 定义的加载策略：信任的梯度
7. MCP Server 的隔离策略：共享 vs 专属的取舍
8. Worktree 隔离：让子代理在自己的沙箱里改代码
9. 从 Sub-Agent 到 Multi-Agent：架构选型的三角博弈

附录

1. 总结一下源码里藏着的设计巧思
2. 源码关键文件索引

入门篇

1. 一个比喻理解 SubAgent

想象你是一个项目经理（主 Agent），手下有几个专员（SubAgent）。你不会自己去翻 200 个文件找答案——你会把任务交给调研专员，让他去翻，他翻完了最终再把结论汇报给你。

这就是 SubAgent 做的事：主 Agent 把任务派给一个独立的子进程去执行，子进程干完后只把结论带回来。

比如 Claude Code 内部的工具调用：

Agent({ SubAgent_type: "Explore", prompt: "搜索整个代码库，找出所有 API 端点定义" })

这段调用会启动一个 Explore 类型的子代理，它自己去搜索、读取文件、分析代码，最后把结果摘要返回。主 Agent 只看到结论不看到过程。

一句话总结：SubAgent = 一个拥有独立上下文窗口的自治 Worker，干完活只交结论。

2. SubAgent 解决的三个核心问题

问题一：上下文污染

Claude 的上下文窗口再大也是有限的。如果让主 Agent 自己去搜 30 个文件，那些搜索结果、文件内容、中间分析全部留在主对话里，等真正要做决策时，那上下文窗口可能已经快满了。

SubAgent 的解决方案是让自己天然拥有一个独立的上下文窗口。即中间过程全都留在子代理里，主对话只看结论。也就是说子代理执行完毕后，这些中间内容就消失了。

简单判断：如果信息对当下执行是必要的，但对后续决策是噪声——用子代理。

问题二：行为不可控

主 Agent 通常拥有完整的工具权限（读文件、写文件、执行命令）。但某些任务你只想让它"看"，不想让它"改"。

对于这个问题 SubAgent 的解决方案是精确的工具权限控制。即我们可以定义一个只读型子代理，只给它Read、Grep、Glob三个工具，这样它想改也改不了了。

# 只读型子代理（代码审查） tools: Read, Grep, Glob # 开发型子代理（bug 修复） tools: Read, Write, Edit, Bash # 研究型子代理（技术调研） tools: Read, WebFetch, WebSearch

问题三：经验无法沉淀

每次都要手动告诉 Claude "去查这个、用那个方式分析"。这些操作步骤无法复用。

针对这个问题 SubAgent 的解决方案是配置即文件。子代理的定义保存在.md文件中，可以放进 Git 与团队共享，好用的配置可以复制到其他项目。

所以 SubAgent 可以用三个词概括：隔离、约束、复用。那么再从更高层面看 SubAgent 的设计哲学，其实就是将一个大脑拆成多个岗位角色，每个岗位只做一件事，并且有明确的权限边界。

3. 你可能已经在使用了

Claude Code 内置了几个 SubAgent。当你在对话里说”帮我看看代码库结构”、”先规划一下怎么做”、或者 Claude 自动走验证流程的时候，这些 SubAgent 就在干活。而你可能根本没注意到。

Explore（代码库的搜索引擎）

Explore 是最常用的内置 SubAgent。它的定位很明确：快速搜索、只读分析。

当我们在对话里说比如”帮我找一下所有 API 端点的定义”或者”这个函数在哪些地方被调用了”，Claude 就会启动 Explore 去干活。它会把成百上千行的 grep 结果、文件读取、路径分析全吞进自己的上下文里，最后只给你一份干净的摘要。

搜索深度分三档：quick、medium（默认）、very thorough。这个档位是可以在 prompt 里指定的，Explore 会据此调整搜多广。这不是代码层面的硬限制，纯粹是 prompt 级别的指导：

• quick 就是跑几条 grep 就收工，适合”某个 class 在哪个文件”这种目标明确的问题
• medium 则会多搜几个路径、多读几个文件，适合”这个模块的结构是怎样的”
• very thorough 会在多个目录和命名规范下反复搜，尽量不留死角——适合”梳理认证流程从入口到数据库的完整调用链”。

工具方面 Explore 能用 Glob（按文件名搜）、Grep（按内容搜）、Read（读文件）、Bash（但只能跑只读命令）。在前段时间 Claude Code 暴露的源码里使用disallowedTools硬性屏蔽了 Edit、Write、NotebookEdit。说明它确实改不了东西。

外部用户跑 Explore 用的是 Haiku，快且便宜。Anthropic 内部用户则会继承主 Agent 的模型。

Claude Code 暴露的源码里有个不太起眼的阈值：EXPLORE_AGENT_MIN_QUERIES = 3。这个参数的作用是，主 Agent 被告知任务只需要 1-2 次搜索就搞定的别启动 Explore，直接用 Grep/Read，只有明确需要 3 次以上查询时才值得派出去。

另外，Explore 默认省略 CLAUDE.md 和 gitStatus（能到 40KB）。只读代理不需要知道 commit 规范和 PR 流程，自己会跑git status。这一项每周会省 5-15 Gtok。

Plan（动手之前先想清楚）

Plan 的定位是软件架构师。它不写代码，专门在动手之前把方案想透。

比如当我们跟 Claude 说”我想给系统加个支付模块”，这个时候 Claude 就会先派 Plan 去调研，Plan 会读现有代码、找已有的模式和约定、理清依赖关系、最后输出一份分步实施计划。

系统提示给 Plan 定义了四步流程：

• 理解需求
• 深入探索（读代码、追踪调用链、参考已有实现）
• 设计方案（考虑取舍）
• 输出计划（分步策略、依赖关系、可能的坑）。

输出必须以”Critical Files for Implementation”结尾，并列出最关键的 3-5 个文件，这样主 Agent 拿到这份计划就知道下一步该读什么、改什么了。

Plan 跟 Explore 一样只读——同样的使用了disallowedTools，改不了文件。但模型不同：Plan 继承主 Agent 的模型，不会降级到 Haiku。架构设计需要更强的推理能力，用便宜模型容易翻车。

Explore 和 Plan 的分工边界是：Explore 搜完就交结果，Plan 搜完还要分析、权衡、给建议。找函数在哪用 Explore，搞清”加这个功能要改哪些文件、按什么顺序改”用 Plan。

General-purpose（什么都干的全能选手）

Explore 和 Plan 都被硬性禁止了 Edit、Write 等工具，但 General-purpose 没这个限制。tools: ['*']，即父 Agent 有什么它就能用什么，这是它跟 Explore/Plan 的根本区别。搜索和规划是只读的活儿，而 General-purpose 要真刀真枪改代码。

系统提示很短，两段话完事：

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.

意思是把活干完，别画蛇添足，但也别半途而废。

General-purpose 适合的场景是那种连贯的多步骤流程：先读代码定位问题、再改代码、再跑测试验证。比如”修复认证模块的登录 bug”这种任务。

模型字段故意留空，由getDefaultSubagentModel()在运行时决定，是跟着会话配置走的。

Claude Code Guide——产品文档专家

Claude Code 还有一个不太起眼的内置 SubAgent：claude-code-guide。当你问”Claude Code 怎么配 hooks？”、”Agent SDK 怎么用？”的时候，Claude 会派它去查官方文档。

它的工具是 Glob、Grep、Read、WebFetch、WebSearch。Haiku 模型，dontAsk 权限（不弹确认框）。干活流程是先抓code.claude.com和platform.claude.com的文档索引，再定位到具体页面拿答案。

Verification——专门来挑刺的

Verification 的系统提示第一句话就说：

Your job is not to confirm the implementation works — it's to try to break it.

它不是来验证”代码能跑”的，它是来找茬的。

当主 Agent 完成一项实现任务后，Verification 被自动调用。它会跑构建、测试、lint，然后根据变更类型（前端、后端、CLI、数据库迁移等各有各的检查套路）做针对性验证，还要跑边界值测试和对抗性探测。

输出格式要求严格：每条检查必须附带实际执行的命令和输出，不能只说”看起来没问题”。最后给出 VERDICT：PASS、FAIL 或 PARTIAL。默认后台运行，模型继承主 Agent。

这五个内置 SubAgent 各管一摊：搜索、规划、执行、查文档、找茬。共同点是它们都把高噪声的工作留在子进程里，不让垃圾信息堆到主对话中。

4. 什么时候该用，什么时候不该用

其实判断标准很简单：主对话需不需要承载过程本身？

适合用 SubAgent 的场景

1. 有高噪声输出的任务——主对话只关心结论，不关心过程。比如搜索 30 个文件找一个 API 定义。
2. 角色边界非常明确的任务——天然需要和其他任务隔离开。比如代码审查只看不改。
3. 可以并行执行的研究型任务——比如同时调研三个模块的实现方式。
4. 可以拆成清晰阶段的流水线式任务——比如先调研，再规划，再实现。

不适合用 SubAgent 的场景

重要提醒：子代理不能再嵌套调用子代理。所有编排都必须由主对话完成，流水线的调度中心只有一个。

实践篇

5. 三步创建自定义 SubAgent

方式一：交互式（推荐新手）

在 Claude Code 中输入/agents，按照向导操作即可。

方式二：手写配置文件（推荐进阶）

直接创建.claude/agents/your-agent.md文件。优势是更精细的控制、方便版本管理、可以从其他项目复制。

方式三：CLI 参数临时创建（适合 CI/CD）

通过--agents参数在启动时传入 JSON 格式的子代理定义。仅在当前会话中存在，不会保存到磁盘。

claude --agents '[{"name":"lint-checker","tools":["Bash","Read"]}]'

这种方式特别适合 CI/CD 自动化：在流水线中临时创建任务专用的子代理。

6. 配置文件完全指南

一个完整的子代理配置文件长这样：

--- name: code-reviewer description: Review code for security issues and best practices. Use after code changes. tools: - Read - Grep - Glob permissionMode: plan model: sonnet skills: - chain-knowledge - recent-incidents hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/validate-readonly-query.sh" --- 你是一个代码审查专家。 当被调用时： 1. 首先理解代码变更的范围 2. 检查安全问题 3. 检查代码规范 4. 提供改进建议 输出格式： ## 审查结果 - 安全问题：[列表] - 规范问题：[列表] - 建议：[列表]