1. Claude Code + Codex 多 Agent 并行：小白也能用的分工方法

多 Agent 最容易出问题的地方，往往和聪明程度关系不大。
真正麻烦的是 5 个 Agent 同时改同一批文件。
最后看起来很热闹，实际合并时全是冲突，人还要倒回去擦屁股。

注：此文配图源自本人开源 skill：「卷卷整理研究所：内容插画 Skill」，https://github.com/dososo/juju-content-illustrations

现在 Claude Code、Codex、Gemini CLI 都开始支持 subagents 或并行 Agent 工作流。
官方文档里已经说得很直接：这类能力适合代码库探索、多步骤计划、批量审查、并行研究、组件拆分和大规模迁移。

但小白第一次用，很容易把「并行」理解成「同时让 5 个 Agent 随便改」。
这就危险了。
Agent 的能力越强，乱改文件的速度也越快。
一个人乱改，还能靠 git diff 慢慢看；
5 个 Agent 一起乱改，最后可能谁也说不清哪一段是为了什么。

更合适的做法是：主会话只做总控和验收，5 个 Agent 各自拿到明确边界。
能只读就只读，必须改文件就放进独立 worktree。
这样才能把并行变成效率，避免把项目搞乱。

1.1. 先分清楚：并行 Agent 适合什么任务

并行 Agent 适合那些可以拆开做、互相依赖不强的任务。
比如让一个 Agent 查登录模块，一个 Agent 查支付模块，一个 Agent 查测试覆盖，一个 Agent 查错误日志，一个 Agent 整理文档。
这些任务可以同时跑，最后把结果汇总回来。

它不适合一上来就让 5 个 Agent 同时改核心架构。
比如同一个状态管理文件、同一个数据库 schema、同一个 API 类型定义，如果 5 个 Agent 都去碰，冲突基本跑不掉。
就算 git 能合并，语义上也可能乱。

一个简单判断标准是：如果两个 Agent 会修改同一个文件，就先不要并行写代码。
可以让它们并行调研、并行审查、并行出方案，但真正改文件时要分区、分支、分顺序。

1.2. 最小可用结构：1 个总控，5 个工人

小白可以先用一个最简单的结构：主会话当总控，另外 5 个 Agent 当工人。
总控负责拆任务、定边界、收结果、做最终判断；工人只负责自己的小任务，不越界。

5 个 Agent 可以这样分：

这个分法的好处是，前两个 Agent 帮你看清楚项目，第三个 Agent 才动手改，第四个 Agent 负责验证，第五个 Agent 把过程留下来。
你不会一开始就把所有人丢进代码里乱改。

1.3. 先写 Plan，再派 Agent

多 Agent 并行之前，最重要的是写清楚任务边界，创建 Agent 反而是后面的事。
可以先让主会话输出一份 Plan，内容不用很长，但要包含四件事：目标是什么，哪些文件可能会被碰，哪些文件禁止修改，每个 Agent 最后要交付什么。

可以直接这样问：

请先不要改代码。
请阅读当前项目，给我一份多 Agent 并行执行 Plan。
要求包含：
1. 任务目标。
2. 可以并行的子任务。
3. 每个子任务允许读取和修改的文件范围。
4. 哪些文件禁止修改。
5. 每个 Agent 最终需要返回的结果格式。
如果两个子任务可能修改同一个文件，请标记为冲突风险，不要并行执行。

这个提示词的关键，是先把「哪些任务不能并行」找出来。
很多时候，真正有价值的 Plan 会先告诉你其中 2 个任务必须串行，然后再告诉你剩下的 Agent 怎么开跑。

1.4. 只读任务可以大胆并行

并行最安全的第一步，是只读。
让多个 Agent 同时读代码、查调用链、看测试、找文档、分析日志，通常不会踩文件。
OpenAI Codex 文档也提到，subagent workflow 很适合 codebase exploration 这类高度并行任务。

比如你可以这样派任务：

请并行启动 5 个只读 Agent，分别完成下面任务。所有 Agent 只能读取文件，不能修改文件。
A：梳理用户登录流程，输出关键文件和调用链。
B：梳理支付流程，输出关键文件和调用链。
C：检查测试目录，找出和本次需求相关的测试入口。
D：检查最近报错日志或错误处理代码，列出高风险点。
E：阅读 README、AGENTS.md、配置文件，整理项目约束。
请等待全部 Agent 返回后，合并成一份执行计划。

这一步跑完以后，你会得到一张项目地图。
它比直接让 Agent 改代码稳得多。
因为主会话还没有被海量搜索结果污染，5 个 Agent 又各自把细节压缩成摘要返回。

1.5. 要改文件，就用 worktree 隔离

只读任务可以在一个项目里并行跑。
写代码就要小心。
官方 Claude Code 文档专门强调 worktree：每个并行会话放在单独的 git checkout 里，文件互不接触。
Git 官方文档也说明，一个仓库可以同时有多个工作树，每个工作树可以 checkout 不同分支。

小白可以把 worktree 理解成「同一个项目的多个隔离副本」。
它们共享 git 历史，但文件目录分开。
A Agent 在 project-agent-login 里改登录，B Agent 在 project-agent-tests 里补测试，互相不会直接覆盖对方文件。

手动方式大概是这样：

git status
git worktree add ../project-agent-login -b agent/login
git worktree add ../project-agent-tests -b agent/tests
git worktree add ../project-agent-docs -b agent/docs
git worktree list

如果你用 Claude Code，它也有更省事的方式，比如官方文档里的 claude --worktree feature-auth。
命令可以以后再记，先理解原则：每个会改文件的 Agent，最好在自己的隔离目录里工作。

1.6. 每个 Agent 都要有「文件边界」

worktree 能隔离目录，但不能替你决定边界。
你仍然要告诉每个 Agent 它能改什么，不能改什么。

给实现 Agent 的提示词可以这样写：

你是 Agent C，负责实现登录页的表单校验。
允许修改：src/pages/login/*、src/components/form/*、tests/login/*。
禁止修改：数据库 schema、支付模块、全局路由、package.json。
如果发现必须修改禁止范围内的文件，请停止并写入 blocked.md，不要自行改动。
完成后请运行相关测试，并把修改文件、测试命令、测试结果写入 handoff.md。

这段提示词看起来啰嗦，但很有用。
它把 Agent 的活动范围圈住了。
遇到越界需求时，Agent 要停下来报告，不能为了完成任务自己扩大权限。

1.7. 不要让 5 个 Agent 都当程序员

实际用下来，5 个 Agent 全部写代码并不稳。
更好的做法是：2 个只读分析，1 个实现，1 个测试，1 个文档和验收。

这样安排有两个好处。
第一，冲突少。
真正写代码的 Agent 数量少，文件冲突自然少。
第二，验证更清楚。
测试 Agent 和文档 Agent 没参与实现，更容易发现实现 Agent 漏掉的地方。

如果项目很大，也可以开两个实现 Agent，但要保证它们修改的模块完全分开。
比如一个只改前端页面，一个只改后端接口；一个只改文档，一个只改测试。
只要边界模糊，就先不要并行写。

1.8. 合并时不要一把梭

5 个 Agent 都完成后，千万不要把所有改动一次性合进主分支。
正确做法是一个一个看 diff，一个一个跑测试。

可以按这个顺序：先看只读 Agent 的报告，确认 Plan 没跑偏；
再看实现 Agent 的 diff，确认它没有越界；
然后看测试 Agent 的结果，确认能跑通；
最后看文档和交接，确认下次还能接上。

如果使用 worktree，可以先在每个 worktree 里检查：

git status
git diff
git log --oneline -5

合并前，最好让主会话做一次总审查：

请审查这几个 Agent 的输出，不要改代码。
重点检查：
1. 有没有两个 Agent 修改同一个文件。
2. 有没有 Agent 修改了禁止范围。
3. 测试是否覆盖本次改动。
4. 哪些改动可以合并，哪些需要退回。
5. 合并顺序应该怎么排。

这一步很关键。
多 Agent 并行省下来的时间，不能在合并时全部赔回去。
先审查，再合并，最后跑全量测试。

1.9. 最容易犯的错

第一个，是把并行当成加速按钮。
并行只适合可拆分任务。
如果任务本身还没想清楚，开 5 个 Agent 只会把不确定性放大。

第二个，是不给 Agent 文件边界。
Agent 很容易为了完成目标顺手改全局配置、公共类型、依赖版本。
单个 Agent 这么做已经危险，多个 Agent 同时这么做，后面就很难收拾。

第三个，是只看最终答案，不看过程日志。
每个 Agent 都应该留下它读了哪些文件、改了哪些文件、跑了哪些命令、哪些测试通过、哪些地方没确认。
没有交接记录，下次还要重新问一遍。

第四个，是忽略成本。
Codex 文档也提醒过，subagents 会消耗更多 token，因为每个 Agent 都在做自己的模型和工具调用。
并行有成本。
任务越多，成本越高，速率限制也更容易触发。

1.10. 一个小白版完整流程

如果你第一次试，可以按这个流程走，不要一上来挑战大重构。

先选一个中等任务，比如「给登录页增加邮箱格式校验，并补测试」。
然后让主会话只做 Plan，不改代码。
Plan 确认后，开 5 个 Agent：A 查登录流程，B 查现有表单组件，C 在 worktree 里实现，D 在另一个 worktree 里补测试，E 写交接和风险清单。

等全部完成后，主会话先汇总，再审查 C 和 D 的 diff。
如果 C 和 D 改到了同一个测试文件，就先让主会话判断谁的改动保留。
合并一个，跑一次相关测试；
再合并下一个，再跑一次测试。
最后再跑全量测试。

整个流程看起来比「直接让 Agent 改」多几步，但它更适合真实项目。
真实项目慢一点还能接受，最怕的是改完以后没人知道哪里变了、为什么变、怎么验证。

1.11. 可以直接复制的总控提示词

下面这段可以直接给 Claude Code 或 Codex 用。
第一次建议只跑只读 Plan，确认靠谱后再放开写权限。

请作为总控 Agent，帮我设计一个 5 Agent 并行执行方案。
当前阶段不要改代码。

目标：{写清楚这次任务目标}

请你先完成：
1. 阅读项目结构和 AGENTS.md / README / 测试说明。
2. 判断任务能否拆成 5 个相互独立的子任务。
3. 给每个 Agent 分配任务、文件范围、权限范围和交付物。
4. 明确哪些 Agent 只能只读，哪些 Agent 可以在独立 worktree 里改文件。
5. 标记所有可能冲突的文件和需要串行处理的部分。
6. 给出合并顺序和验证命令。

输出格式：
- 总目标
- 5 个 Agent 的任务表
- 文件边界
- 冲突风险
- worktree 建议
- 验证命令
- 最终合并顺序

如果任务不适合并行，请直接说明原因，并给出更稳的串行方案。

1.12. 最后提醒

多 Agent 并行真正有价值的地方，在于把项目里的探索、实现、测试、文档和验收分开处理，而不只是让屏幕上同时跑很多东西。
主会话负责判断，工人 Agent 负责执行，worktree 负责隔离，测试负责兜底。

如果你是小白，第一次只记住一句话就够了：先并行读，再隔离改，最后逐个合并。
只读并行能帮你快速看清项目；
写代码一定要有文件边界和 worktree；
合并时不要偷懒，必须看 diff 和跑测试。

用好了，5 个 Agent 可以像一个小型开发小队。
用不好，5 个 Agent 就是 5 个同时改文件的新手实习生。
差别不在模型多强，差别在你有没有给它们清楚的边界和验收标准。

1.13. 参考链接

• Claude Code：Run agents in parallel
• Claude Code：Run parallel sessions with worktrees
• Claude Code：Create custom subagents
• OpenAI Codex：Subagents
• Google Developers Blog：Subagents have arrived in Gemini CLI
• Git：git-worktree Documentation