task-dependency-patterns

任务依赖模式

概述

Claude Code 2.1.16 引入了原生任务管理系统，包含四种工具：

CC 2.1.268 注意事项： 只有在 Claude 3.x、Opus 4.0 至 4.7、Sonnet 4.0 至 4.6 以及 Haiku 4.5 上才会提供 TaskCreate、TaskGet、TaskUpdate、TaskList 和 TodoWrite。在不属于此允许列表的模型上，这些工具不可用，除非操作员设置了 CLAUDE_CODE_ENABLE_TODO_TOOLS=1。CC 仅会读取用户设置、受管设置（或 shell）中的标志。ork 无法随附此标志（CC 只会从插件设置中读取 permissions），因此应将此技能中的所有 Task 工具调用视为取决于操作员的环境。

• TaskCreate：创建包含主题、描述和 activeForm 的新任务
• TaskUpdate：更新状态（pending → in_progress → completed），设置依赖项
• TaskGet：获取包括阻塞项在内的完整任务详情
• TaskList：查看所有任务的状态和依赖关系摘要

任务支持结构化工作跟踪、并行协调和清晰的进度可见性。

适用场景

• 拆分复杂的多步骤实现
• 协调跨多个文件的并行工作
• 跟踪大型功能的进度
• 管理相关更改之间的依赖关系
• 让工作状态一目了然

关键模式

1. 任务分解

将复杂工作拆分为原子化、可跟踪的单元：

Feature: Add user authentication

Tasks:
#1. [pending] Create User model
#2. [pending] Add auth endpoints (blockedBy: #1)
#3. [pending] Implement JWT tokens (blockedBy: #2)
#4. [pending] Add auth middleware (blockedBy: #3)
#5. [pending] Write integration tests (blockedBy: #4)

2. 依赖链

使用 addBlockedBy 创建执行顺序：

// Task #3 cannot start until #1 and #2 complete
{"taskId": "3", "addBlockedBy": ["1", "2"]}

3. 状态工作流

pending → in_progress → completed
   ↓           ↓
(unblocked)  (active)

pending/in_progress → deleted

• pending：任务已创建，但尚未开始
• in_progress：正在处理中
• completed：工作已完成并验证
• deleted：任务已移除 — 永久删除该任务

删除任务

使用 status: "deleted" 永久删除任务：

// Delete a task
{"taskId": "3", "status": "deleted"}

适合删除的情况：

• 阻塞项均已失败的孤立任务
• 已被其他方案取代的任务
• 误创建的重复任务
• 已取消流水线中的任务

不应删除的情况：

• 之后可能重试的任务（保留为 pending）
• 包含有用历史记录的任务（改为标记为 completed）
• 被 in_progress 工作阻塞的任务（等待问题解决）

4. activeForm 模式

使用现在进行时形式显示旋转指示器：

subject（祈使形式）	activeForm（进行时）
运行测试	正在运行测试
更新架构	正在更新架构
修复身份验证	正在修复身份验证

Agent Teams

Agent Teams 支持多 Agent 协调，并提供共享任务列表和点对点消息传递。

CC 2.1.161 — 独立并行工具调用失败： 并行批次中的工具调用失败不再导致其他调用取消；每个调用都会返回自己的结果。队友必须独立检查任务状态并明确处理失败，而不能假设整个批次都已中止。

团队工作流

1. (implicit team — CC 2.1.178+)       → one team per session; no TeamCreate
2. TaskCreate(subject, description)    → Add tasks to shared list
3. Agent(name, team_name, prompt)      → Spawn teammates into the implicit team
4. TaskUpdate(owner: "teammate-name")  → Assign tasks
5. SendMessage(to, message, summary)   → Direct teammate communication
6. (turn / background ends)            → teammates wind down; Ctrl+F x2 for bg

跨会话回复会送达父会话（CC 2.1.248）： 当子 Agent 向另一个会话发送 SendMessage 时，回复会送达父会话的对话，而不会送达子 Agent；子 Agent 发出消息后继续执行，父会话读取回复。跨会话 SendMessage / ListAgents 也可在 Bedrock、Vertex 和 Foundry 上使用，并且在禁用遥测时也可用（CC 2.1.248）。

何时使用团队，何时使用 Agent 工具

标准	Agent 工具（子 Agent）	Agent Teams
独立任务	是	大材小用
跨领域更改	有限	是
Agent 之间需要沟通	否（星型拓扑）	是（网状拓扑）
成本敏感度	较低（约 1 倍）	较高（约 2.5 倍）
复杂度 < 3.0	是	否
复杂度 > 3.5	可以	推荐

团队任务模式

# Spawn teammate into shared task list. A teammate that writes files works in
# a manual worktree the lead creates first (#4557); the lead merges its branch
# before dependent tasks start. No isolation on the call: a call with name and
# isolation launches a plain subagent, not a teammate (Claude Code docs).
Bash("git worktree add .worktrees/backend -b feat/my-feature-backend feat/my-feature")
Agent(
  prompt="You are the backend architect... Work only in .worktrees/backend/ "
         "(cd there, check pwd and branch first). Commit your work there and "
         "message the lead your branch name and commit sha.",
  team_name="my-feature",
  name="backend-architect",
  subagent_type="ork:backend-system-architect"
)

# Teammate claims and works tasks
TaskList → find unblocked, unowned tasks
TaskUpdate(taskId, owner: "backend-architect", status: "in_progress")
# ... do work ...
TaskUpdate(taskId, status: "completed")
TaskList → find next task

点对点消息传递

# Direct message between teammates (params: to, message, summary)
SendMessage(to: "frontend-dev",
  message: "API contract ready: GET /users/:id returns {...}",
  summary: "API contract shared")

# No broadcast primitive — send to each teammate, or post to the shared
# task list (TaskCreate/TaskUpdate) so every teammate sees it
SendMessage(to: "backend-dev",
  message: "Breaking change: auth header format changed",
  summary: "Breaking auth change")

上下文耗尽处理

使用 Agent Teams 时，如果工作流进行到一半达到上下文限制：

• 通过 TaskList 收集已完成队友的部分结果
• 综合现有输出——优先采用部分结果，而不是静默失败
• 使用 TaskUpdate(taskId: task_id, status: "completed", metadata: {"skipped": "context limit"}) 记录跳过的任务

反模式

• 为简单的单步工作创建任务
• 循环依赖（A 阻塞 B，B 阻塞 A）
• 任务受阻时仍将其保留为 in_progress
• 完成后未将任务标记为已完成
• 仅与一名队友相关的消息使用广播
• 为简单的顺序工作组建团队（改用 Agent 工具）

相关技能

• ork:implement - 带有任务跟踪和进度更新的实现工作流
• ork:verify - 验证任务和完成清单
• ork:fix-issue - 基于假设的 RCA 跟踪问题解决方案
• ork:brainstorm - 使用并行 Agent 任务探索设计

参考资料

按需通过 Read("references/<file>") 加载：

文件	内容
dependency-tracking.md	依赖跟踪模式
status-workflow.md	状态工作流详情
multi-agent-coordination.md	多 Agent 协调