企业官网建设流程全解析

最近我在自己的项目里试了一回真正意义上的“并行任务自动化”，把以前要串行跑很久的几个重构和测试任务同时丢给 Cloude Code 的 Agents 去处理，整个过程比我想象中更可控，效率也高得明显。这里面的关键不在于把多个 prompt 堆在一起，而是理解 Claude Code 的 Agent 模型、隔离机制和上下文边界。这篇就完整记录下我是怎么设计、编排、排错和优化这一套多代理协作流程的，希望能帮到准备拿 Claude Code 做批量任务、项目接管和自动化重构的人。

1. 单代理的瓶颈：为什么并行自动化成了刚需

先把背景说清楚。Claude Code 是一个运行在终端里的 AI 编程助手，和传统 IDE 插件最大的区别是它自己会读文件、跑命令、改代码、查日志，整个工作流是代理式的。也就是说，你给的不是一句“帮我写个函数”，而是一个可以连续操作仓库的任务描述，它自己规划、执行、验证。

1.1 串行执行在真实项目中的三个痛点

单个 Agent 在简单任务上表现确实好，但一旦任务量变大，三个问题会非常明显：

第一，上下文窗口被历史对话快速消耗。一个代理在一个会话里既要做需求理解，又要读核心代码，还要改十几个文件，最后还要跑测试。等你把前几步做完，上下文里已经堆满了中间产物，真正重要的结果反而没有空间。Claude 的模型再强，窗口也是有限的，到后期经常出现“我让它改 A 文件，它却盯着 B 文件的老代码分析半天”这种失焦现象。

第二，任务切换带来注意力漂移。假设现在有个仓库，要同时完成三件事：修复一个接口的分页逻辑、给两个工具函数补单元测试、把项目里废弃的 console.log 全部清理掉。单代理的做法是“先做第一件，再做第二件，再做第三件”。但代理在切换任务时，需要把上一段的推理过程在脑内“缓存清理”再加载新任务，这中间很容易残留上一任务的判断，导致改错文件或者用了不匹配的代码风格。

第三，长链路步骤失败回滚代价太大。串行执行意味着后面的所有步骤都依赖前面的结果。如果第一步改了数据层，第二步迁移业务代码时发现方案不对，你需要先回滚第一步，再重新设计。Claude Code 虽然支持 git 操作，但反复回滚不但浪费时间，还会污染提交历史。

1.2 多代理协作的适用边界

并不是所有场景都适合上多代理。我自己的判断标准是三条：任务之间是否有文件级隔离，任务之间是否存在强数据依赖，每个子任务是否能有独立的验收标准。如果一个任务需要不断参考另一个任务的中间输出，那并行就是灾难，不如老老实实串行。

典型的适合场景包括：

• 大仓库里按模块拆分重构，每个模块独立处理。
• 批量修改不同目录下格式类似的代码，比如统一日志规范、替换废弃 API。
• 测试补全，给互不依赖的几个模块分别写测试。
• 多语言项目里，前后端代码同步调整，两边可以并行跑。

而我这次做的项目正好是一个典型的中型前端仓库，三个模块互不引用，可以安全地拆开处理。

2. 环境准备：先把 Claude Code 跑起来再说

多代理协作对工具链的要求其实不高，但有些前置配置确实会影响后面的稳定性。先把基础环境补齐，后面踩坑会少很多。

2.1 安装与登录的完整路径

Claude Code 的安装方式主要是 npm 全局安装，命令很简单：

npm install -g @anthropic-ai/claude-code

安装完成后在终端执行claude进入交互界面，首次使用会引导你完成登录。官方推荐的方式是通过 Claude 账号登录，也可以用 API key 方式。登录状态可以通过/status查看，如果出现 “not logged in” 的提示，就直接执行/login重新走一遍认证流程。

Windows 环境下需要注意一点：Claude Code 对 PowerShell 和 Windows Terminal 的支持比较成熟，但如果你用的是老的 cmd 窗口，一些交互式渲染可能异常。建议直接用 Windows Terminal，配置好后体验好很多。

2.2 VSCode、桌面版与命令行：三种运行形态怎么选

现在 Claude Code 有三类使用方式：纯命令行、VSCode 插件、桌面版。很多人问这三者到底有什么区别，我的建议是：

• 纯命令行是做多代理并行自动化的主战场。因为它能配合 shell 脚本、Makefile、CI 系统，可以同时启动多个独立进程，这才是真正意义上的并行。
• VSCode 插件适合在编辑器里做局部代码修改，它的内联 diff 和文件跳转做得很顺，适合人工 review 代理的改动。但它本身还是单会话模型，不适合批量并行。
• 桌面版适合不熟悉命令行的使用者，交互更图形化，但在自动化编排上能力有限，不太建议拿到并行任务里用。

我的最终方案是：命令行做并行执行，VSCode 插件做结果 review，两个工具各管一段。

2.3 模型切换与第三方模型接入思路

Claude Code 官方闭源，默认强绑定 Claude 系列模型。在交互会话里用/model可以随时切换模型，比如把简单任务切到 Haiku 省钱，把复杂重构切到 Opus 求稳。做多代理编排时，这一点很重要，因为我可以在不同子任务里用不同级别的模型，这个后面细讲。

至于社区里讨论的接入第三方模型，比如 DeepSeek，那属于非官方适配方案，需要额外的兼容层配置，稳定性取决于社区维护进度。如果你不是有特殊需求，建议还是用官方模型链，省去不必要的排错成本。

3. Agents 机制拆解：Task 工具、Subagent 与权限模型

Claude Code 的并行能力并不像“开十个终端窗口”这么简单，它的核心是 Agent 内部的子代理机制。理解这套机制，你才知道怎么编排任务才能不打架、不串场、不污染上下文。

3.1 主代理与子代理的分工逻辑

Claude Code 在同一会话里有一个主代理负责和你对话、理解需求、汇报结果。当任务复杂度上升，它可以调用多个子代理（Subagent），每个子代理在独立的上下文中运行自己的任务，完成后把结果返回给主代理。

这就是整个多代理协作的基础。子代理的优点有三个：

一是上下文隔离。每个子代理只加载自己需要的那部分文件，不会被其他任务的文件内容干扰。这就解决了我前面说的“上下文被历史对话消耗”的问题。

二是职责聚焦。子代理的任务描述里写得很清楚：你只需要做这件事，遇到其他问题不要管，直接报告。这种强约束让代理在一个小范围内发挥，比让一个全能代理什么都管更可靠。

三是可组合性。主代理可以把一个复杂任务拆成多个子任务，按依赖关系逐个分发。虽然在一个会话内，主代理调用子代理本身是顺序执行的，但你可以通过多进程方式把它们变成真正并行，这个后面会细讲。

3.2 通过 Markdown 文件定义自定义 Subagent

Claude Code 允许你自定义子代理，这是并行编排的关键能力。自定义子代理放在项目的.claude/agents/目录下，每个子代理是一个 Markdown 文件，头部是 YAML 格式的配置，正文是系统提示词。

举个例子，我定义了一个专门负责“代码审查”的子代理：

--- name: code-reviewer description: 负责审查指定目录的代码质量，输出问题清单和改进建议 tools: Read, Grep, Glob, LS model: sonnet permission-mode: default --- 你是一个严格的代码审查者。 你的任务： 1. 读取指定路径下的所有源码文件 2. 检查命名规范、重复代码、潜在 bug 和糟糕的抽象 3. 只输出问题清单，不修改任何代码 输出格式： 问题ID | 文件路径 | 行号 | 严重程度 | 问题描述 | 修复建议

这里有几个字段要注意。name是子代理的名字，description是给主代理看的“何时该用我”的说明，tools决定子代理能用的工具白名单，model决定子代理用哪个模型跑，permission-mode决定文件修改权限。如果你不想让某个子代理改任何文件，就不要给它Edit工具，同时在权限模式里选default，这样安全边界很清晰。

3.3 三种权限模式的取舍

Claude Code 的权限模式直接决定了 Agent 能不能直接改文件、执行命令。它主要有三个档位：

• default：每次修改前要你确认，命令执行也要你批准。最安全，适合任务边界模糊的情况。
• acceptEdits：文件修改自动接受，但命令执行仍要确认。适合改动明确的批量重构。
• plan：只读模式，Agent 只给你方案，不改任何文件。适合前期调研和方案设计。

在并行编排里，我强烈建议不同的子代理用不同的权限模式。调研型任务用plan，改动明确的用acceptEdits，涉及环境变量操作或者危险命令的任务强制default。这样并行跑起来后，时间不会浪费在无意义的确认弹窗上，同时风险区域又没有失控。

4. 并行任务编排实战：拆分、调度与合流

到这一节才真正进入执行阶段。我会按实操顺序一步步说明，这次项目里我是怎么从仓库状态开始，到最终合流收尾的。

4.1 建立隔离环境：分支、目录与上下文边界

并行任务第一原则是：不要让多个任务在同一个工作目录下同时改文件。这不是能力问题，而是并发控制问题。两个 Agent 同时编辑同一个文件时，后写的人会覆盖先写的人的成果，而且你还很难察觉。

我用的方案是git worktree，一个仓库分出三个工作目录，每个并行任务在一个独立目录下操作：

git worktree add ../repo-module-a -b feat/module-a git worktree add ../repo-module-b -b feat/module-b git worktree add ../repo-module-c -b feat/module-c

这样每个任务都有完整的仓库副本，但相互之间完全隔离。跑完后每个分支独立提交，最后由我在主分支上做合并。这个方式比复制目录好，因为它保持了同一个 git 仓库的关联，后续合并非常顺。

如果你的任务之间确实需要共享某些文件，那就不适合直接并行，建议先用串行方式把共享文件改完，再并行处理各自模块。

4.2 在一个会话里并发调用多个 Subagent

任务隔离好后，就可以进入 Claude Code 交互会话，让主代理编排子代理了。虽然单会话内的子代理调用是顺序的，但这种编排方式依然很有价值——它适合子任务之间有弱依赖关系的场景，比如必须先统计模块 A 的 API 列表，再让第三个子代理根据这些 API 写测试。

我在项目里给主代理的 prompt 大致如下：

我需要处理这个仓库的三个模块，分别是： 1. src/modules/auth：修复分页逻辑，补充边界条件处理 2. src/modules/billing：清理废弃函数，补两个工具函数的单元测试 3. src/modules/profile：统一错误处理方式 请先调用 code-reviewer 子代理快速审查这三个模块的现状，然后分别创建三个任务，按依赖关系依次处理。 每个任务完成后，汇报改动的文件清单和测试结果。

主代理收到这个指令后，会通过 Task 机制创建子代理任务。每个子代理只负责单一模块，读取的文件范围被限定在各自模块内，所有修改在独立上下文里完成后再汇总回来。这种做法的好处是每个子代理的结果都足够聚焦，主代理拿到的是三个清晰的结果快照，而不是一大堆混杂的中间过程。

4.3 多进程并行：真正让任务同时跑起来

会话内编排解决的是“上下文隔离+任务聚焦”，但如果三个模块完全独立、互不依赖，一个 Session 里顺序跑还是慢。真正想“同时跑”，就要用多进程并行，也就是同时启动多个 Claude Code 进程，每个进程负责一个任务。

我写的并发脚本核心逻辑大概是这样的：

#!/bin/bash run_task() { local dir="$1" local task_file="$2" cd "$dir" || exit 1 claude -p "$(cat $task_file)" --output-format json > result_$(basename $dir).json 2>&1 } # 每个 worktree 目录分配一个任务 run_task "../repo-module-a" "task_a.md" & run_task "../repo-module-b" "task_b.md" & run_task "../repo-module-c" "task_c.md" & # 等待所有后台进程结束 wait echo "所有并行任务执行完毕"

这里用claude -p（print 模式）执行非交互式任务，每个任务对应一个独立的 prompt 文件。--output-format json可以拿到结构化输出，方便后续解析。后台运行加wait保证所有任务完成后脚本才继续。

实际跑的时候有个参数要注意：并发数不是越大越好。我试过同时跑 5 个以上任务，发现一是 API 限流概率明显上升，二是每个 agent 的上下文和计算资源会有争抢，导致单个任务变慢。我的经验是 3 个并行比较稳，如果你的任务简单，可以到 4 个。

4.4 结果合流与冲突处理的实操方案

并行任务跑完，合流阶段同样关键。因为每个 worktree 有自己的分支，所以合流就是常规的 git 操作：

# 回到主分支 git checkout main # 把三个 feature 分支按顺序合并 git merge feat/module-a feat/module-b feat/module-c -m "合并并行开发的三个模块"

这里最容易出情况的是：两个任务都修改了同一个公共文件，比如package.json或者某个公共常量文件。Git 可能会自动合并，也可能产生冲突。我处理冲突的思路是：先看冲突文件，人工判断两边改动的逻辑，如果都是往同一份数组里加内容，手动合并两段代码；如果改动逻辑有重叠，就重新跑一个子代理专门解决冲突。

所以我在并行时还有个习惯：给每个任务文件里都加一句“如果某个文件非改不可，请确保语义与其他模块兼容”，这能在源头上减少冲突概率。

5. 项目记忆与 Skills：让多代理团队保持一致的底层配置

多代理并行跑起来之后，你会发现一个很容易出现的问题：不同代理对项目规范的理解不一致。比如一个代理用单引号，另一个用双引号；一个代理按现有命名习惯写，另一个自由发挥。这个问题的根源不是模型不行，而是代理入职前没有统一的“公司制度”。Claude Code 里的CLAUDE.md和Skills就是解决这个问题的。

5.1 CLAUDE.md 的作用边界

CLAUDE.md是放在项目根目录或者子目录里的 Markdown 文件，Claude Code 每次启动时会自动读取它，作为项目的“入职手册”。我的CLAUDE.md一般包含这些内容：

• 项目简介和技术栈。
• 代码风格要求：缩进、引号、命名规范、组件组织方式。
• 常用命令：如何跑测试、如何构建、如何启动开发服务器。
• 目录结构说明：哪些目录是业务代码，哪些是公共工具，哪些是禁止修改的生成代码。

这样每个并行任务里的代理看到的都是同一份项目规范，产出的代码风格就会统一很多。注意，CLAUDE.md不要写太长，太长了代理反而抓不住重点，控制在 50 行以内，只写最关键的信息。

5.2 Skills 安装与自定义

Skills 是 Claude Code 的“技能包”机制，它把某种特定任务的完整流程固化成可复用的模板。和 CLAUDE.md 不同的是，Skills 更偏向“怎么做一件事”，比如“如何给这个项目新增一个 API 接口”“如何写一个符合规范的单元测试”。

安装官方 skill 可以这样：

claude skill add <skill-id>

但更实用的是自定义团队内部的 skill。一个 skill 本质上是一个目录，里面包含一个SKILL.md作为入口说明文件，里面写清楚这个 skill 的使用场景、执行步骤和输出格式。比如我给自己项目写过一个“批量迁移日志规范”的 skill，结构类似：

.claude/skills/log-migration/ ├── SKILL.md └── examples/ └── before-after.md

SKILL.md 的大致内容：

--- name: log-migration description: 将指定的日志调用统一迁移到新版 logger 接口 --- 当用户要求迁移日志规范时，按以下步骤执行： 1. 扫描 src 目录下所有 console.log / console.warn 调用 2. 替换为 logger.info / logger.warn 3. 保持日志文案和参数结构不变 4. 修改后运行 npm run lint 确保没有引入新错误 5. 输出修改的文件清单和剩余 console 调用统计

有了这个 skill，不管哪个并行任务里遇到日志迁移，代理都会自动加载并使用同一套流程。并行任务的产出就会高度一致。

5.3 MCP 扩展的接入

MCP（Model Context Protocol）是 Claude Code 接入外部工具的标准协议。你可以通过 MCP 给代理加上数据库查询、浏览器操作、API 调试等能力，让 Agent 不只是改代码，还能验证自己改的结果。

接入方式很简单：

claude mcp add database --env DB_URL=xxx -- npx mcp-server-postgres

在并行场景里我一般不会让所有代理都接入 MCP，因为多个代理同时连数据库可能产生写冲突。我的做法是：只让负责集成验证的那个子代理接入测试库的 MCP，其他模块开发子代理只给文件读写和命令执行工具。职责边界清晰，安全风险也小。

6. 运行中的常见报错与排查链路

多代理并行和单代理不一样，出错的影响面更大。这里记录几个我在实际使用中遇到的典型问题，以及完整的排查思路，供参考。

6.1 “无法连接 Anthropic 服务”类问题的排查顺序

有次我同时跑 5 个claude -p任务，跑了十几分钟后突然有任务自己中断了，日志里出现类似 “unable to connect to anthropic services fail” 的错误。

我的排查顺序是固定的：

1. 先看是不是偶发。单任务重跑一次，如果成功，说明是并发高导致的临时连接问题，降并发数就行。
2. 再看登录态。执行claude /status确认当前账号状态正常，有时候 token 过期也会出现连接类报错。
3. 检查网络连通性。这里要先确认运行机所在网络环境能正常访问目标服务域名，这一步属于环境前置条件，不同网络环境表现差异较大，建议先用普通方式访问确认。
4. 最后看版本，执行claude update升级到最新版，有些连接问题是旧版本协议兼容性导致的。

这个顺序看起来很基础，但我发现很多人一看到 connection 类报错就慌，先去翻 API key、翻配置，结果浪费了大量时间。按这个顺序排查，大约 80% 的问题在第一步就能解决，也就是重试一次或者降并发。

6.2 沙箱启动失败与权限问题

Claude Code 在受限环境里执行命令时，可能会碰到沙箱启动失败的情况。表现形式通常是任务里涉及到 bash 工具调用时直接报错，或者在 VSCode 插件里看到类似“sandbox failed to start”的提示。

常见的几个原因：

• 当前系统用户的临时目录没有写权限。
• 杀毒软件或系统安全策略拦截了子进程创建。
• 资源限制，比如文件描述符上限太低。

排查步骤也很直接。先手动创建一个临时文件测试目录写入权限；再把命令执行的权限模式降级到default，看是否还报错；最后检查系统资源限制，ulimit -n看一下文件描述符数量是否过小。Claude Code 的沙箱设计本身比较保守，如果你的任务里确实需要执行很多命令，建议先在小范围里验证命令链路，再放到完整任务里跑。

6.3 并行任务导致的资源竞争现象

并行最隐蔽的坑是“任务本身没报错，但结果相互干扰”。有一次我开两个并行进程，一个负责改代码，一个负责跑测试，结果两边同时访问了同一个缓存目录，导致测试任务读到了未完成构建的中间产物，报了一些完全无法理解的错误。

这种问题的特征在于错误信息看起来毫无规律，甚至单进程重跑完全正常。排查思路是先检查它们是否共享了某个目录，比如 node_modules/.cache、临时目录、日志目录。解决方式要么是给每个任务指定独立的缓存目录，要么在环境变量层面做隔离，比如分别设置不同的TMPDIR。

后来我在脚本里都加上了一段环境隔离：

export TMPDIR="$PWD/.tmp_$(basename $dir)" mkdir -p "$TMPDIR"

这样一个任务一个临时目录，资源竞争问题从此基本绝迹。

7. 多代理协作的进阶优化：成本、上下文与流程固化

基础流程能稳定跑通之后，下一步就是让它更快、更省、更可控。这个阶段拼的是对上下文分配的精细程度和流程的复用能力。

7.1 上下文窗口怎么分才不浪费

如果你在同一个 Claude Code 会话里跑多个子代理，那么主代理的上下文会被“汇报结果”逐渐填满。这里有一个很重要的优化思路：让子代理的返回结果尽可能结构化、简短，而让子代理自己保留详细过程。

我在设计子代理的任务描述时，会明确指定输出格式，比如：

输出格式（严格按行输出）： - 文件路径（相对仓库根目录） - 改动内容摘要（不超过 30 字） - 新增函数列表（如果有） - 测试命令执行结果

这样主代理拿到的就是一份干净的结果清单，而不是一大段思考过程。父代理的上下文占用会大幅下降，你能在同一个会话里调度更多子任务，不需要反复清理上下文。

还有一个技巧是：把大任务拆成“调研子代理+实施子代理”两段。调研子代理只读代码，输出一份结构化的“现状分析+修改方案”，实施子代理拿着这份方案去改，这样避开了一个代理又调研又动手导致的上下文过载。

7.2 成本控制的几个有效手段

并行任务跑起来最直观的代价就是 token 消耗翻倍。我的成本控制思路主要有三条：

第一，按任务难度选模型。简单任务比如清理废弃变量、统一格式化，用 Haiku 完全可以；常规重构用 Sonnet；涉及到多文件调优和架构判断的才上 Opus。在自定义子代理文件里通过model字段指定，不同子代理用不同模型。

第二，给任务加输出长度限制。在 prompt 里写明“汇报总长度不超过 300 字”“不要输出完整代码 diff，只输出改动摘要”。这样能有效减少非必要 token，尤其适合批量任务。

第三，限制工具的探索范围。默认代理可能会用 Grep 和 Glob 去扫全仓库，非常费 token。我会在子代理的tools字段里只给必要的工具，再在 prompt 里写明“只允许查看 src/module-a 目录下的文件”。这个动作能把成本降低 30% 到 40%。

7.3 把并行流程固化成项目级规范

折腾完一轮并行自动化后，最终目标是把这套流程沉淀下来，让团队的其他人也能直接用。我做两件事：

第一，把所有并行任务的标准 prompt 模板放到.claude/agents/或者项目的prompts/目录里。这样以后新起任务，直接改关键路径和描述就能复用。

第二，写一个run-parallel.sh脚本放进项目仓库，脚本里封装了 worktree 创建、任务分发、结果合流的所有步骤。团队成员不用理解 Claude Code 的详细机制，只要按格式添加任务描述文件，再执行./run-parallel.sh就能自动跑完全部流程。

到这里，整套多代理并行自动化的框架已经完整。最后分享一个我实际操作中的体会：并行任务自动化的真正价值并不只是“同时做几件事”，而是逼着你把任务拆得足够清晰——任务边界越清楚，每个代理的表现就越稳定，合流的成本也越低。如果你打算在自己的项目里实验多代理，我建议不要一上来就跑大型重构，先拿一个模块拆分、测试补全这类低风险任务练手，跑通一次全流程后，再逐步加大任务复杂度。另外一个小技巧是：每个并行任务的 prompt 里一定要写清楚“最终输出的文件路径”，让代理把结果落盘到指定位置，而不是只写在回复里，你会省下很多收集结果的时间。