你刚启动了第二个 Claude Code agent。问题来了。

第一个 agent 正在做重构。第二个需要开发一个涉及部分相同文件的功能。它们互相不知道对方的存在。你同时充当路由器、状态存储和冲突解决者,而你唯一的工具就是在终端窗口之间复制粘贴上下文。

大多数开发者在使用 Claude Code 时就是在这里碰壁的。不是因为 agent 编码能力差,而是因为没有系统告诉它该做什么。

复制粘贴问题

大多数 Claude Code 工作流的开头都一样。你脑子里有个任务(或者在 Jira 里,或者在 GitHub issue 里),然后把描述粘贴到 agent 的 prompt 中。"做一个认证流程。""修复分页 bug。""加上暗色模式支持。"

对单个 agent 来说,这没问题。agent 拥有完整上下文,你可以观察它的输出,而且因为你一直盯着它,所以知道什么时候完成了。

加上第二个 agent,裂缝立刻出现。

Agent A 在重构 API 层。Agent B 在构建新的 endpoint。两个都在改 server/routes.ts。彼此不知道对方的改动。你在一方 push 后另一方的工作崩溃时才发现冲突。更糟的情况是,两边本地都成功了,但合并结果以任何 diff 都看不出来的方式损坏了。

根本原因不是 agent 做事粗糙,而是缺少共享状态。没有地方记录"Agent A 负责 API 重构"。没有状态说明"routes 文件正在被修改,请等待"。agent 们各自基于独立的 prompt 运行,对全局一无所知。

加上第三个 agent,你花在协调上的时间就超过了写代码的时间。

Agent 真正需要从任务系统得到什么

在寻找工具之前,值得问一下:Claude Code agent 要做好工作,到底需要什么?

答案是出乎意料地少。

一个唯一标识符。 可以在 commit 和评论中引用的东西。"修了那个 bug"在多 agent 日志里毫无用处。"完成 PROJ-47:过滤视图下分页返回错误计数"是可追踪的。

明确的范围。 标题、描述和验收标准。不是长篇大论,不是带人物角色的用户故事,而是"完成"是什么样子的具体陈述。"/users endpoint 返回分页结果。页面大小默认 25。next_cursor 字段在最后一页为 null。"

可更新的状态。 Agent 需要表明自己所处的阶段:已认领、进行中、已完成。没有这个,你又回到了盯着终端窗口猜测的老路。

依赖感知。"PROJ-46 合并之前不要开始这个"能防止最常见的多 agent 故障:在还不存在的代码上构建。

注意这个列表里缺少什么。Sprint 规划、速度跟踪、看板、故事点、带彩色标签的 epic。Agent 不需要项目管理的形式主义。它们需要的是一个任务、一个状态,以及说"我完成了"的方式。

CLAUDE.md 契约

任务系统告诉 agent 做什么。CLAUDE.md 文件告诉它们怎么做。

如果你在运行多个 Claude Code agent,每个都应该有一个定义其身份和边界的 CLAUDE.md。这不是可选配置,而是 agent 能否协调与互相干扰之间的区别。

下面是一个工程 agent 的精简示例:

## Identity

Engineer for the project. You implement features, fix bugs,
and write tests. You own implementation quality.

## What You Own

- All files under `components/` and `lib/`
- Unit tests in `__tests__/`
- You may read but not modify files under `server/`

## What You Don't Own

- Deployment configuration (that's ops)
- Issue triage and prioritization (that's the coordinator)
- QA validation (QA tests your work independently)

## Completion Protocol

Before marking any task done:
1. Run the full test suite: `pnpm test`
2. Verify your change works manually
3. Comment what you did with the commit hash
4. Push before reporting completion

边界部分是承重结构。没有明确的文件所有权,agent 就会越界。工程 agent "好心地"重构了部署配置。QA agent 通过修改被测代码而不是测试本身来"修复"测试。明确的边界能防止这些故障模式。

完成协议同样重要。它防止了最常见的 agent 故障:仅仅能编译通过就声称完成。"运行完整测试套件"和"手动验证"是具体的关卡。遵循此协议的 agent 产出的工作是人类可以信任的。没有协议的 agent 产出的工作需要你逐行检查。

将此扩展到多个 agent,你就得到一个每个成员都知道自己的车道、交接协议和"完成"含义的团队。

CLI-first 任务管理

这里有一个工作流观察,我花了比应有更长的时间才内化:Claude Code agent 用 CLI 工具比 GUI 界面工作效果好得多。

想想就明白了。Claude Code agent 生活在终端里。它能执行命令、读取输出、根据结果采取行动。要求它浏览 web UI、点击按钮、解读渲染后的页面,是在对抗 agent 的天然界面。

基于 CLI 的任务系统意味着 agent 可以在单一流程中完成这些:

# Read the task
task show PROJ-47

# Claim it
task update PROJ-47 --status in_progress --assignee agent-1

# Do the work...

# Report completion
task comment PROJ-47 "DONE: Fixed pagination. Commit: abc1234"
task update PROJ-47 --status done

无需上下文切换。无需浏览器窗口。无需看板截图。Agent 读取任务、执行工作、更新状态,全程不离开它的工作环境。

输出也是机器可读的。当你需要检查各 agent 的情况时,可以查询:

task list --status in_progress    # What's being worked on?
task list --assignee agent-2      # What is agent-2 doing?
task list --blocked               # What's stuck?

这就是有效工具的形态。一个说 agent 语言的 CLI。

Beads:面向 agent 的本地优先 issue 跟踪

上面描述的工作流不是假设。这是我每天用 beads 运行的流程。beads 是一个开源的本地优先 issue 跟踪器,专为这种 agent 驱动的开发而构建。

beads 将 issue(称为"beads")存储在代码库旁的本地 Dolt 数据库中。每个 bead 有 ID、标题、描述、状态、优先级、依赖关系和评论线程。CLI 叫 bd,是 agent 用来读取任务、更新状态和留下结构化评论的接口。

这是一个真实的工作流。我创建一个任务:

bd create --title "Fix pagination on filtered views" \
  --description "The /users endpoint returns wrong count when filters are applied. Page size defaults to 25. next_cursor should be null on the last page." \
  --priority p2

Agent 认领它:

bd update bb-r3k2 --claim --actor eng1
bd update bb-r3k2 --status in_progress

在写任何代码之前,agent 评论它的计划:

bd comments add bb-r3k2 --author eng1 "PLAN:
1. Fix count query in /users to apply filters before COUNT()
2. Add cursor boundary check for last page
3. Add test cases for filtered pagination

Files:
- server/routes/users.ts - fix count query
- server/routes/users.test.ts - add filtered pagination tests"

这是一个检查点。如果计划有误,你在 30 秒内就能发现,而不是 45 分钟后才发现糟糕的实现。

Agent 完成工作,运行测试,然后评论完成情况:

bd comments add bb-r3k2 --author eng1 "DONE: Fixed filtered pagination count.

- COUNT() now applies the same WHERE clause as the data query
- next_cursor returns null when offset + page_size >= total_count
- Added 4 test cases covering filtered + unfiltered pagination

Commit: a1b2c3d"

bd update bb-r3k2 --status ready_for_qa

任务现在有了完整的审计跟踪:请求了什么、agent 计划了什么、实际做了什么、以及用于 review 的 commit hash。运行 QA 的第二个 agent 可以接手并独立验证。

这能工作是因为 beads 说的是和 agent 相同的语言。一切都是 CLI 命令。一切都产生结构化输出。工具和 agent 之间没有阻抗不匹配。

看到全局

CLI 工作流可以扩展到 3 或 4 个 agent,然后会触及新的天花板。不是工具的天花板,是认知的天花板。

到了 5 个 agent,运行 bd list 然后在脑中组装项目状态,就像阅读电子表格同时试图在脑中保持一个依赖关系图。哪些任务被阻塞了?哪个 agent 已经 20 分钟没更新状态了?功能 epic 完成了 60% 还是 80%?信息都在 CLI 输出中,但拼凑它需要的精力随每个额外 agent 而累积。

这就是 Beadbox 的位置。它是位于 beads 之上的实时仪表板,显示整个 agent 团队的状态。可视化渲染的依赖树。Epic 进度条。无需运行五个 bd show 命令就能浏览的 agent 评论线程。

Beadbox 不替代 CLI。Agent 仍然用 bd 做一切事情。Beadbox 是你需要全局视图时打开的那一层:哪些工作流在推进,哪些卡住了,瓶颈在哪里。它监视 beads 数据库的变更并实时更新,所以你永远不会看到过时的数据。

Beta 期间免费,完全在你的本地机器上运行。无需账号,无需云端,数据留在本地。

开始使用

你不需要 13 个 agent 就能从结构化任务管理中获得价值。从两个 Claude Code agent 和一条规则开始:每个任务创建一个 bead,每个 agent 在编码前评论它的计划,每次完成包含验证步骤。

这个模式会产生复利效应。一旦 agent 有了共享任务系统,你可以添加独立验证工作的 QA agent。可以添加从优先级队列分发任务的协调者。可以扩展到 5、10、15 个 agent,而协调开销不会线性增长,因为协议处理了以前需要手动上下文切换的工作。

工具:

beads 用于本地优先任务管理。开源。
Claude Code 作为 agent 运行时。
Beadbox 用于团队扩大时的可视化监控。

如果你正在构建类似的工作流,请在 GitHub 上给 Beadbox 加个 star。

如何管理 Claude Code Agent 的任务