Claude Code Subagent与结构化任务分解：何时使用哪种方式

结构化任务分解实践

当答案是"独立agent"时，你需要一种方法把feature分解成可以并行运行而不互相干扰的任务。

分解过程：

1. 识别依赖图。 在拆分任何东西之前，先标注什么依赖什么：

Feature: User profile page with activity feed

- API endpoint: GET /users/:id/profile     (no deps)
- API endpoint: GET /users/:id/activity     (no deps)
- React component: ProfileHeader            (depends on profile API)
- React component: ActivityFeed             (depends on activity API)
- Integration test: profile page end-to-end (depends on all above)

两个API端点没有依赖关系。可以并行运行。两个React组件各依赖一个API。集成测试依赖所有。

2. 划定所有权边界。 每个任务获得一个文件范围。Profile API agent拥有server/routes/profile.ts和server/services/profile.ts。Activity API agent拥有server/routes/activity.ts和server/services/activity.ts。谁也不碰对方的文件。如果共享工具需要修改，一个agent创建变更，另一个等待。

3. 为每个任务定义验收标准。 每个任务需要一个明确的"完成"条件，可以在不查看其他任务的情况下验证。"Profile API以正确格式返回200"是可验证的。"个人资料页面能用"不行，因为它依赖集成。

4. 指定交接制品。 下游agent从上游agent需要什么？通常是：已知分支上的已commit代码、状态更新、以及描述接口契约的评论（API形态、组件props、函数签名）。

这种分解将模糊的"构建个人资料页面"转化为五个离散任务，带有明确的依赖关系和验证标准。每个任务可以分配给一个恰好拥有所需上下文且不多不少的agent。

用Beads进行结构化分解

这就是拥有真正任务系统的重要性所在。你不能用便签和终端输出追踪五个并行任务。

beads是一个本地优先的issue追踪器，原生地建模这种分解。Epic代表feature。Children代表子任务。Dependencies阻止agent在前置条件完成前开始工作。

实践中的分解如下：

# Create the epic
bd create --title "User profile page with activity feed" \
  --type epic --priority p2

# Create subtasks as children
bd create --title "GET /users/:id/profile endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "GET /users/:id/activity endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "ProfileHeader React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-api

bd create --title "ActivityFeed React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-activity-api

bd create --title "Profile page integration test" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-header,bb-activity-feed

结构现在是显式的。运行bd show bb-profile-header的agent看到它依赖profile API任务。如果那个任务还没完成，agent知道不该开始。当API agent完成并标记任务完成时，前端agent的依赖被解除。

Agent工作流遵循可预测的循环：

# Agent claims the task
bd update bb-profile-api --claim --actor eng1

# Agent comments its plan before writing code
bd comments add bb-profile-api --author eng1 "PLAN:
1. Create route handler at server/routes/profile.ts
2. Add service layer at server/services/profile.ts
3. Return shape: { id, name, avatar, bio, joinedAt }
4. Test: curl localhost:3000/users/1/profile returns 200"

# Agent implements, tests, commits
# ...

# Agent marks done with verification steps
bd comments add bb-profile-api --author eng1 "DONE: Profile endpoint implemented.
Returns { id, name, avatar, bio, joinedAt }.
Verified: curl returns 200 with correct shape.
Commit: abc1234"

bd update bb-profile-api --status ready_for_qa

每一步都有记录。QA agent读DONE评论，准确知道如何验证。下游agent读PLAN评论，在代码完成之前就知道API契约。

这不是为了流程而流程的开销。这是防止五个并行agent产出五份不兼容代码的最小结构。

默认选择

在生产工作中运行并行agent数月之后，这是我遵循的决策树：

从subagent开始，当：

• 任务是研究或探索（搜索、阅读、比较）
• 结果需要汇聚为单一行动
• 所有工作在一个上下文窗口内
• 不需要对每个并行单元进行独立验证

切换到独立任务，当：

• 工作的不同部分触及不同文件
• 每个部分有自己的验收标准
• 你希望QA独立验证各部分
• 工作时间足够长，一部分可能比另一部分早完成数小时
• Agent需要不同的上下文（前端agent不需要数据库内部细节）

复杂feature的混合方式： 研究和规划阶段使用subagent（扇出、收集信息、综合计划），然后将实现分解为独立agent的独立任务。Spec-driven development工作流在这里自然契合：一个带subagent的单一agent编写spec，然后spec分解为多agent舰队的任务。

可视化分解

当你有五到十个带依赖关系的结构化任务时，在终端中追踪进度变得困难。bd list显示的是扁平列表。它不显示哪些任务被阻塞、哪些准备开始、或epic进展到了哪里。

这就是Beadbox解决的问题。它读取同一个beads数据库，渲染带进度指示器、依赖关系和agent分配的epic树。你可以看到哪些子任务已完成，哪些因前置条件而阻塞，哪些准备好让agent领取。用--deps指定的依赖图变成你并行工作的可视化地图。

当agent完成任务并更新状态时，Beadbox实时反映变化。不用刷新，不用重新运行bd list。树更新了，进度条移动了，阻塞的任务随着依赖解除而解除阻塞。

同样的数据。只是变得可见了。

如果你正在构建这样的工作流，在GitHub上给Beadbox一颗星。