task-management-protocol

任务管理协议

使用 Claude Code 的原生任务工具，在 Agent 和会话之间进行任务同步、进度跟踪和上下文交接的标准化协议。

问题陈述

后台 Agent 完成工作后，主会话却收不到通知。Agent 不会在任务描述中更新发现结果。Agent 或会话之间也没有结构化上下文交接的协议。

此技能解决以下问题：

1. 会话结束或 Agent 完成工作时上下文丢失
2. 后台 Agent 的发现结果未传达到主会话
3. 任务可见性差导致重复工作
4. 缺少在 Agent 之间传递信息的结构化方式

核心工具参考

工具	用途	使用时机
TaskList()	列出所有任务及其状态	开始工作时、完成后
TaskGet(id)	获取完整任务详情	开始分配的任务之前
TaskCreate(...)	创建新任务	规划阶段、发现子任务时
TaskUpdate(...)	更新状态/元数据	取得进展、发现问题、完成时

计划文件更新协议（铁律）

当任务属于某个计划文件（.claude/context/plans/*.md）时，负责更新任务标记的是执行 Agent，而不是路由器。

任务开始时：在计划文件中找到任务行，并将 - [ ] 改为 - [~]。

任务完成时：将 - [~] 改为 - [x]，并附上一行结果说明。

工具：对指定行使用 Edit，不要重写整个文件。

时机：在调用 TaskUpdate(completed) 之前更新计划文件。

静默处理：如果计划文件不存在，则静默跳过，不要报错。

# Find the line number
grep -n "task subject keywords" .claude/context/plans/my-plan.md

# Then use Edit to change [ ] → [~] on start, [~] → [x] on complete

反模式：将计划文件更新留给路由器。路由器只能看到已完成的任务，因此必须在执行过程中实时更新计划文件。

---

协议

阶段 1：会话开始（必须执行）

开始任何工作之前，先按顺序执行以下操作：

// Step 1: Check existing tasks
TaskList();

// Step 2: If assigned task exists, read full details
TaskGet({ taskId: '<assigned-id>' });

// Step 3: Claim the task
TaskUpdate({
  taskId: '<assigned-id>',
  status: 'in_progress',
  activeForm: 'Working on <task-subject>',
});

原因：

• 避免重复工作（查看当前正在进行的工作）
• 从任务描述中获取完整上下文
• 向其他 Agent/会话表明工作已开始

阶段 2：工作期间（进度更新）

在以下情况下更新任务：

• 发现重要信息
• 遇到阻碍
• 发现子任务
• 取得重大进展

发现结果更新模式

// When you discover something important
TaskUpdate({
  taskId: 'X',
  description: `ORIGINAL: <original-description>

## Discoveries (${new Date().toISOString().split('T')[0]})
- Found: <what you discovered>
- Files: <relevant files>
- Impact: <why this matters>`,
  metadata: {
    discoveredFiles: ['path/to/file1.ts', 'path/to/file2.ts'],
    discoveries: ['Pattern X found', 'Dependency Y required'],
    lastUpdated: new Date().toISOString(),
  },
});

阻碍更新模式

// When you hit a blocker
TaskUpdate({
  taskId: 'X',
  description: `<existing-description>

## BLOCKED (${new Date().toISOString().split('T')[0]})
- Blocker: <what's blocking>
- Needs: <what's required to unblock>
- Workaround: <possible workaround if any>`,
  metadata: {
    status: 'blocked',
    blocker: 'Description of blocker',
    blockerType: 'dependency|permission|information|external',
    needsFrom: 'user|other-agent|external-system',
  },
});

创建子任务模式

// When you discover subtasks
TaskCreate({
  subject: 'Subtask: <specific-task>',
  description: `Parent: Task #X

## Context
<why this subtask exists>

## Scope
<specific work to be done>

## Acceptance Criteria
- [ ] <criterion 1>
- [ ] <criterion 2>`,
  activeForm: 'Working on <subtask>',
});

// Link to parent
TaskUpdate({
  taskId: '<new-subtask-id>',
  addBlockedBy: ['X'], // This subtask blocks parent completion
});

阶段 3：完成（必须执行）

没有结构化元数据时，绝不要将任务标记为完成：

TaskUpdate({
  taskId: 'X',
  status: 'completed',
  description: `<original-description>

## Completed (${new Date().toISOString().split('T')[0]})
- Summary: <one-line summary of what was done>
- Files modified: <list>
- Tests: <passed/added/none>`,
  metadata: {
    summary: 'Concise summary of completed work',
    filesModified: ['path/to/file1.ts', 'path/to/file2.ts'],
    filesCreated: ['path/to/new.ts'],
    testsAdded: true,
    testsPassing: true,
    outputArtifacts: ['.claude/context/reports/backend/my-report.md'],
    nextSteps: ['Optional follow-up', 'Another consideration'],
    completedAt: new Date().toISOString(),
  },
});

// Check for newly unblocked tasks
TaskList();

阶段 4：会话结束/交接

结束会话前，如仍有未完成的工作，请执行以下操作：

// Update all in-progress tasks with current state
TaskUpdate({
  taskId: 'X',
  description: `<existing-description>

## Session Paused (${new Date().toISOString().split('T')[0]})
- Progress: <what was accomplished>
- Current state: <where things stand>
- Next step: <immediate next action>
- Files to review: <key files>`,
  metadata: {
    sessionPaused: true,
    progress: '60%',
    currentState: 'Description of current state',
    immediateNextStep: 'The very next thing to do',
    keyFiles: ['file1.ts', 'file2.ts'],
    keyDecisions: ['Decision 1', 'Decision 2'],
    pausedAt: new Date().toISOString(),
  },
});

上下文交接结构

交接元数据架构

在 Agent 之间交接上下文时，使用以下一致的结构：

interface TaskHandoffMetadata {
  // Progress tracking
  status?: 'not_started' | 'in_progress' | 'blocked' | 'completed';
  progress?: string; // e.g., "60%", "3/5 steps"

  // Discovery context
  discoveredFiles?: string[];
  discoveries?: string[];
  patterns?: string[];

  // Blocker information
  blocker?: string;
  blockerType?: 'dependency' | 'permission' | 'information' | 'external';
  needsFrom?: string;

  // Completion context
  summary?: string;
  filesModified?: string[];
  filesCreated?: string[];
  outputArtifacts?: string[];

  // Continuation context
  currentState?: string;
  immediateNextStep?: string;
  keyFiles?: string[];
  keyDecisions?: string[];

  // Timestamps
  lastUpdated?: string;
  completedAt?: string;
  pausedAt?: string;
}

读取交接上下文

开始处理其他 Agent 已经处理过的任务时：

// Get full task details including metadata
const task = TaskGet({ taskId: 'X' });

// Check metadata for context
if (task.metadata?.sessionPaused) {
  // Previous session paused - read currentState and immediateNextStep
}
if (task.metadata?.discoveries) {
  // Previous agent found things - review discoveries array
}
if (task.metadata?.blocker) {
  // Task was blocked - check if blocker is resolved
}

跨会话协作

环境变量：CLAUDE_CODE_TASK_LIST_ID

使用此环境变量在多个会话之间共享任务列表：

# Set shared task list for all sessions
export CLAUDE_CODE_TASK_LIST_ID="my-project-tasks"

# Start claude code - will use shared task list
claude

适用场景：

• 多个终端处理同一个项目
• 需要共享任务状态的后台 Agent
• 团队协作管理任务列表

共享任务列表模式

// Session A creates task
TaskCreate({
  subject: 'Implement feature X',
  description: '...',
  metadata: {
    owner: 'session-a',
    priority: 'high',
  },
});

// Session B (same CLAUDE_CODE_TASK_LIST_ID) picks up task
TaskList(); // Sees task from Session A
TaskUpdate({
  taskId: '1',
  status: 'in_progress',
  metadata: {
    owner: 'session-b', // Claims ownership
    previousOwner: 'session-a',
  },
});

铁律（必须遵守）

1. 完成任务时必须附上摘要

// WRONG - No context for future reference
TaskUpdate({ taskId: 'X', status: 'completed' });

// CORRECT - Full context preserved
TaskUpdate({
  taskId: 'X',
  status: 'completed',
  metadata: {
    summary: 'Added auth middleware with JWT validation',
    filesModified: ['src/middleware/auth.ts'],
    completedAt: new Date().toISOString(),
  },
});

2. 发现问题时必须更新

// WRONG - Discoveries lost
// ... agent finds important pattern but doesn't record it ...

// CORRECT - Discoveries preserved
TaskUpdate({
  taskId: 'X',
  metadata: {
    discoveries: [...existingDiscoveries, 'Found circular dependency in module X'],
  },
});

3. 完成任务后必须调用 TaskList

// WRONG - May have unblocked other tasks
TaskUpdate({ taskId: "X", status: "completed" });
// ... session ends ...

// CORRECT - Check for follow-up work
TaskUpdate({ taskId: "X", status: "completed", metadata: {...} });
TaskList();  // Find newly unblocked tasks

4. 使用元数据组织结构，使用描述撰写说明

// WRONG - Structured data in prose
TaskUpdate({
  taskId: 'X',
  description: 'Files: a.ts, b.ts. Blocked by: auth issue. Progress: 50%',
});

// CORRECT - Structured metadata + prose description
TaskUpdate({
  taskId: 'X',
  description: 'Implementing auth flow. Hit a blocker with token refresh.',
  metadata: {
    filesModified: ['a.ts', 'b.ts'],
    blocker: 'auth issue',
    progress: '50%',
  },
});

与 Memory Protocol 集成

任务元数据是对 Memory Protocol 的补充，但不能取代它：

信息类型	任务元数据	Memory 文件
特定于任务的发现	是	否
项目级模式	仅供参考	是（learnings.md）
架构决策	仅供参考	是（decisions.md）
阻塞问题	是	是（issues.md）
进度状态	是	否
完成摘要	是	是（learnings.md）

模式：

1. 在任务元数据中记录特定于任务的上下文
2. 在 memory 文件中记录项目级经验
3. 在两者之间交叉引用

// Task completion with memory reference
TaskUpdate({
  taskId: 'X',
  status: 'completed',
  metadata: {
    summary: 'Implemented auth flow',
    memoryUpdates: ['learnings.md: JWT refresh pattern', 'decisions.md: ADR-005 auth architecture'],
  },
});

示例

示例 1：开发者 Agent 完成功能

// Start
TaskList();
TaskGet({ taskId: '5' });
TaskUpdate({ taskId: '5', status: 'in_progress', activeForm: 'Implementing login flow' });

// Discovery during work
TaskUpdate({
  taskId: '5',
  metadata: {
    discoveries: ['Existing auth module at src/auth/', 'Uses JWT not sessions'],
    keyFiles: ['src/auth/jwt.ts', 'src/middleware/auth.ts'],
  },
});

// Completion
TaskUpdate({
  taskId: '5',
  status: 'completed',
  metadata: {
    summary: 'Added login endpoint with JWT auth',
    filesCreated: ['src/routes/login.ts', 'src/routes/login.test.ts'],
    filesModified: ['src/routes/index.ts'],
    testsAdded: true,
    testsPassing: true,
    completedAt: new Date().toISOString(),
  },
});
TaskList(); // Check for unblocked tasks

示例 2：后台 Agent 交接

// Background agent starting long task
TaskUpdate({
  taskId: '10',
  status: 'in_progress',
  metadata: { runningInBackground: true },
});

// Progress update (multiple during execution)
TaskUpdate({
  taskId: '10',
  metadata: {
    progress: '40%',
    currentState: 'Processed 400/1000 files',
    discoveries: ['Found 12 security issues', '3 critical in auth module'],
  },
});

// Completion - main session can check this
TaskUpdate({
  taskId: '10',
  status: 'completed',
  metadata: {
    summary: 'Security scan complete: 12 issues found (3 critical)',
    outputArtifacts: ['.claude/context/reports/security/security-scan.md'],
    criticalFindings: 3,
    highFindings: 5,
    mediumFindings: 4,
    completedAt: new Date().toISOString(),
  },
});

示例 3：多 Agent 协作

// Planner creates tasks with dependencies
TaskCreate({ subject: 'Design auth system', description: '...', activeForm: 'Designing auth' });
TaskCreate({
  subject: 'Implement auth backend',
  description: '...',
  activeForm: 'Implementing auth',
});
TaskCreate({ subject: 'Add auth tests', description: '...', activeForm: 'Testing auth' });

TaskUpdate({ taskId: '2', addBlockedBy: ['1'] }); // Implementation blocked by design
TaskUpdate({ taskId: '3', addBlockedBy: ['2'] }); // Tests blocked by implementation

// Architect completes design
TaskUpdate({
  taskId: '1',
  status: 'completed',
  metadata: {
    summary: 'Auth design complete - JWT with refresh tokens',
    outputArtifacts: ['.claude/context/plans/auth-design.md'],
    keyDecisions: ['JWT over sessions', 'Redis for token store'],
  },
});

// Developer can now start (task 2 unblocked)
TaskList(); // Shows task 2 now available
TaskGet({ taskId: '2' }); // Gets design context from task 1's metadata

相关技能

• session-handoff - 创建完整的会话交接文档（适用于复杂交接）
• operational-modes - 在任务执行期间自我调节工具使用
• thinking-tools - 用于验证任务完成质量的检查点

铁律

1. 绝不在没有结构化元数据（summary、filesModified、completedAt）的情况下将任务标记为已完成
2. 始终在开始任何工作前调用 TaskUpdate(in_progress)——未经认领绝不开始
3. 绝不在未调用 TaskList() 检查是否有新解除阻塞的任务时完成工作
4. 始终在发现出现时立即更新任务元数据，而不是事后补记
5. 绝不在描述正文中放置结构化数据——使用 metadata 字段存放机器可读字段

反模式

反模式	失败原因	正确做法
完成时没有摘要元数据	后续 Agent 没有可供继续工作的上下文	始终在完成元数据中包含 summary、filesModified 和 completedAt
工作前跳过 in_progress	任务看似无人认领；会开始重复工作	开始前始终调用 TaskUpdate(in_progress)
完成后不检查 TaskList	新解除阻塞的任务仍然停滞	每次任务完成后始终调用 TaskList()
在描述正文中放置结构化数据	Agent 无法解析；上下文丢失	结构化数据使用 metadata 字段，叙述内容使用 description
缺少发现更新	工作期间积累的上下文会在会话结束时丢失	在发现出现时立即更新元数据，而不是事后补记

Memory Protocol（强制要求）

开始前： 阅读 .claude/context/memory/learnings.md

完成后：

• 发现新的任务模式 -> .claude/context/memory/learnings.md
• 任务工具存在问题 -> .claude/context/memory/issues.md
• 关于任务结构的决策 -> .claude/context/memory/decisions.md

假设任务可能被中断：如果内容不在任务元数据中，就等于没有发生。