Claude Code 多智能体工作流指南：从 1 个到 N 个

调度循环

需要有人指挥。在多智能体 Claude Code 设置中有两个选择：你手动做，或者指定一个协调者智能体。

手动调度

你维护一个任务列表。给智能体分配任务。检查进度。处理阻塞。这在大约五个智能体时还行得通，之后协调开销就开始吞噬生产力增益了。

典型的手动调度周期：

1. 早上： 检查什么在进行中、什么被阻塞、什么准备好开始
2. 分配： 给每个智能体发送带上下文的下一个任务
3. 监控： 每 10-15 分钟检查智能体输出，寻找卡住的迹象
4. 解除阻塞： 当智能体遇到问题时，介入或重新分配
5. 收尾： 一天结束时检查交付了什么，规划明天

在 tmux 中，这看起来就是在面板间切换、读最近的输出、决定每个智能体接下来需要什么。像 gp（在不中断智能体的情况下查看其最近输出）这样的工具有帮助，但你仍然是瓶颈。

协调者智能体

专门指定一个 Claude Code 智能体来给其他智能体分配工作。这个智能体不写代码。它读取任务积压，将工作分配给空闲智能体，检查进度，并以编程方式处理调度循环。

这是我们使用的模式。我们的 "super" 智能体运行巡逻循环：每隔几分钟检查每个活跃智能体，核查任务状态，识别阻塞，在智能体空闲时分配新工作。人类（我）做优先级决策并解决模糊情况。Super 处理后勤。

协调者智能体需要自己的 CLAUDE.md：

# CLAUDE.md for Agent: super

## Identity
Dispatch coordinator. You assign work to agents, monitor progress,
and ensure the pipeline keeps moving. You do NOT write code.

## Responsibilities
- Maintain awareness of all active tasks and their statuses
- Assign ready tasks to idle agents
- Monitor agent progress every 5-10 minutes
- Escalate blockers to the human when agents can't self-resolve
- Verify agents follow the protocol: plan before code, test before done

## Communication
- To assign work: message the agent with task ID and priority
- To check progress: peek at agent's recent output
- To escalate: message the human with context and options

协调者模式比手动调度的扩展性好得多。10 个以上的智能体时，手动协调是全职工作。协调者智能体处理日常后勤，只将需要人类判断的决策上报。

多智能体工作的 tmux 布局

物理布局比你想象的重要。运行多个 Claude Code 智能体的 tmux 配置：

# Create a new tmux session
tmux new-session -s agents -n super

# Split into panes for each agent
tmux split-window -h -t agents:super
tmux split-window -v -t agents:super.1

# Or create named windows (easier to manage at scale)
tmux new-window -t agents -n eng1
tmux new-window -t agents -n eng2
tmux new-window -t agents -n qa1
tmux new-window -t agents -n frontend
tmux new-window -t agents -n backend

超过四个智能体后，命名窗口胜过分割面板。一个屏幕读不了五个面板，但在命名窗口间快速切换很容易。命名约定也重要。eng1、eng2、qa1 一眼就能扫到。agent-1、agent-2、agent-3 什么信息都没有。

在各自的工作目录中用各自的 CLAUDE.md 启动每个智能体：

# In the eng1 window
cd ~/project
claude --claude-md ./agents/eng1/CLAUDE.md

# In the qa1 window
cd ~/project
claude --claude-md ./agents/qa1/CLAUDE.md

一个实用建议：保留一个「仪表盘」窗口，它就是一个 shell。用来运行 git log --oneline -10、检查任务状态或在不中断智能体工作的情况下观察它们。这会成为你的指挥中心。

出问题的时候

多智能体工作流以可预测的方式失败。了解故障模式可以避免你付出代价去学习。

两个智能体编辑同一个文件。 通常是因为 CLAUDE.md 中的文件所有权不够具体。lib/utils.ts 是经典的冲突磁铁。解决方案：要么将共享工具文件分配给特定智能体，要么让所有人只读并通过单一所有者路由变更。

智能体沉默了。 遇到了速率限制、错误循环，或者卡在了深层推理链中。检查输出。如果在重试同一个失败命令，终止会话并用更清晰的指令重启。定期健康检查（每 10-15 分钟）能在你浪费一个小时之前捕获这种情况。

上下文窗口填满了。 长时间运行的智能体积累上下文，开始表现变差。每个智能体的 CLAUDE.md 应该包含相应协议：「如果工作超过 90 分钟，保存状态并请求新会话。」实践中，这意味着智能体提交工作、记录中断点，新的 Claude Code 会话从该提交继续。

工作偏离规格。 智能体构建了技术上可用但不符合要求的东西。解决方案是编码前先计划模式：写代码之前，智能体评论其实现计划。你 60 秒内审查计划，在误解变成 500 行差异之前抓住它们。

流水线停滞。 智能体 B 在等智能体 A，但智能体 A 在等你的决定。与此同时，智能体 C 30 分钟前就完成了工作，一直闲着。这是协调失败，不是技术问题。协调者智能体（或你）需要通过监控阻塞和重新分配空闲智能体来保持流水线运转。

我们如何用 Beads 解决这个问题

上述一切用便利贴和美好愿望就能运作。但大约到五个智能体时，非正式的方法开始出现裂痕。你忘了智能体 C 在做什么。搞不清哪些任务被阻塞了。记不住智能体 B 需要的 API 接口是已完成还是刚开始。

这就是 beads 解决的问题。Beads 是一个开源的、本地优先的问题跟踪器。每个任务是一个 "bead"，拥有唯一 ID、状态、描述、验收标准、依赖关系和评论线程。全部通过名为 bd 的 CLI 访问，这意味着你的 Claude Code 智能体可以在不离开终端的情况下读写。

使用 beads 的调度循环是这样的：

# See what's ready for work
bd list --status open

# Assign a task to an agent
bd update bb-a1b2 --claim --actor eng1

# Agent reads its assignment
bd show bb-a1b2

# Agent comments its plan before coding
bd comments add bb-a1b2 --author eng1 "PLAN:
1. Add endpoint at /api/users
2. Define UserResponse type in lib/types.ts
3. Write integration test

Files: server/api/users.ts (new), lib/types.ts (modify)
Test: curl localhost:3000/api/users returns 200 with JSON array"

# Agent finishes and comments what it did
bd comments add bb-a1b2 --author eng1 "DONE: /api/users endpoint live.
Returns paginated JSON. Added UserResponse type.

Verification:
1. curl http://localhost:3000/api/users → 200, JSON array
2. curl http://localhost:3000/api/users?page=2 → 200, second page
3. pnpm test → all passing

Commit: 8f3c2a1"

# Agent marks the task done
bd update bb-a1b2 --status closed

每个智能体遵循这个协议：认领、计划、实现、评论 DONE、更新状态。每个 bead 的评论线程成为完整的审计跟踪：发生了什么、为什么、如何验证。

依赖关系防止冲突工作：

# Create a task that depends on another
bd create --title "Build user list component" \
  --deps bb-a1b2 \
  --description "Frontend component that calls /api/users. Blocked until API is live."

依赖任务在 bb-a1b2 完成之前保持阻塞状态。没有智能体会过早拿起它。没人会浪费时间为尚不存在的 API 构建前端。

bd list 命令给你整个流水线的快照：

bd list --status in_progress
# Shows what every agent is actively working on

bd blocked
# 显示等待未完成依赖的任务

bd list --status open --priority p1
# Shows the highest-priority work that's ready to start

这取代了你脑中维护的心智模型。每个任务的状态、每个智能体当前的工作、每条依赖链，全部可以从命令行查询。

扩展可见性

CLI 能用。但在规模上，通过在终端运行 bd list 所能吸收的信息量有限。当八个智能体在三个 Epic 上工作，有十七个未完成任务和十几个依赖关系时，你需要看到工作的形状，而不只是列表。

这就是我们构建 Beadbox 要填补的空白。Beadbox 是一个实时仪表板，位于 beads 之上，向你展示：

• Epic 树带进度条，让你看到每个功能在所有子任务中的推进情况
• 依赖关系图，在阻塞工作停滞流水线之前将其浮出水面
• 智能体活动，展示哪个智能体在做什么，计划和完成评论在上下文中可见
• 实时更新，因为仪表板监控你的 beads 数据库，智能体更新任务状态时自动刷新

Beadbox 不替代 CLI。你的智能体仍然通过 bd 对 beads 进行读写。Beadbox 给你全局视图，让你能做出判断：哪个 Epic 落后了，哪个智能体需要帮助，瓶颈在哪里形成。

测试期间免费。如果你正在构建这样的工作流，请在 GitHub 上给 Beadbox 加星。

入门指南

不需要十三个智能体就能受益。最小可行设置：

1. 两个 Claude Code 智能体在不同的 tmux 窗口中，各自拥有定义文件所有权边界的 CLAUDE.md。
2. 一个任务列表（这个规模下文本文件就够了），让两个智能体都知道在做什么以及下一步是什么。
3. 提交协议： 两个智能体都频繁提交，开始新工作前先拉取。

当这变得自然之后，添加第三个智能体用于测试或文档。然后考虑协调者智能体。然后采用 beads 进行结构化任务跟踪。在协调痛点增加时扩展系统，而不是之前。

困难的不是工具。是思维方式的转变：从「我在用一个 AI 助手」到「我在管理一个团队」。CLAUDE.md 文件、调度协议、所有权边界：这些是管理实践，不是配置文件。你在建立一个组织，即使团队成员运行在 API 调用上。

从两个智能体和清晰的边界开始。其他一切从这里展开。