企业官网建设流程全解析

早两年做项目，我最怕听到的一句话就是"上下文太长了，我有点忘了前面的逻辑"。Claude Code 用久了你会发现，一个会话里塞太多任务后，模型确实会变得迟钝——不是它能力不行，而是"一个人"同时兼顾全局和细节，本来就容易顾此失彼。这篇想聊的 Subagent 全流程实操，就是我在这个背景下摸索出的解法：不把所有事都压在主线程里，而是按需拆出一个个专职子代理，各自干各自的活，最后回传结果。它不是什么黑魔法，就是一套职责划分和工作流设计，但用好了，单会话能处理的复杂度和最终交付质量都会有肉眼可见的提升。这篇文章适合已经开始用 Claude Code 做实际项目、又觉得"单线程做大事越来越吃力"的人，我会从创建配置、调度协作到问题排查，把整套方法完整走一遍。

我会用到大量真实项目里反复验证过的写法，也会指出文档里没写得那么细、但实际踩过才会发现的坑。如果你还只是把 Claude Code 当对话式编程助手用，那看完这篇之后，你对它的定位大概率会从"写代码的聊天框"升级成"一个能自己拆活分派的小团队"。

1. 为什么你早晚会从单线程转向 Subagent

1.1 单会话模式下的隐性瓶颈

Claude Code 默认的工作方式，是主线程里的那个 agent 维护一个连续的上下文窗口。你让它读文件、改代码、跑测试，它就在同一块"工作记忆"里不断追加信息。这个模型在任务量小的时候很舒服，你不需要额外学习任何概念，打开就能干。

但任务变重之后，有两个问题会越来越明显。

第一，上下文会被无关信息填满。改一个模块时，你可能顺手浏览了五个相关文件，这些文件内容全进了上下文。等真正要写代码的时候，有效信息反而被稀释了，模型需要从一堆杂讯里"回忆"关键点，输出质量自然下滑。

第二，串行等待太浪费。主线程在干 A 任务时，B 任务只能排队。哪怕 B 只是查一个 API 的用法、整理一份错误日志，也得等当前这轮对话结束。这就像你只有一个员工，所有需求都堆在他桌上，他再快也有峰值上限。

这两个瓶颈叠加，会让中大型项目做到后半程时明显变慢，甚至出现"改一行代码，连带弄坏另一处逻辑"这种经典问题。

1.2 Subagent 解决的是哪一类问题

Subagent 的思路是：主线程仍然是总指挥，但它可以在需要的时候，把某个子任务委派给一个专门的子代理。这个子代理拥有自己的上下文窗口，任务执行期间，它在独立环境里工作，只把最终结论或产物返回给主线程。

这意味着三件事发生了质变。

上下文开始"显式隔离"。子代理看到的只是它的任务描述和它自己读取的材料，不会把无关历史带进来，也不会把它的中间过程全部污染回主会话。主线程的上下文里，最后只多了一条任务结果，而不是一整段嘈杂的工作记录。

并行变成可能。你可以同时派多个子代理去处理不同的独立任务。它们之间不共享状态，也就没有相互等待的问题。主线程可以继续干自己的活，或者等它们全部结束后统一汇总。

职责可以专业化。每个子代理都有自己明确的人设和工具集。比方说，让一个专门做代码审查的子代理在每次提交前把所有改动过一遍，让另一个专门整理技术文档的子代理单独负责 README 输出——它们每次执行都有清晰边界，不会像主线程那样"又要写代码、又要写文档、又要跑测试"。

从"一个能力全面的通用助手"变成"一组各司其职的专用角色"，这是我在实际使用中最核心的心智转变。

1.3 什么样的人建议马上用起来

如果你满足下面任意一条，Subagent 对你的收益会非常大：

• 正在用 Claude Code 做存量代码库的维护或重构，经常需要同时兼顾多个模块。
• 写代码时经常觉得"对话越往后越笨"，常见操作没问题，复杂牵扯容易出错。
• 有固定的重复性工作，比如每次提交前的代码检查、接口变更后的文档同步、错误日志的归类分析。
• 希望团队内多人共用一套统一的自动化工作流，让大家在相同场景下拿到一致的结果。

如果你只是写一些一次性脚本、几十行代码的小工具，单线程完全够用，没必要为了用而用。Subagent 的收益和任务复杂度、上下文压力成正比，项目越复杂，收益越明显。

2. Subagent 的创建与配置，一份可以直接抄的模板

2.1 产物形态与存放路径

在 Claude Code 里，一个 Subagent 本质上是一个带固定结构的 Markdown 文件，放在项目的.claude/agents/目录下。文件本身不是代码，而是一份"岗位说明书"，里面写清楚了：这个子代理是干嘛的、能用什么工具、有哪些行为约束、输出长什么样。

这种设计有几个好处。一个是配置可以纳入版本管理，团队里任何人拉下来都是一致的；另一个是调整成本极低，想改人设改描述，直接编辑 Markdown 文本就行，不需要重新编译加载。我一开始觉得"就一个 md 文件能有多大魔力"，实际用下来才发现，文件越简单越好维护，反而比写一堆脚本实现 agent 更实用。

目录结构参考：

my-project/ ├── .claude/ │ └── agents/ │ ├── code-reviewer.md │ ├── doc-writer.md │ └── bug-hunter.md └── src/

2.2 一个标准 Subagent 配置文件的字段拆解

先给一个完整的模板，后面逐段解释。

--- name: code-reviewer description: 负责对代码改动进行系统性审查，发现潜在缺陷、安全隐患与代码规范问题。适合在开发完成一轮改动后调用。 tools: Read, Grep, Glob, MultiTool model: sonnet --- 你是资深代码审查者，专注发现逻辑漏洞、边界条件遗漏和安全隐患。 # 行为准则 - 先阅读改动相关文件，再结合调用上下文判断改动影响。 - 重点检查：空指针、数组越界、并发问题、资源未释放、错误处理缺失。 - 不要给出修复合集，只输出问题列表和严重程度评级。 # 输出格式 按以下格式输出： ## 问题清单 - [严重级别] 文件路径:行号 — 问题描述 ## 审查结论 一句话结论：是否建议合并 / 需要修复后再合并。

逐个字段说明。

name是这个 Subagent 的唯一标识。调用时直接用这个名字，所以尽量简短且语义清晰。我习惯用连字符命名，比如code-reviewer、api-doc-updater，避免空格和特殊字符，免得在调用语法里出问题。

description是最影响调用效果的字段。它的作用不是给人看，而是给主线程看的——主线程会读所有子代理的 description，结合当前任务判断"该派哪个子代理去干"。所以这不是散文写作，要按"任务描述 + 适合场景"的格式把它写成搜索词。比如：

• 好的描述："负责代码审查，发现逻辑缺陷与安全问题。适合在改动后调用。"
• 差的描述："这是一个非常厉害的审查专家，拥有多年经验……"

后一种描述在主线程做任务匹配时基本不产生任何作用力。

tools字段控制这个子代理的工具权限。Claude Code 的工具面板有个范围，不是每个子代理都应该拿到全部工具。原则是最小权限：只给任务必要的工具。审查类给读工具就够了，文档生成类可能需要 Write，但通常不需要给你执行外部命令的权限。

model是可选字段，指定这个子代理底层跑哪个模型变体。复杂推理任务用更强的配置，简单跑腿任务用轻量配置，这样成本和响应速度都能控制。作为通用经验，审查、架构设计这类任务我会安排更强模型，日志整理、格式转换这类事务性杂活用轻量模型。

2.3 系统提示词描述得越细，越不需要"调教"

写 Subagent 的系统提示词时，我踩过最明显的坑是：把提示词写得像"角色扮演"。什么"你是一个热情细致的工程师"，这类描述对实际行为几乎零影响。

真正起作用的是这三类内容：

• 具体行为约束：先读什么、后做什么、不做什么。
• 输出格式要求：结果是列表、表格还是固定段落。
• 质量标准：什么情况算通过，什么情况必须打回。

举个例子，与其写"请认真检查代码"，不如写"当发现 repaint 循环调用时标记为高优问题"。前者的"认真"无法被模型量化，后者的"repaint 循环调用"则是一个可被执行的判断标准。

所以我后来写配置，基本不写形容词和态度描述，只写动词和条件。这个原则在审查、测试、文档生成三类任务上都适用。行为描述越具体，子代理的输出越稳定，主线程收到的结果也就越省心。

2.4 权限与加载机制的一些经验

Subagent 不能自己去调用其他 Subagent，这一点设计上和"子代理针对特定任务做单轮深度工作"的定位相符。如果你确实需要"一个子代理再把任务拆分给另一些子代理"，那就得回到主线程做编排：主线程发任务，收集结果，再决定下一步派谁。我在实践中的做法是，把多层分工写成主线程里的一组待办清单，而不是让子代理内部继续递归。

另外，每次调用 Subagent 都是一次独立的上下文构建。同一个子代理多次调用，每次都是冷启动，不会记住上一次的对话。这既是限制也是优点：它保证了每次执行的任务边界干净，不会被历史污染。反过来，如果任务本身强依赖前序上下文，就应该保留在主线程里做，而不是硬塞给子代理。

提示：创建完新的 Subagent 后，如果你在当前会话里无法立刻感知到它，通常需要重新启动会话或重载配置目录。多数版本里，配置是在会话启动时加载的，新增文件后重启一下最稳妥。

3. 实操：三条主线场景的完整流程

3.1 让审查子代理把守合并前的最后一道关

我在项目里最常用的场景，是提交合并前的代码审查。以前是自己肉眼滚一遍改动，后来所有改动都过一遍code-reviewer，效率和覆盖率都有明显提升。

实际操作的流程大概是这样的：

1. 在主线程里先描述任务：改动涉及哪个模块、哪个分支、大概改了什么。
2. 派发子代理：

task: 请审查当前工作区中 src/order 模块的最近改动，重点排查并发下单场景中的竞态条件，以及订单状态流转是否有遗漏分支。调用 code-reviewer 执行审查。

3. 子代理执行期间，主线程可以继续做别的——比如准备下一个迭代的代码骨架。这不是必须的，但对复杂项目来说，并行处理能省下肉眼可见的时间。
4. 子代理返回结果后，主线程读取问题清单，我可以逐条确认哪些需要改，哪些是有意为之的已知行为。

审查结果的格式因为是按配置里约定好的模板输出的，我不用再从大段对话里找结论。这算是一个隐性收益：稳定格式让"人和工具之间的交互成本"降到了最低。

这类子代理适合接在现有流程后面。改完代码立刻让它跑一轮，既不会打断创作节奏，又能把机械性的检查工作自动化。

3.2 让文档子代理在功能完成后自动补齐说明文档

我承认，写文档是我最不愿意做的工作之一。但 Subagent 让这件事的痛苦程度下降了一个量级。

我的做法是维护一个doc-writer子代理，专门负责从代码和提交说明中提取信息，生成或更新 Markdown 文档。配置里明确约束它"只读代码、只输出文档、不修改代码"。

调用方式类似：

task: 查看 src/gateway/ 下新增的速率限制实现，为 docs/api.md 补充该功能的接口说明。调 doc-writer 完成。

它会自己读取相关文件、理解接口行为，然后按我定义的模板返回一段可以直接粘贴的文档内容。我不需要花时间回忆刚才写代码时那些细节，也不需要在换上下文之后重新描述一遍需求。

用久了以后，我发现文档子代理最好的工作模式是"频繁、小步、即时"。每完成一个功能点就同步更新文档，而不是攒到发版前一次性补。原因很简单：保留在主线程里的上下文越完整，子代理读代码时理解得越准；拖得越久，它需要自己摸索的上下文就越多，出错概率自然变大。

3.3 用并行子代理同时处理多模块的重复劳动

比单次调用更有价值的，是让多个 Subagent 并行跑不同的任务。我的实际场景是这样的：

有一次要给三个独立的微服务模块补充单元测试，每个模块的工具类、边界条件都不一样。我的做法是同时派三个测试编写子代理，每个负责一个模块。子代理之间互不干扰，各自读取各自的模块代码、各自生成对应的测试文件。等它们全部完成后，我统一合并，再跑一轮 CI。整体耗时大约是从前串行做法的三分之一。

并行调用需要注意一点：既然子代理之间没有共享状态，它们各自的输出有可能产生冲突，比如都写了同一个文件、或者生成的两份文档中引用关系不一致。所以并行任务最好保证它们操作的文件范围是互斥的。如果任务之间有依赖关系，则不应该并行，老老实实排队等结果。

还有一点，并行派发时主线程不要什么事情都不干。它最优的使用方式是在等结果的同时，处理那些必须由它自己承担的、依赖全局上下文的决策性工作。这样整个流程才真正在"并行"。

4. 把 Subagent 做稳的进阶配置与扩展技巧

4.1 和主线程的边界：哪些任务不要丢给 Subagent

实践时间长了，我总结出一个边界感清单：有些活适合 Subagent，有些活留在主线程反而更稳。

适合交给子代理的：

• 范围明确的独立任务，比如"审查 A 模块代码""总结 B 接口的变更点"。
• 需要大量读文件但不需要全局改动的任务，比如"找到所有未捕获异常的位置"。
• 重复执行且希望格式统一的产出型任务，比如日志归类、错误分析、文档更新。

不适合交给子代理的：

• 强依赖当前对话上下文的续写任务，比如"接着刚才的重构思路继续改代码"。子代理没有刚才的记忆。
• 需要跨多个文件保持一致的大规模重构。这类任务由主线程统一协调更可靠。
• 需要反复和用户确认需求的工作。子代理返回结果后就不能再追问，交互只发生在主线程和用户之间。

记住这个边界以后，失误率明显下降。很多时候不是 Subagent 不好用，而是人把它用错了位置。

4.2 系统提示词里值得加入的"反套路"条款

除了正向的行为描述，我还会在配置里加一些限制性条款，用来约束模型默认的一些"坏习惯"。

比如审查任务里加一条："不要输出鼓励性评价，不要以'整体来说'开头。"这能省掉大量无关套话，让输出直接进入问题列表。

比如文档任务里加一条："不要解释代码为什么存在，只描述外部可观察行为。"这能避免模型自己脑补出并不存在的设计意图，把文档写成一堆猜测。

再比如错误排查任务里加一条："如果你无法根据现有信息定位原因，直接输出'信息不足'+ 缺失信息清单，不要猜测。"这条非常有效，因为模型在被要求给结论的时候，倾向于把任何空白都脑补一个合理解释填上。限制住这个默认行为后，子代理产出的结论质量会大幅提高。

这些反向条款看着不起眼，但实际对输出质量的提升比加一堆"要认真""要负责"大得多。

4.3 使用项目级配置固化团队工作流

如果团队里多个人使用同一代码库，每个人在本地创建的子代理是相互隔离的，不会自动同步。要统一工作流，应该把.claude/目录纳入 Git 管理，让所有成员的子代理配置保持一致。

我在团队里就这么干过：把审查、文档、错误分类三个 Subagent 配置提交到仓库根目录下，新人拉完代码之后，不需要任何额外安装步骤，就拥有了一套和团队一致的自动化工具链。这个收益隐性的，但长期价值极高——相当于团队约定了一套"对机器的接口"。

有一点提醒一下：把.claude目录提交进仓库前，要检查里面有没有包含个人本地路径、私密命令之类的内容。配置文件虽小，它也会被所有协作者读到，该做敏感信息隔离的时候不能偷懒。

4.4 保存会话状态，多种模板配合多类任务

做得更细一点的话，可以为不同类型的工作分别准备子代理模板，而不是"一个子代理试图覆盖所有审查场景"。我自己的现状是需要几个固定角色：

• 一个面向提交合并的代码审查者，只关心质量和安全。
• 一个面向接口文档的编写者，只读代码，输出文档。
• 一个面向日志现场的错误定位者，专门研究报错堆栈和日志上下文。
• 一个面向依赖梳理的架构分析者，用于绘制模块关系、排查循环依赖。

每个角色的系统提示词都不长，但都非常专一。专一带来的效果是，主线程在派发任务时几乎不用费心"讲解背景知识"，子代理一上来就知道自己该干什么。这也让整套工作流变得非常接近"真正的团队分工"——每个角色各管一段，互不越界。

5. 常见问题与排查技巧实录

5.1 子代理没有按预期工作？先查这三处

我遇到过最多次的问题，是子代理"好像没生效"。表现各不相同：有的返回结果像普通对话，有的完全不按输出模板走。排查顺序我固定为以下三步。

第一步是确认文件名和name字段是否匹配。调用语法依赖 name 字段做标识，如果配置里写的是code-reivewer这种拼写错误，主线程根本找不到对应角色，只能退回普通对话模式。

第二步是检查 description 是否写得太抽象。如果描述只有"负责代码相关任务"这种范围，主线程做任务匹配时可能选不中它，或者选中的是另一个描述更具体的角色。让 description 直接对应明确任务场景，能大幅减少"派错人"的情况。

第三步是查看子代理返回结果是否被截断或格式异常。如果输出超长，部分模型会自动截断。解决办法是精简输出模板，把"必须输出的核心信息"收拢到几行以内，其余内容可放可不放。

5.2 上下文爆炸：子代理结果的引用问题

子代理返回的结果会放回主线程上下文。如果设计不当，这一步是新的上下文污染来源。比如我早期让文档子代理输出整篇完整的 README，每次更新完都返回少则几千字的内容，几轮下来主线程又被塞满了。

现在的做法是：在配置里要求子代理"只输出变更段落，不要输出全文"，或者"输出变更摘要 + 文件路径"。这样主线程拿到的是一份轻量、可操作的结果，而不是一大堆需要二次筛选的原始文本。

遇到确实需要完整产物的场景，我会让子代理直接写入文件，再在主线程里去读那个文件的局部内容。这比把全文塞回对话里再让主线程复述一遍科学得多。

5.3 特定任务频繁失败时的退出策略

偶尔会遇到某个子代理在特定任务上反复失败的情况。调整一次两次系统提示词没效果的话，就别继续死磕了。合理的做法是把任务拆成更小的子步骤，或者干脆回到主线程手动处理这个case。

我之前处理过一个怪异问题：让 bug 排查子代理分析一套超长日志，总是漏掉某个非典型的报错分支。后来我把日志按时间切分成两段，先后派它分析，最终定位到了问题。这个经验说明，任务粒度不合适的时候，子代理的独立上下文反而是一个劣势——它看不到完整全景。此时"缩小任务颗粒度"比"增加提示词篇幅"有效得多。

5.4 一次快速的运营成本对比

做过几次之后，我认真对比过"用不用子代理"的时间账。

以一次典型的改动为例：修改一个接口 + 更新文档 + 审查改动 + 排查一个关联问题。

单线程做法是：改接口 → 写文档 → 审查 → 查问题，串行做，中途切换任务时上下文会明显混乱。全部完成大约需要一小时。

使用子代理做法是：主线程改接口的同时，派文档子代理去读代码并输出文档初稿，派排查子代理去分析早已收集好的日志，最后主线程改完接口后调审查子代理做一轮检查。四件事里有三件在并行。

总耗时会降到三四十分钟，同时主线程的上下文因为不承载文档初稿和日志分析过程，整体清晰度更高，后续改动也不容易丢信息。对我这种经常要在多个上下文之间切换的人来说，这个收益是实打实的。

6. 关于 Subagent，我的几条实操心得

6.1 从一个小场景开始，不要一次性铺开

Subagent 最大的上手陷阱是想一步到位：第一天就建八个子代理，指望它们全部立刻产生价值。我自己的经验是，先挑一个最痛的重复性场景切入。可以是每次提交前的审查，也可以是持续更新的文档。

等这个场景跑顺了，你会自然知道下一步该往哪扩展。同时，每多一个子代理，你就多一份维护成本——它们的描述要随业务演进保持更新，工具权限要适时调整。它不是"加上就一劳永逸"的东西，更像持续维护的团队岗位。

6.2 系统提示词定期回顾，像维护代码一样维护它

我在项目里有个习惯：每两到三周会快速过一遍所有子代理的配置。重点看两个问题：有没有描述和当前业务已经脱节？有没有输出模板在实际使用时被频繁改写？

如果发现某个子代理的输出经常需要我在主线程里改了才能用，那就是信号——说明它的提示词或者模板需要调整。戳中这个信号时不要拖，不然它会在之后的所有任务里持续产出需要人工返工的结果。

6.3 一条可复用的通用检查清单

最后，把我每次新建 Subagent 时的一份轻量检查项分享出来，算是个清单惯例：

• name 是否简短、唯一、无空格。
• description 是否按"任务 + 场景"格式写明，避免形容词堆砌。
• tools 是否做到最小权限授权。
• 系统提示词里是否有具体动词和可执行条件，而不是空泛的态度要求。
• 输出模板是否限定了长度和格式，防止上下文被结果污染。
• 文件是否已落入.claude/agents/目录并纳入版本管理。
• 如果多人协作，是否确认团队里其他人拉取后也能识别同一个配置。

这套检查项不花什么时间，但它基本能保证每个新子代理在第一次被调用时就达到可用状态，而不是上线后再来回调。我自己在后面加新角色时一直沿用这套流程，目前没有再踩过前面那些低级的坑。用它替换掉"写一堆配置然后看运气"的做法，大概率也能让你的 Subagent 真正稳定地替你干活。