任务管理协议技能Skill task-management-protocol

---

name: 任务管理协议 description: 使用 Claude Code 任务工具进行任务同步、上下文传递和跨会话协调的协议。确保代理正确更新任务发现并实现无缝工作继续。 version: 1.0.0 model: sonnet invoked_by: both user_invocable: true tools: [TaskCreate, TaskList, TaskGet, TaskUpdate, Read, Write] best_practices:

• 会话开始时和完成后始终调用 TaskList()
• 发现信息时立即更新任务描述
• 使用结构化元数据进行上下文传递
• 无总结元数据前切勿标记完成
• 完成工作后检查被阻塞任务 error_handling: strict streaming: supported verified: false lastVerifiedAt: 2026-02-19T05:29:09.098Z

---

任务管理协议

使用 Claude Code 原生任务工具进行任务同步、进度跟踪和代理间上下文传递的标准化协议。

问题陈述

后台代理完成工作但主会话未收到通知。代理未更新任务描述以记录发现。代理或会话间缺乏结构化上下文传递协议。

此技能解决：

1. 会话结束或代理完成时上下文丢失
2. 后台代理发现未传递给主会话
3. 任务可见性差导致重复工作
4. 无结构化方式在代理间传递信息

核心工具参考

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

协议流程

阶段 1：会话开始（强制）

执行任何工作前，执行此序列：

// 步骤 1：检查现有任务
TaskList();

// 步骤 2：如果分配任务存在，读取完整详情
TaskGet({ taskId: '<分配-id>' });

// 步骤 3：声明任务
TaskUpdate({
  taskId: '<分配-id>',
  status: 'in_progress',
  activeForm: '处理 <任务主题>',
});

重要性：

• 防止重复工作（查看已进行任务）
• 从任务描述获取完整上下文
• 向其他代理/会话发出工作开始信号

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

更新任务时机：

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

发现更新模式

// 当发现重要信息时
TaskUpdate({
  taskId: 'X',
  description: `原始：<原始描述>

## 发现 (${new Date().toISOString().split('T')[0]})
- 发现：<发现内容>
- 文件：<相关文件>
- 影响：<重要性说明>`,
  metadata: {
    discoveredFiles: ['路径/到/文件1.ts', '路径/到/文件2.ts'],
    discoveries: ['发现模式 X', '需要依赖 Y'],
    lastUpdated: new Date().toISOString(),
  },
});

阻塞更新模式

// 当遇到阻塞时
TaskUpdate({
  taskId: 'X',
  description: `<现有描述>

## 阻塞 (${new Date().toISOString().split('T')[0]})
- 阻塞点：<阻塞原因>
- 需求：<解决阻塞所需>
- 变通方案：<可能的变通方案>`,
  metadata: {
    status: 'blocked',
    blocker: '阻塞描述',
    blockerType: 'dependency|permission|information|external',
    needsFrom: 'user|other-agent|external-system',
  },
});

子任务创建模式

// 当发现子任务时
TaskCreate({
  subject: '子任务：<具体任务>',
  description: `父任务：任务 #X

## 上下文
<此子任务存在原因>

## 范围
<具体工作内容>

## 验收标准
- [ ] <标准 1>
- [ ] <标准 2>`,
  activeForm: '处理 <子任务>',
});

// 链接到父任务
TaskUpdate({
  taskId: '<新子任务-id>',
  addBlockedBy: ['X'], // 此子任务阻塞父任务完成
});

阶段 3：完成（强制）

无结构化元数据切勿标记任务完成：

TaskUpdate({
  taskId: 'X',
  status: 'completed',
  description: `<原始描述>

## 完成 (${new Date().toISOString().split('T')[0]})
- 总结：<工作单行总结>
- 修改文件：<列表>
- 测试：<通过/添加/无>`,
  metadata: {
    summary: '完成工作的简洁总结',
    filesModified: ['路径/到/文件1.ts', '路径/到/文件2.ts'],
    filesCreated: ['路径/到/新文件.ts'],
    testsAdded: true,
    testsPassing: true,
    outputArtifacts: ['.claude/context/reports/我的报告.md'],
    nextSteps: ['可选后续步骤', '其他考虑'],
    completedAt: new Date().toISOString(),
  },
});

// 检查新解阻塞任务
TaskList();

阶段 4：会话结束 / 传递

在结束包含未完成工作的会话前：

// 更新所有进行中任务状态
TaskUpdate({
  taskId: 'X',
  description: `<现有描述>

## 会话暂停 (${new Date().toISOString().split('T')[0]})
- 进度：<已完成内容>
- 当前状态：<情况概述>
- 下一步：<立即行动>
- 审查文件：<关键文件>`,
  metadata: {
    sessionPaused: true,
    progress: '60%',
    currentState: '当前状态描述',
    immediateNextStep: '下一步行动',
    keyFiles: ['文件1.ts', '文件2.ts'],
    keyDecisions: ['决策 1', '决策 2'],
    pausedAt: new Date().toISOString(),
  },
});

上下文传递结构

传递元数据模式

在代理间使用一致结构传递上下文：

interface TaskHandoffMetadata {
  // 进度跟踪
  status?: 'not_started' | 'in_progress' | 'blocked' | 'completed';
  progress?: string; // 例如，“60%”、“3/5 步骤”

  // 发现上下文
  discoveredFiles?: string[];
  discoveries?: string[];
  patterns?: string[];

  // 阻塞信息
  blocker?: string;
  blockerType?: 'dependency' | 'permission' | 'information' | 'external';
  needsFrom?: string;

  // 完成上下文
  summary?: string;
  filesModified?: string[];
  filesCreated?: string[];
  outputArtifacts?: string[];

  // 延续上下文
  currentState?: string;
  immediateNextStep?: string;
  keyFiles?: string[];
  keyDecisions?: string[];

  // 时间戳
  lastUpdated?: string;
  completedAt?: string;
  pausedAt?: string;
}

读取传递上下文

当开始其他代理处理过的任务时：

// 获取完整任务详情包括元数据
const task = TaskGet({ taskId: 'X' });

// 检查元数据获取上下文
if (task.metadata?.sessionPaused) {
  // 先前会话暂停 – 读取 currentState 和 immediateNextStep
}
if (task.metadata?.discoveries) {
  // 先前代理发现 – 审查 discoveries 数组
}
if (task.metadata?.blocker) {
  // 任务被阻塞 – 检查阻塞是否已解决
}

跨会话协调

环境变量：CLAUDE_CODE_TASK_LIST_ID

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

# 为所有会话设置共享任务列表
export CLAUDE_CODE_TASK_LIST_ID="我的项目任务"

# 启动 claude code – 使用共享任务列表
claude

使用时机：

• 多终端处理同一项目
• 应共享任务状态的后台代理
• 任务列表团队协作

共享任务列表模式

// 会话 A 创建任务
TaskCreate({
  subject: '实现功能 X',
  description: '...',
  metadata: {
    owner: '会话-a',
    priority: 'high',
  },
});

// 会话 B（相同 CLAUDE_CODE_TASK_LIST_ID）接手任务
TaskList(); // 看到会话 A 任务
TaskUpdate({
  taskId: '1',
  status: 'in_progress',
  metadata: {
    owner: '会话-b', // 声明所有权
    previousOwner: '会话-a',
  },
});

铁律（必须遵守）

1. 无总结不完成

// 错误 – 无上下文供未来参考
TaskUpdate({ taskId: 'X', status: 'completed' });

// 正确 – 完整上下文保留
TaskUpdate({
  taskId: 'X',
  status: 'completed',
  metadata: {
    summary: '添加 JWT 验证的身份验证中间件',
    filesModified: ['src/middleware/auth.ts'],
    completedAt: new Date().toISOString(),
  },
});

2. 发现即更新

// 错误 – 发现丢失
// ... 代理发现重要模式但未记录 ...

// 正确 – 发现保留
TaskUpdate({
  taskId: 'X',
  metadata: {
    discoveries: [...现有发现, '发现模块 X 中的循环依赖'],
  },
});

3. 完成即检查任务列表

// 错误 – 可能有解阻塞任务
TaskUpdate({ taskId: "X", status: "completed" });
// ... 会话结束 ...

// 正确 – 检查后续工作
TaskUpdate({ taskId: "X", status: "completed", metadata: {...} });
TaskList();  // 查找新解阻塞任务

4. 元数据用于结构，描述用于叙述

// 错误 – 结构数据混入叙述
TaskUpdate({
  taskId: 'X',
  description: '文件：a.ts, b.ts。阻塞：身份验证问题。进度：50%',
});

// 正确 – 结构元数据 + 叙述描述
TaskUpdate({
  taskId: 'X',
  description: '实施身份验证流程。遇到令牌刷新阻塞。',
  metadata: {
    filesModified: ['a.ts', 'b.ts'],
    blocker: '身份验证问题',
    progress: '50%',
  },
});

与记忆协议集成

任务元数据补充但不替换记忆协议：

信息类型	任务元数据	记忆文件
任务特定发现	是	否
项目全局模式	仅参考	是 (learnings.md)
架构决策	仅参考	是 (decisions.md)
阻塞问题	是	是 (issues.md)
进度状态	是	否
完成总结	是	是 (learnings.md)

模式：

1. 在任务元数据中记录任务特定上下文
2. 在记忆文件中记录项目全局学习
3. 交叉引用

// 任务完成带记忆引用
TaskUpdate({
  taskId: 'X',
  status: 'completed',
  metadata: {
    summary: '实施身份验证流程',
    memoryUpdates: ['learnings.md: JWT 刷新模式', 'decisions.md: ADR-005 身份验证架构'],
  },
});

示例

示例 1：开发者代理完成功能

// 开始
TaskList();
TaskGet({ taskId: '5' });
TaskUpdate({ taskId: '5', status: 'in_progress', activeForm: '实施登录流程' });

// 工作期间发现
TaskUpdate({
  taskId: '5',
  metadata: {
    discoveries: ['现有身份验证模块位于 src/auth/', '使用 JWT 非会话'],
    keyFiles: ['src/auth/jwt.ts', 'src/middleware/auth.ts'],
  },
});

// 完成
TaskUpdate({
  taskId: '5',
  status: 'completed',
  metadata: {
    summary: '添加带 JWT 身份验证的登录端点',
    filesCreated: ['src/routes/login.ts', 'src/routes/login.test.ts'],
    filesModified: ['src/routes/index.ts'],
    testsAdded: true,
    testsPassing: true,
    completedAt: new Date().toISOString(),
  },
});
TaskList(); // 检查解阻塞任务

示例 2：后台代理带传递

// 后台代理开始长任务
TaskUpdate({
  taskId: '10',
  status: 'in_progress',
  metadata: { runningInBackground: true },
});

// 进度更新（执行期间多次）
TaskUpdate({
  taskId: '10',
  metadata: {
    progress: '40%',
    currentState: '处理 400/1000 文件',
    discoveries: ['发现 12 个安全问题', '3 个关键在身份验证模块'],
  },
});

// 完成 – 主会话可检查
TaskUpdate({
  taskId: '10',
  status: 'completed',
  metadata: {
    summary: '安全扫描完成：发现 12 个问题（3 个关键）',
    outputArtifacts: ['.claude/context/reports/security-scan.md'],
    criticalFindings: 3,
    highFindings: 5,
    mediumFindings: 4,
    completedAt: new Date().toISOString(),
  },
});

示例 3：多代理协调

// 规划者创建带依赖任务
TaskCreate({ subject: '设计身份验证系统', description: '...', activeForm: '设计身份验证' });
TaskCreate({
  subject: '实现身份验证后端',
  description: '...',
  activeForm: '实现身份验证',
});
TaskCreate({ subject: '添加身份验证测试', description: '...', activeForm: '测试身份验证' });

TaskUpdate({ taskId: '2', addBlockedBy: ['1'] }); // 实现阻塞于设计
TaskUpdate({ taskId: '3', addBlockedBy: ['2'] }); // 测试阻塞于实现

// 架构师完成设计
TaskUpdate({
  taskId: '1',
  status: 'completed',
  metadata: {
    summary: '身份验证设计完成 – JWT 带刷新令牌',
    outputArtifacts: ['.claude/context/plans/auth-design.md'],
    keyDecisions: ['JWT 优于会话', 'Redis 用于令牌存储'],
  },
});

// 开发者可开始（任务 2 解阻塞）
TaskList(); // 显示任务 2 可用
TaskGet({ taskId: '2' }); // 从任务 1 元数据获取设计上下文

相关技能

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

记忆协议（强制）

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

完成后：

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

假设中断：如果未记录在任务元数据中，则视为未发生。