去年 11 月下旬，我已经投入到一个 WooCommerce 构建项目中三周了，这是为一个批发客户做的。大约三十个自定义文章类型、一个定制定价引擎，以及一个结账流程，其中的条件逻辑多得我不想再数。我是项目中唯一的开发者。我只是在插件层、主题覆盖和 REST API 端点之间频繁切换上下文，一天天地浪费时间。
那时我真正致力于并行运行 Claude Code 子代理。不是玩玩而已。我真的重新构造了我拆分工作的方式，这样多个代理可以同时运动而不会互相干扰。
以下是我学到的内容，包括我最初犯的错误。
---
Claude Code 中"子代理"的实际含义
人们对这个词使用得很随意。在 Claude 的代理框架中，子代理只是一个 Claude 实例，它从编排器接收一个有范围的任务，执行它，然后返回输出。编排器（它本身可以是一个 Claude 会话）决定如何拆分工作、要启动哪些子代理，以及如何整合结果。
实际上，对于大多数构建网站和应用的我们来说，这意味着运行多个终端会话，每个都有一个有焦点的 Claude Code 上下文，针对同一个代码库。有时编排是通过脚本自动化的。坦白说，通常只是我从 Notion 的计划文档中手动协调每个代理在做什么。
顺序和并行之间的区别
顺序代理工作是大多数开发者的默认做法：要求 Claude 执行任务 A，等待，然后要求它执行任务 B。对于简单的工作来说没问题。但如果 A 和 B 不依赖彼此的输出，你就在浪费时间。
平行子代理同时在独立工作流上运行。我提到的 WooCommerce 项目：我有一个代理在重构定价引擎逻辑，而另一个代理正在为 REST API 控制器生成 PHPDoc 注释。完全没有重叠。两者都在大约做一个花费的时间内完成了。
---
我如何实际构建工作拆分
这是没人清楚讲过的部分。代理设置很容易。难的是弄清楚要拆分什么。
我使用了一个简单的规则，这是我在 2022 年一次痛苦的合并冲突事件后想出来的：在同一个会话中，没有两个代理应该接触同一个文件。完全遵守。如果我不能保证这一点，这些任务就不会并行运行。
任何并行运行前的我的计划步骤
在我启动任何东西前，我写一个短的任务清单。没什么花哨的，只是一个纯文本文件或一个 Notion 页面，包含：
- 任务名称和一句话描述
- 范围内的文件（明确列表）
- 范围外的文件（任何可能诱使代理偏离的相邻内容）
- 预期输出格式
- 代理需要的任何不在代码库中的上下文
这大概需要15分钟。它让我避免了数量多得令人尴尬的冲突。
---
我最常拆分的三种工作流类型
在Seahawk进行了12000多次网站构建，加上我自己的客户工作，我注意到同样的分类反复出现，都是很好的并行化候选。
1. 文档和代码生成
一个代理编写或重构代码。另一个为不同的模块编写文档、测试或注释。这些几乎从不冲突，而且手动做都很繁琐。在WooCommerce批发项目中，我让一个子代理为定价函数生成PHPUnit测试桩，而另一个在构建自定义管理列。测试桩花了大约四分钟。管理列花了十二分钟。那四分钟我没有浪费任何时间等待。
2. 前端和后端隔离
如果你的前端和后端在清晰分离的目录中（应该这样，但那是另一个话题），这是自然的拆分。我曾让一个子代理在/resources/js中构建React组件，而另一个在/app/Http中连接Laravel控制器。唯一的协调点是在任何代理开始前就商定API合约。我把它写在项目根目录的AGENTS.md文件中。两个代理都参考了它。
3. 逐个模块重构
大型重构按顺序进行时很痛苦。如果你有八个功能模块各自需要相同类型的更改（更新过时的方法、迁移到新的助手，随便什么），就在代理之间拆分。我曾运行四个同时进行的代理，将一个遗留插件从WP_Query循环迁移到repository模式。每个代理负责两个模块。不到一小时完成。按顺序要花半天。
---
工具设置：我实际使用的东西
我不会假装我有什么复杂的基础设施。我的实际设置是：
- Claude Code在单台MacBook Pro M3的多个
tmux窗格中运行 - 项目根目录的共享
AGENTS.md文件，定义约定、文件所有权和工作流之间的API合约 - 每个代理一个Git分支。总是。即使分支只存在二十分钟
- 任何合并前都快速运行
git diff --stat来捕捉意外情况
AGENTS.md文件可能是我过去一年来为工作流添加的最有用的东西。它是一个纯markdown文件，告诉任何代理（或人工）项目约定是什么、哪些文件属于哪个工作流，以及什么要避免触碰。把它看作是一个为AI上下文窗口编写的CONTRIBUTING.md。
关于上下文窗口管理
这是人们变得懒散然后困惑的地方。每个子代理有自己的上下文。这意味着如果代理B需要知道代理A的决定，你必须明确地告诉它。它不会自动知道。
我通过维护一个SESSION_LOG.md来处理，在每个代理完成一个块后手动更新。最多三到五个要点：做了什么、改变了什么、下一个代理需要知道什么。开销很低。替代方案是代理做出假设破坏你的代码，那样的开销高得多。
---
问题出在哪里（来自痛苦的经历）
Seahawk去年春天有一个金融科技仪表盘项目，我们试图在没有定义适当文件所有权的单体仓库中运行子代理。两个代理都决定更新共享的utils/formatters.ts文件。都不知道对方。最终的合并在技术上没问题，但我们花了40分钟协调意图。完全可以避免。
我反复看到的失败模式：
- 共享实用工具文件。这是陷阱。锁定它们。如果子代理需要更新共享实用工具，该任务应该单独运行，而不是并行运行。
- 模糊的任务描述。如果你给一个agent说"清理auth模块"，它的解释会因上下文内容的差异而千差万别。要具体。"重构AuthController.php以使用已在app/Repositories/UserRepository.php中定义的UserRepository接口。不要修改接口本身。"这才是安全的提示。
- 没有分支隔离。在
main上运行所有agent就是你如何制造令人兴奋的周五下午的方法。分支不花钱。 - 跳过清单。我知道，我知道。这感觉像是额外负担。还是做吧。每次我跳过它，我都在一个小时内后悔了。
---
一次真正的并行运行，一步步来
上周二一个Shopify到WooCommerce迁移项目的会话大致是这样的（匿名化了，但结构完全一致）。
- 我用Notion写了任务清单。识别出四个可以并行化的任务。
- 创建了四个git分支：agent/product-import、agent/tax-logic、agent/rest-endpoints、agent/admin-ui。
- 打开了四个
tmux窗格，每个一个Claude Code会话。 - 在每个会话开始时粘贴了
AGENTS.md的相关部分作为上下文。 - 给每个agent它的任务提示，引用特定的文件。
- 同时运行所有四个。泡了杯咖啡。实际上在它还热的时候喝了，感觉像是个奇迹。
- 审查了每个分支输出。在PHP上运行phpcs，在任何touched的JS上运行eslint。
- 按顺序合并：先是产品导入（其他的对它的schema有轻微依赖），然后税务逻辑，然后REST端点，然后admin UI。
- 用发生的变化更新了
SESSION_LOG.md。
所有四个任务合并的总耗时：大约35分钟。我对顺序完成的估计是90分钟到2小时。这个我可以接受。
---
这做什么（和不做什么）替代
并行子agent不是思考的替代品。那个15分钟的规划步骤真的是你在做架构工作。agent执行。你仍然必须知道要构建什么、各部分如何契合，以及输出是否实际正确。
我在每个agent的输出接触main之前审查它。每一次。我曾经抓住一个子agent自信地写了一个缓存层，它本来会在多站点设置上导致陈旧数据问题。代码看起来没问题。它在逻辑上对特定上下文是错误的。之所以抓住它只是因为我读了它。
Anthropic自己关于agent任务的指导特别标记了在不可逆转的操作之前人工检查点的重要性。这不是企业模板语言。这是实际重要的建议，特别是当agent有数据库写入权限或正在运行迁移时。
这不替代的另一件事：与客户沟通。Agent可以构建一个功能。它不能告诉客户为什么截止日期改变了或管理围绕范围蔓延的期望。那部分仍然是你的。
---
FAQ
我需要特殊的API访问权限或工具来运行Claude Code子agent吗？
不需要奇特的设置。Claude Code是Anthropic的基于终端的编码工具，你可以在单独的终端会话中运行多个实例（我用tmux）。如果你直接调用API，你需要一个有足够速率限制的Claude API密钥。对于大型并行工作负载，在开始前检查你的速率限制层，这样你就不会在会话中途遭遇限流。
我如何阻止agent在共享文件上冲突？
在开始之前定义文件所有权。我描述的 AGENTS.md 约定效果很好。如果两个任务都需要修改同一个共享实用文件，不要并行处理这两个任务。先运行共享实用文件的更改，提交它，然后从这个干净的基础上并行运行其他任务。
这只在大项目中有用吗？
说实话，没有。我在单页网站上使用过它，当时我想在新功能代码旁边生成文档。规划的开销足够低，即使是适度的时间节省也能证明它的合理性。也就是说，如果一个项目的可并行化任务少于五个左右，设置时间就会开始超过收益。用你的判断力。
如果代理生成了不好的输出会怎样？
你在审查时发现它，丢弃分支，然后用更具体的提示重试。这就是分支隔离的整个要点。不好的代理输出只会消耗你审查它和重新提示的时间。如果你遵循每个代理一个分支的规则，它不应该让你的代码库崩溃。
我能自动化编排而不是手动做吗？
可以，对于重复的工作流来说值得这样做。我写过简单的 Bash 脚本，用预定义的提示和上下文依次启动 Claude Code 调用。对于完全自动化的并行编排，你需要构建一个编排层，以编程方式生成代理、收集输出并处理依赖关系。那是一项更大的工程投资。对于大多数自由职业者和小型代理商来说，用 tmux 和任务清单进行手动协调就足够了。
---
诚实的事实是，平行子代理并没有让我成为一个显著更好的开发者。它让我在特定的任务类别上变得更快，即瓶颈是执行而不是思考的地方。思考仍然是我的。架构决策、客户电话、代码审查。全都还是我。
但那些繁琐的执行部分？我会拿回我能得到的每一分钟。