Agentic coding workflow 的效果，高度依赖结构、规划与受控执行。随着系统变得越来越复杂，工具和自动化能力不断增多，如果仍然依赖临时式（ad hoc）的 prompting，就会明显提高意外改动和不可预测行为的风险。
本章将讨论 Claude Code 如何通过 planning 和 multi-agent execution 来支持结构化的 agentic workflow。它会展示：为什么从探索式 prompting 转向 spec-driven development 能够提升安全性与可预测性；以及多个 agent 如何被协调起来，在同一个代码库上高效协作。虽然示例使用的是 Claude Code，但这里讨论的原则对于更广泛的 agentic system 同样成立。
Claude Code 的 planning mode 在官方文档中已有说明。若想快速了解 planning mode 的工作方式，以及什么情况下应该使用它，可以参考这里：
https://code.claude.com/docs/en/common-workflows#how-to-use-plan-mode
本章将涵盖以下主题：
- Claude Code 的 planning mode
- 并行使用多个 Claude Code agent
Claude Code Planning Mode
Claude Code 提供了一个 planning mode，它让开发流程能够从探索式编码，过渡到 spec-driven development。这是 agentic coding workflow 中一个非常基础的原则。
在 planning mode 下，Claude Code 被限制在只读操作范围内，它的职责是在任何代码改动发生之前，先产出一份 specification 或 implementation plan。
Planning mode 允许 Claude Code 去研究、分析并推理某个问题空间，然后给出详细实现计划。在这份计划被显式 review 和批准之前，不允许进行代码修改。
Planning Mode 的特征
Planning mode 是一个只读阶段。在这个阶段里，Claude Code 可以：
- 读取文件
- 分析代码库
- 发起 MCP 调用
- 检索文档
- 设计解决方案
但它不能：
- 编辑、创建或删除文件
- 提交 Git commit
- 安装包
- 执行任何会改变环境状态的操作
这种模式非常接近资深软件工程师的工作方式。整个过程通常从收集上下文、理解需求与业务约束开始；然后进入规划；最后只有在 review 和 approval 之后，才进入执行。
Planning Workflow
Planning workflow 遵循一个结构化顺序：
- Claude Code 研究并分析现有代码库，或用户提供的需求
- 形成一份完整的实现计划或规格说明
- 把这份计划呈现出来供 review
- 在得到批准之后，Claude Code 退出 planning mode 并进入实现阶段
这种把“策略”与“执行”分开的方式，会带来更高的一致性与安全性，尤其是在处理大型代码库或复杂项目时尤为重要。
通过建立一个只读的 planning 阶段，这套 workflow 为后续的实现决策打下了一个更安全、更审慎的基础。也正因为有了这个基础，我们才能理解为什么 specification 这类 planning artifact，会在更可靠的开发 workflow 中扮演核心角色。接下来就会继续展开这一点。
Spec-driven Development 的价值
Planning mode 在设计复杂系统或理解大型项目时尤其有用。它最主要的价值，在于把规划和执行清晰分开，从而降低风险、提高可靠性。
一种常见做法，是把 Claude 生成出的 plan 或 specification 导出成一个 Markdown 文件。这个文件可以被共享、被团队共同 review，并在整个项目生命周期中反复复用。这样一来，Claude Code 的价值就不只是“生成一次计划”，而是把 planning artifact 变成了显式且持久的资产。
这其实就是 spec-driven development 的一个典型 workflow。不是一上来就立刻写功能，而是先花时间定义业务问题、明确到底要解决什么，以及应该怎么解决。这样做通常会带来更好的结果，尤其是和 subagent 配合时，还能减少整体实现时间。
一份定义良好的 specification，会为语言模型清晰限定问题空间，建立边界，并减少 hallucination。它还能避免一些意外副作用，例如无关文件被修改，或者不相关功能发生回归。
下面这个例子会展示：这些原则如何在一个端到端的 planning 与 refinement workflow 中被真正用起来。
示例：迭代完善 Hook Marketplace 的规格说明
在这个练习中，我们将使用 Claude Code 的 planning mode，为一个名为 HookHub 的新 Next.js 项目起草规格说明。我们不会直接写实现，而是先把项目结构和需求定义成一个 planning artifact。这样就可以在真正生成代码之前，反复迭代和优化设计。
实操：使用 Planning Mode
在项目目录中打开 Claude Code：
claude
进入 planning mode：
/plan
下面的示例展示了：在输入 /plan 之后，Claude Code 会运行在 planning mode 下。
图 6.1 —— 执行 /plan 后，Claude Code 进入 planning mode
进入 planning mode 之后，输入如下 Prompt：
Create a detailed specification for a web application called HookHub
The application should:
Display available Claude Code hooks
Render them as cards
Link each card to its GitHub repository
Support filtering by hook event type
这里，Claude Code 被要求为一个名为 HookHub 的 Web 应用生成规格说明。这个应用本质上是一个 Claude Code hooks 的 marketplace，用于展示可用的 hook。页面会以卡片形式展示这些 hooks，每张卡片都链接到一个 GitHub 仓库，而该仓库中包含一个面向开发工作流的 Claude Code hook。应用还应支持按 hook event type 进行筛选。
在 planning mode 下，Claude Code 会先生成一个初始任务列表，收集相关信息，并产出一份 specification 文档。整个阶段都不会写代码。Claude Code 只做研究、定义概念，并输出一份结构化的规格说明，供后续实现使用。
图 6.2 —— 在 planning mode 中生成的 HookHub 初始规格说明
初始规格里会包含一些仍需进一步打磨的设计决策和功能决策。比如，在这个示例中，hooks 被设计成用 carousel 形式展示，而且只覆盖了部分 hook event type。
接下来，规格会通过反馈继续 refinement。比如：去掉 carousel 展示方式，改成在首页直接展示全部 hook cards；同时，把更多 hook event type（包括代码生成之后触发的事件）补进规格说明中。
持久化保存 Hook Marketplace 的规格说明
当 refinement 完成后，最终版的 Hook Marketplace 应用规格说明会被导出成一个 Markdown 文件。
图 6.3 —— 将 HookHub 的规格说明导出并保存为 Markdown 文件
这个 .md 文件可以被提交到仓库中，或者存放在一个专门的位置，比如 .claude 目录下。这样，这份规格就会作为一种持久化的项目 memory 被保存下来，并在后续的 Claude Code 请求中反复作为上下文使用。
这份持久化 specification 会在实现阶段约束 Claude Code 的行为，并在与 subagent 协作时，提供一致的指导。
这个例子展示了：如何利用 planning mode 和 deep thinking，生成、打磨并保存一份具体应用的规格说明。通过对真实设计决策的反复迭代，并把最终产物保留为项目 memory，这套 workflow 为真正执行阶段建立起了稳定上下文。有了 specification 之后，更高级的执行模式——包括并行开发——也才能更有效地展开。
并行使用多个 Claude Code Agent
Claude Code 支持同时运行多个 AI agent，从而加速开发 workflow。核心思想是：把独立任务并行化，让更多工作在更短时间内完成。具体做法，就是在同一个项目中运行多个 Claude Code 实例。
你可以把这个 workflow 理解成一个多智能体编码系统的入门示例。虽然还可以构建更复杂、包含 sub-agent 的 agentic workflow，但这里展示的是两个独立 Claude Code 实例并行运行的最简单形式。
图 6.4 —— 多个并行 Claude Code agent 在同一个共享代码库上工作
多个 agent 可以类比成多个开发者同时在同一个项目、同一个 GitHub branch 上工作。每个 agent 都对整个代码库拥有读写权限。这种共享访问方式确实能支持协作，但也要求你在任务分配上足够谨慎，否则很容易引发冲突。这个 workflow 是否有效，取决于你分配给每个 agent 的任务本质。
识别适合并行执行的任务
只有当任务彼此独立时，并行执行才是有效的。适合并行的任务包括：
- 修复互不相关的 bug
- 构建不同的 UI 页面
- 在一个组件库中创建相互独立的组件
这些任务彼此不会干扰，因此可以同时推进。
但如果任务之间存在依赖关系，就不应该并行执行。一个典型例子是全栈功能：后端先实现一个 API endpoint，前端再去消费它。如果把前后端分别交给两个 agent 同时做，前端 agent 往往会去调用一个实际上还不存在的 API。这样就很容易导致它基于假设去写 mock 实现，而这些假设最终可能和真实 API 不一致，从而带来接口不匹配问题。
在 multi-agent workflow 中，一个关键能力就是：判断哪些任务是真正独立的，哪些任务必须串行完成。独立任务可以并行推进；串行任务则必须按顺序执行。在这个 workflow 下，工程师的角色开始从“直接写代码”转向“协调和监督多个 AI agent 的工作”。
示例：在 HookHub 项目中进行并行开发
这个例子展示的是：如何基于本章前面已经创建出的 HookHub specification，让多个 Claude Code agent 并行工作。这份 specification 已经定义了应用结构，并为实现过程提供了共同参照。
项目基于 project/hookhub 分支，从一个特定 commit 开始。这个 commit 表示当前应用的基线状态，也是这些 agent 开始工作的起点。
确立起始状态
这个 demo 从 project/hookhub 分支的如下 commit 开始：
<insert commit hash here>
要复现这个起始状态，可执行：
git checkout project/hookhub
git reset --hard <commit-hash>
npm install
npm run dev
此时，应用会展示：
- 一个基础版 hero section
- 以简单布局渲染出来的 hook cards
- 尚未做进一步视觉优化的页面
也就是说，这个应用已经能展示 hook cards，并且可以作为后续并行任务拆分的上下文基础。
图 6.5 —— 用于识别独立任务、以便并行执行 agent 的 HookHub 界面
如果想高效使用多个 agent，首先要做的就是识别出那些真正独立的任务。只有独立任务，才适合并行处理，从而真正提升开发速度。
给 Agent 分配独立任务
在当前这个 HookHub 界面里，有两块内容可以分别独立优化，因此是非常适合并行处理的候选项：
- 优化 hook card 组件的视觉设计
- 优化主页 hero section 的视觉设计
图 6.6 —— 两个并行运行的 Claude Code 实例，分别修改 HookHub 界面的不同部分
接着，把这两个任务分别分配给两个不同的 Claude Code 实例。一个 agent 只负责修改 hook card 组件文件；另一个 agent 只负责修改 hero section。
同时运行多个 Claude Code 实例
打开两个不同的终端窗口。
Terminal 1 —— 更新 Hook Card 组件
claude
Prompt：
Improve the visual design of the HookCard component.
Modify only:
src/components/HookCard.tsx
Do not modify other files.
Terminal 2 —— 更新 Hero Section
claude
Prompt：
Redesign the hero section.
Modify only:
src/components/Hero.tsx
Do not modify HookCard.tsx.
这样，两个 agent 就开始并行独立运行了。
之所以这种 setup 能顺利工作，是因为 HookCard 和 Hero section 分别定义在不同文件中。如果它们被写在同一个文件里，那么并发修改就很容易引发冲突。
把组件拆到各自独立文件中，本身就是软件开发的一项通用最佳实践：它能提高可维护性、可读性和可测试性。而在 agentic workflow 下，这一点会变得更加重要。
并发执行任务
这两个 Claude Code 实例会各自独立运行，并并行执行分配给自己的任务。每个 agent 都只修改与自己任务相关的文件。由于两个组件已经被隔离，因此在执行过程中不会发生文件冲突。
当执行完成后，更新后的 hook card 组件和更新后的 hero section 就都会反映出各自负责的改动。
图 6.7 —— HookHub 界面：hook cards 与 hero section 被并行更新之后的效果
审查并提交改动
当两个 agent 都完成工作之后，就可以对改动进行审查并提交到仓库。
先执行：
git status
git diff
如果改动看起来没有问题，再执行：
git add .
git commit -m "Refine HookCard and Hero using parallel Claude Code agents"
这个例子展示了：当任务彼此独立且作用域被正确限制时，多个 Claude Code 实例可以并发使用，从而加快开发速度。
本章里的示例，故意展示的是 multi-agent execution 最简单的一种形式：多个 Claude Code 实例在同一个 branch 上共享文件访问权限，只通过修改不同文件来规避冲突。
这种 setup 有助于你理解并行执行的核心思想。但必须说明：让多个 agent 直接在同一个 branch 上工作，本质上是脆弱的。如果它们修改了重叠文件，或者引入了不兼容改动，就会发生冲突。
在专业开发环境中，更标准的做法，是通过 Git branch 或 Git worktree 来隔离改动。使用 Git worktree 时，每个 agent 都在自己的工作目录、自己的 branch 上运行，相当于各自拥有一份独立代码副本。之后，再通过一个可控流程去审查和合并这些改动。
本章主要关注的是概念清晰度，以及最容易复现的最小 setup。更健壮的并行策略——包括分支隔离、结构化合并流程——会在本书后面的章节里继续展开。
总结
在本章中，我们讨论了 Claude Code 如何通过 planning mode 和 multi-agent execution 来支持 agentic development workflow。我们看到，planning mode 通过把分析与实现分离，实现了 spec-driven development；而 specification 又可以借助 deep thinking 反复 refinement，并作为项目 memory 持久保留下来。我们还演示了：多个 Claude Code agent 如何在同一个共享代码库中，针对独立任务并行工作。
在下一章中，我们将继续深入 Claude Code subagents，看看它们如何在复杂开发任务中支持更结构化、更隔离、更并发的 workflow。
