Claude Code 如何实现多个 AI Agent 并行写代码？完整工作流解析

多个 Claude Code 会话同时修改同一批文件，最终往往不是“开发速度翻倍”，而是覆盖、冲突和无法验收一起出现。

最快的解法是按任务类型选择机制：研究和独立分析使用 subagents；并行编辑代码必须使用隔离 worktree；需要多个会话协同推进时再由主会话统一调度。最可靠的 Claude Code 多 AI Agent 工作流是“任务拆分、隔离执行、自动测试、人工合并”四层。

适合阅读这篇文章的人，包括已经在终端使用 Claude Code 的开发者、需要同时处理功能、测试与文档任务的团队负责人，以及准备把多会话 Claude Code 部署到远程 Mac 的工程师。

最后更新于 2026 年 8 月 13 日，命令、配置字段与清理行为核实自 Claude Code 官方并行 Agent 文档、官方 worktree 文档 与 官方 subagents 文档。

先判断并行任务属于哪一类

Claude Code 的并行能力并不是单一开关。subagents、agent view、agent teams 和 worktree 分别解决上下文、会话调度、协作通信与文件隔离问题，混用概念是后续冲突的主要来源之一。

任务类型	更适合的机制	是否默认隔离文件	主要交付物
搜索代码库、分析日志、阅读文档	subagents	否，除非额外指定	结构化摘要、问题列表、证据
多个独立终端会话	agent view	取决于是否使用 worktree	会话状态与分支变更
需要主会话统一分派任务	agent teams	否，需自行划分文件所有权	任务列表、消息、代码或报告
多个 Agent 同时修改代码	worktree + 任一调度方式	是	独立分支上的提交

官方文档明确区分了这些能力：subagents 返回子任务摘要，agent view 用于查看后台会话，agent teams 通过共享任务列表和消息协作，而 worktree 负责隔离 Git 工作目录。官方功能对比说明 已将它们列为不同的并行路径。

因此，以下提示词适合研究任务：

请使用 3 个独立 subagents，分别分析认证、数据库和 API 模块。
每个 Agent 只返回：
1. 关键文件；
2. 已确认的调用链；
3. 风险点；
4. 不超过 10 条的建议。
不要修改任何文件。

这里的重点不是“启动越多 Agent 越好”，而是限制返回格式，避免搜索结果、日志和大段源码重新挤满主会话上下文。

先处理文件覆盖与隐藏依赖

文件覆盖

如果多个会话都在同一个目录运行，A 会话写入的内容可能立即被 B 会话看到并覆盖。即使两个 Agent 分别修改不同函数，也可能因为格式化、代码生成或自动修复操作触碰同一个文件。

并行编辑时，应优先使用：

claude --worktree feature-auth
claude --worktree test-auth

官方机制会为会话创建独立工作目录和分支；worktree 之间共享 Git 历史与远程仓库，但每个目录拥有自己的文件状态。官方 worktree 创建与清理说明 对此有明确限制。

隐藏依赖

真正难处理的不是普通源文件，而是多个任务都依赖的共享产物。派发前至少标记以下对象：

• 公共类型、接口和路由定义；
• 数据库迁移文件；
• package-lock.json、pnpm-lock.yaml 等依赖锁文件；
• OpenAPI、GraphQL 或代码生成文件；
• CI 配置和项目级设置；
• .env、.env.local 等被 Git 忽略的本地配置。

⚠️ 经验提醒： worktree 只隔离文件修改，不会自动解决接口依赖。两个 Agent 即使各自在独立分支中工作，也可能分别基于不同的接口假设完成任务。

建议为每类共享文件指定唯一负责人。例如，接口 Agent 先提交类型和 API 变更；功能 Agent 只能消费该提交，不直接重写接口；测试 Agent 可以并行设计测试，但在接口提交合并后再执行最终验收。

再安排上下文与会话调度

subagents 的适用边界

subagents 有独立的新上下文，不会自动看到主会话已经读过的所有文件，也不能假设主会话中已经讨论过的结论。因此，委派提示词必须包含目标、范围、禁止事项和输出格式。

适合交给 subagents 的任务包括：

• 统计某个模块的调用关系；
• 从构建日志中找出真正失败的测试；
• 对比两个实现的行为差异；
• 阅读外部文档后提炼迁移影响；
• 对某个 Pull Request 做只读审查。

官方文档说明，subagent 的优势在于把高输出量操作留在独立上下文中，只向主会话返回必要摘要。官方 subagents 使用场景 也建议将搜索、测试和日志处理设计成边界清晰的独立任务。

agent teams 的适用边界

如果多个 Agent 需要持续沟通、共享任务状态并互相传递结果，可以启用 agent teams。该功能目前仍属于实验能力，默认关闭，需要设置：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

启动后，应明确指定主 Agent、协作者角色和任务依赖，例如让一个 Agent 负责 API，一个负责测试，一个负责安全审查。官方说明中，团队由主会话、多个独立 teammate、共享任务列表和消息系统组成。官方 agent teams 配置文档 还特别提醒：团队成员不会自动获得 worktree 隔离，必须通过文件边界或额外 worktree 方案避免同时编辑同一文件。

agent view 的适用边界

需要开发者自己启动和检查多个后台会话时，agent view 更接近“会话控制台”。它适合功能开发、Bug 修复和测试执行分别运行的场景，但这些会话默认仍消耗同一台机器上的本地资源。

官方文档指出，后台会话在本机睡眠或关机时会停止；会话删除后，其关联 worktree 也可能被清理，所以合并或推送必须先完成。官方 agent view 限制说明 对这些行为有明确描述。

按文件所有权拆分任务

一个适合 Claude Code 多 AI Agent 的拆分方案，不是把“开发一个完整功能”复制给多个 Agent，而是把交付物拆成可以独立验收的边界。

Agent 角色	负责范围	不应触碰	验收方式
研究 Agent	调用链、现有约定、风险记录	业务源文件	输出文件清单与证据
实现 Agent	独立模块或单一功能	共享迁移、锁文件	单元测试与提交摘要
测试 Agent	测试用例、回归脚本	未确认的接口实现	测试命令与失败日志
审查 Agent	安全、边界、可维护性	未经授权的重构	问题等级与复现步骤

推荐采用以下决策条件：

• 若任务只需要读取代码、日志或文档，则选 subagents；否则进入文件隔离判断。
• 若两个任务会修改同一个文件，则不要直接并行写入，改为指定单一负责人，其他 Agent 只提交建议。
• 若任务分别修改互不重叠的模块，则选独立 worktree，并为每个 worktree 使用独立分支。
• 若多个 Agent 需要持续互相发送结果，则选 agent teams；但仍要单独规划文件所有权。
• 若远程主机无法稳定保持多个终端会话，则回退到少量后台会话或分批执行。

这套判断比“让 Claude 自己决定是否并行”更容易审计，因为每个并行任务都有明确的触发条件和回退路径。

为每个 worktree 重建环境

Git worktree 是新的检出目录，主目录中未被 Git 跟踪的文件不会自动完整出现。常见问题包括依赖未安装、虚拟环境路径失效、构建工具版本不同，以及本地环境变量缺失。

可以按以下顺序初始化：

1. 确认仓库状态。 在主目录执行 git status，确认没有未提交的关键改动，并决定 worktree 从远程默认分支还是当前本地提交创建。
2. 建立隔离目录。 使用 claude --worktree <名称>，或通过 git worktree add 创建目录和分支。
3. 执行可重复初始化。 让每个 Agent 运行项目已有的安装、生成和数据库准备脚本，不要依赖某个开发者机器上的手工状态。
4. 处理被忽略文件。 如果确实需要复制 .env 等被忽略文件，可以配置 .worktreeinclude；但秘密不应写入仓库，也不应通过普通提示词暴露给 Agent。
5. 检查工具链。 在每个 worktree 中验证运行时、包管理器、编译器、测试框架和系统权限。
6. 记录环境结果。 将初始化命令、失败原因和修复方式写入任务摘要，避免下一个 Agent 重复排查。

对于远程 Mac，建议把初始化脚本、权限审批和依赖缓存提前准备好。远程环境并不会因为创建了多个 worktree 就自动共享所有运行时状态；共享缓存可能节省下载时间，但也可能引入锁竞争，因此需要由项目脚本明确控制。

⚠️ 安全边界： .worktreeinclude 适合复制被 Git 忽略但确实需要的本地配置，不等于秘密管理系统。生产密钥、长期令牌和个人访问令牌仍应通过受控的环境注入方式提供。

用统一门禁验收，而不是相信完成声明

每个 Agent 完成后都应返回一份固定格式的交付记录：

任务状态：完成 / 阻塞 / 部分完成
分支名称：
变更文件：
提交：
执行过的测试：
测试结果：
已知限制：
回滚方式：
需要主会话确认的事项：

主会话或独立审查 Agent 再执行统一门禁：

• ✅ 工作目录没有意外修改；
• ✅ 提交只包含任务范围内的文件；
• ✅ 单元测试、类型检查和构建命令通过；
• ✅ 没有新增未解释的依赖或锁文件变化；
• ✅ 生成代码与源文件保持一致；
• ✅ 已知限制已经写进合并请求；
• ✅ 回滚方式能够在干净 worktree 中复现。

如果测试 Agent 与实现 Agent 同时运行，测试结果必须标注基于哪个提交。否则，测试通过可能只是因为它读取了主目录中的旧文件，或者测试会话根本没有验证实现分支。

按依赖顺序合并并处理冲突

多个分支完成后，不要一次性把所有提交合并到主分支。更稳妥的顺序是：

1. 先合并公共接口、类型或基础设施变更；
2. 在主分支执行格式检查、类型检查和快速测试；
3. 再合并依赖这些接口的功能分支；
4. 每次合并后重新运行受影响模块的测试；
5. 最后合并文档、测试补充和低耦合改动；
6. 出现冲突时保留单一事实来源，不要把两套替代实现机械拼接。

如果两个 Agent 实现的是同一个需求的不同方案，应先按验收指标比较：正确性、测试覆盖、迁移风险、性能边界和回滚难度。只有在指标明确后选择一个方案，不能因为两个分支都“已经完成”就同时合并。

Git 原生 worktree 也可以手动管理：

git worktree list
git worktree remove ../project-feature

清理前应确认分支已经合并或推送。官方文档说明，包含未提交改动、未跟踪文件或新提交的 worktree，在清理时可能需要人工确认；非交互运行不会自动替开发者完成所有清理操作。官方清理行为说明

用检查清单控制并发资源

多个 Claude Code 会话会同时消耗终端、CPU、内存、磁盘、网络和模型使用额度。并发数并不等于有效吞吐量：如果所有 Agent 都在等待同一个接口、同一个锁文件或同一个测试环境，额外会话只会增加协调成本。

启动前检查：

• [ ] 每个任务都有明确输入、输出和停止条件；
• [ ] 每个代码写入任务都有独立 worktree 或唯一文件所有权；
• [ ] 共享接口、迁移和生成文件已经指定负责人；
• [ ] 每个会话都有最大重试次数；
• [ ] 测试、构建和审查不会无限后台运行；
• [ ] 主会话设置了人工确认点；
• [ ] 远程环境能够持续运行预计的在线时长；
• [ ] 合并前已保存提交、测试结果和回滚信息。

当任务只是偶发的构建、测试或代码审查时，本地设备通常更容易保留调试上下文；当开发者需要长时间同时运行多个会话，并且本机无法稳定承担构建和终端任务时，再评估按周期使用的远程 Mac 环境。可以先查看 Zutcloud 的 Mac 租用方案，再结合 Mac mini 价格信息 计算实际在线时长与资源占用。

FAQ：并行运行前需要确认的细节

多个 Agent 的启动方式应该怎样选择？

研究型任务可在一个会话中委派 subagents；独立开发任务可分别打开多个 worktree 会话；需要主会话统一分派和沟通时，可启用 agent teams。启动方式不同，文件隔离也不同，所以命令、分支和验收记录必须一起规划，不能只增加 Agent 数量。

subagents 与 worktree 分别解决什么问题？

subagents 隔离的是对话上下文和任务责任，默认返回摘要；worktree 隔离的是检出目录、文件修改和分支状态。前者适合分析和搜索，后者适合并行写代码。需要让 subagent 修改文件时，应明确要求使用 worktree 隔离，不能把上下文隔离误认为文件隔离。

多个会话怎样避免互相覆盖代码？

首先为每个会话建立独立 worktree，其次为共享文件指定唯一负责人，最后在合并时按依赖顺序逐个验证。对于无法拆分的高冲突文件，最安全的方式不是增加 Agent，而是让一个 Agent 编码，其他 Agent 提供审查意见和测试用例。

不同分支是否支持同时开发？

可以。不同 worktree 可以对应不同分支，多个 Agent 能在各自目录中读写文件并提交变更。不过分支隔离只解决修改互相覆盖的问题，不会消除接口假设、依赖版本和迁移顺序带来的逻辑冲突。

远程多会话部署前要准备哪些条件？

远程 Mac 需要稳定的 Git、运行时、依赖安装脚本、认证配置、网络连接和权限策略；如果使用分屏式 agent teams，还要确认终端支持 tmux 或相应的 iTerm2 模式。远程主机还应有会话中断后的恢复和 worktree 清理方案。

结尾：先算清在线时长，再决定运行位置

与在同一个本地目录里直接开启多个 Claude Code 会话相比，普通本地方案容易受到睡眠、磁盘空间、依赖环境不一致和构建资源不足的影响；单纯依赖远程后台会话，又可能遇到网络中断、权限审批和清理不及时等问题。长期稳定、重负载并且需要物理接口的开发任务，更适合自购并维护 Mac；偶发的并行测试、短期项目或需要临时扩展环境时，按周期使用远程 Mac 往往更容易控制投入。

如果本地设备无法持续承担构建、多 worktree 和多会话任务，可以进一步了解 Zutcloud 的帮助中心，再根据计划运行的会话数量、构建持续时间和项目敏感数据要求，判断是否需要租用一台独立的远程 Mac。

FAQ

Claude Code 如何同时启动多个 Agent？

如果只是把搜索、日志分析或代码库探索交给后台任务，可以在一个会话中使用 subagents；如果需要多个独立会话同时运行，可使用 agent view；如果希望由一个主会话管理多个协作者，则可以启用实验性的 agent teams。涉及并行修改文件时，还需要为会话或 subagent 配置独立 worktree。

subagents 和 worktree 有什么区别？

subagents 主要解决上下文和任务委派问题：它们在独立上下文中完成子任务，再向主会话返回摘要。worktree 主要解决文件系统隔离问题：每个工作目录拥有独立检出内容和分支，但共享 Git 历史。两者可以组合使用，不能互相替代。

Claude Code 多会话怎样避免文件冲突？

最稳妥的方法是让每个会话使用独立 Git worktree，并提前划分文件所有权。高冲突文件、依赖锁文件、数据库迁移和生成代码不要由多个 Agent 同时编辑；如果必须修改共享接口，应先由一个 Agent 产出明确提交，其余任务等待接口稳定后再开始。

Claude Code Agent 能否在不同分支并行工作？

可以。通过 `claude --worktree <名称>` 启动时，Claude Code 会创建独立工作目录和分支；也可以使用 Git 原生命令创建 worktree 后再进入目录启动会话。不同分支可以并行开发，但最终仍需按依赖顺序合并，并在每次合并后重新执行测试。

远程运行多个 Claude Code 会话需要什么环境？

远程环境至少要具备可用的 Git 仓库、完整依赖工具链、稳定的认证与网络配置，以及可重复执行的初始化脚本。还要考虑远程主机休眠、会话中断、并发资源和权限审批。若使用 agent teams 的分屏模式，还需要支持 tmux 或 iTerm2 的终端环境。

延伸阅读

• 多智能体框架全面对比：如何选择适合团队协作的方案
• AI Agent 文件系统设计指南：管理上下文、任务与协作状态
• 跨项目记忆如何配置：让编码助手复用团队经验