claude-task-master 批量清理子任务指南clear-subtasks 命令的完整实战解析【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master导读clear-subtasks是 claude-task-master 提供的批量子任务清理命令用于一次性删除某个父任务或整个项目下的全部子任务。本指南以其命令文档 remove-subtasks.md 为骨架结合 CLI 命令注册、核心实现 clear-subtasks.js 与 MCP 工具实现完整讲解该命令的参数用法、执行流程、安全确认机制、异常边界与底层原理。读完本文你将掌握在 Claude Code、Cursor、Roo 等 AI 编程工具中安全地批量清理子任务并在清理后正确维护父任务与项目结构的完整方法。命令概览什么时候使用 clear-subtasks在 claude-task-master 的任务模型中一个父任务可以携带一组带编号的子任务如#5.1、#5.2用于细化复杂工作的拆解。当任务的分解方案需要整体推翻、重新规划或父任务范围大幅收缩时逐条执行remove-subtask效率过低此时应使用clear-subtasks一次性清空指定父任务的全部子任务。与之对应仓库还提供了两个相关的命令文档remove-subtask.md按 ID 删除单个子任务支持--convert将其转回独立任务remove-all-subtasks.md清理全项目所有父任务的子任务对应--all全局模式。三者的关系是remove-subtask是精确手术刀clear-subtasks是批量清理单个任务的分支clear-subtasks --all则是全局级的破坏性操作。命令参数与用法clear-subtasks在 CLI 层的完整参数定义位于 commands.js# 清除单个任务的子任务 task-master clear-subtasks --idtask-id # 一次性清除多个任务的子任务逗号分隔 task-master clear-subtasks --id1,2,3 # 清除所有任务的子任务全局模式需谨慎 task-master clear-subtasks --all参数说明默认值-f, --file file指向任务文件的路径tasks/tasks.json即TASKMASTER_TASKS_FILE-i, --id ids要清除子任务的任务 ID支持逗号分隔的多个 ID无--all清除所有任务的子任务无--tag tag指定任务操作的标签tag上下文当前激活的 tag命令注册代码对参数做了如下校验commands.js当--id与--all都未提供时命令会直接报错退出Error: Please specify task IDs with --idids or use --all to clear all tasks在执行前命令会先初始化 TaskMaster 实例、获取当前 tag 上下文并通过displayCurrentTagIndicator(tag)在终端展示当前所处的 tag确保用户清楚本次操作作用在哪个任务集上。若指定了--all会先读取全部任务 ID 拼接成逗号分隔串再统一交给核心清理函数处理。说明命令文档 remove-subtasks.md 中给出的执行示例为task-master clear-subtasks --idtask-id与 command-reference.md 中的官方用法一致且--id支持逗号分隔批量传入。核心实现清理逻辑与执行流程批量清理的核心逻辑位于 scripts/modules/task-manager/clear-subtasks.js 的clearSubtasks函数。其执行流程如下1. 读取任务数据通过readJSON(tasksPath, projectRoot, tag)读取任务文件若数据缺失或没有tasks数组则输出No valid tasks found.并退出对应测试用例 should handle invalid tasks data。随后在非静默模式下输出 Clearing Subtasks 标题横幅boxen 样式。2. 解析任务 ID 并逐任务处理const taskIdArray taskIds.split(,).map((id) id.trim());对每个 ID 依次执行ID 合法性检查parseInt后若为NaN记录Invalid task ID错误并跳过任务存在性检查在data.tasks中查找匹配 ID找不到则记录Task ${id} not found对应测试用例 should handle non-existent task IDs gracefully空子任务检查任务没有subtasks或数组为空时在汇总表中标记为 No subtasks不产生任何写操作对应测试用例 should handle tasks with no subtasks该场景下writeJSON不会被调用执行清理将task.subtasks置为空数组[]累计clearedCount并在汇总表中标记 N subtasks cleared。值得注意的是核心函数对子任务 ID本身不做区分——它直接清空父任务下subtasks数组的全部内容这与按 ID 删除单个子任务的 remove-subtask.md 语义不同。3. 写回与汇总只要存在任一成功清理的任务clearedCount 0就调用writeJSON将更新后的数据写回任务文件并以 cli-table3 渲染汇总表Task IDTask TitleSubtasks Cleared5Implement user authentication4 subtasks cleared随后输出成功提示与下一步建议Next Steps: 1. Run task-master expand --idid to generate new subtasks 2. Run task-master list --with-subtasks to verify changes若没有任何清理发生所有任务都无子任务或都未找到则输出黄色提示 No subtasks were cleared且不会触发任何文件写入——这是一个重要的安全性设计没有变更就不落盘。安全确认文档中的确认交互设计命令文档 remove-subtasks.md 明确要求在批量清理前展示确认信息示意交互如下Clear Subtasks Confirmation ━━━━━━━━━━━━━━━━━━━━━━━━━ Parent Task: #5 Implement user authentication Subtasks to remove: 4 - #5.1 Setup auth framework (done) - #5.2 Create login form (in-progress) - #5.3 Add validation (pending) - #5.4 Write tests (pending) ⚠️ This will permanently delete all subtask data Continue? (y/n)这份确认清单正是文档中Pre-Clear Analysis的落地形态要求清理前回答三个问题子任务摘要Subtask Summary子任务总数、每个子任务的完成状态done / in-progress / pending、已完成的工作量、受影响的依赖关系影响评估Impact Assessment会丢失哪些数据、要移除哪些依赖、对项目时间线的影响、对父任务本身的连带影响确认环节Confirmation Required明确提示这将永久删除所有子任务数据要求用户输入 y/n 后才继续。对于全项目级的清理--allremove-all-subtasks.md 要求双重确认甚至需要用户手动输入短语CLEAR ALL SUBTASKS才能放行可见破坏性越高确认门槛越严。清理过程的标准步骤结合文档的 Process 章节与源码实现一次完整的批量清理应遵循以下步骤列出所有子任务供确认——确认交互中的清单展示检查进行中的工作——识别 in-progress 子任务提示可能丢失的工作量见文档示例中 Warning: Subtask #5.2 is in-progress移除全部子任务——核心函数将subtasks数组置空更新父任务——清理后父任务的估算、状态与复杂度应被重新评估清理依赖关系——删除指向已移除子任务的依赖引用依赖清理在依赖管理模块如 dependency-manager.js 中统一维护。其中第 2 步检查进行中的工作尤为重要文档示例中#5.2处于 in-progress直接清空会丢失其进行中的成果因此需要人工权衡。智能特性与替代方案文档列出的 Smart Features 与 Alternative Options 本质上是一套删除前止损的策略库实际执行时可参考以下组合智能特性说明转换为独立任务将重要子任务提升为顶层任务避免信息丢失清理前备份任务数据导出 / 备份tasks.json或相关子任务数据保留已完成的工作历史对 done 状态的子任务保留记录只清 pending / in-progress合理更新父任务清理后重算父任务的时间估算、复杂度与状态文档建议的替代选项包括将重要子任务转换为独立任务、保留已完成子任务、归档而非删除、先导出子任务数据。其中转换为独立任务在单条场景下由remove-subtask --convert直接支持见 remove-subtask.md批量场景下可先对关键子任务执行转换再对父任务执行清理。清理后的收尾工作文档 Post-Clear 章节要求在清理完成后展示更新后的父任务——确认父任务现在处于干净状态重新计算时间估算——子任务被清空后父任务的累计估算需要更新更新任务复杂度——复杂任务清空子任务后其复杂度评级可能需重新评估可结合analyze-complexity/ complexity-report.md 命令建议后续步骤——CLI 实现中已内置该能力清理成功后自动提示1. Run task-master expand --idid to generate new subtasks 2. Run task-master list --with-subtasks to verify changes即清空后建议用expand重新拆解文档示例中也提示 Suggestion: Consider re-expanding with better breakdown并用list --with-subtasks验证结果。源码级边界行为测试用例验证clear-subtasks.test.js 完整覆盖了该模块的边界行为可作为使用时的行为契约场景预期行为清除单个任务子任务该任务subtasks变为[]文件被写回逗号分隔多 ID如3,4两个任务的子任务均被清空一次写回任务本无子任务不写文件汇总表标记 No subtasks任务 ID 不存在如99记录Task 99 not found错误不写文件混合有效与无效 ID如3,99有效 ID 正常清理并写回无效 ID 记录错误文件读取失败异常向上抛出数据无效无 tasks输出No valid tasks found.并调用process.exit(1)文件写入失败异常向上抛出从测试还能看出一个实现细节所有写回操作都通过writeJSON走统一的 tag 元数据维护路径测试中_rawTaggedData与tag契约被显式断言因此在 tag 场景下清理子任务也能保持多标签数据的完整性。MCP 调用方式与静默模式除 CLI 外clear-subtasks还被封装为 MCP 工具clear_subtasks定义在 mcp-server/src/tools/clear-subtasks.js其 Zod 参数模式为参数类型说明idstring可选逗号分隔的任务 IDallboolean可选是否清除所有任务的子任务filestring可选任务文件绝对路径默认tasks/tasks.jsonprojectRootstring必填项目根目录绝对路径tagstring可选操作的 tag 上下文该工具通过.refine()强制要求id或all至少提供一个并在注解中标记destructiveHint: true让 MCP 客户端在调用前展示破坏性操作提示。其执行体调用 direct-functions/clear-subtasks.js 中的clearSubtasksDirect该封装会先校验tasksJsonPath、id/all、文件存在性等前置条件然后开启静默模式enableSilentMode()调用核心函数以避免终端输出污染 JSON 响应完成后恢复并读取更新后的数据生成结构化摘要tasksCleared、tag返回给调用方。整个过程即便出错也会在finally路径恢复静默模式保证后续日志行为正常。使用建议与注意事项清理前先确认批量清理不可逆务必先执行task-master list --with-subtasks查看受影响子任务的完成状态与依赖区分单删与批量只需删除个别子任务时优先使用remove-subtask可--convert转为独立任务只有整组重构时才使用clear-subtasks--all是高风险操作会清空整个项目所有父任务的子任务请参照 remove-all-subtasks.md 的流程先备份再执行清理后及时重构清空后建议立即用task-master expand --idid重新拆解避免父任务长期处于无子任务的空转状态tag 场景注意上下文命令会默认作用于当前激活 tag跨 tag 操作请显式传--tag以免清错任务集。【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 claude-task-master 批量清理子任务指南：clear-subtasks 命令的完整实战解析
claude-task-master 批量清理子任务指南clear-subtasks 命令的完整实战解析【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master导读clear-subtasks是 claude-task-master 提供的批量子任务清理命令用于一次性删除某个父任务或整个项目下的全部子任务。本指南以其命令文档 remove-subtasks.md 为骨架结合 CLI 命令注册、核心实现 clear-subtasks.js 与 MCP 工具实现完整讲解该命令的参数用法、执行流程、安全确认机制、异常边界与底层原理。读完本文你将掌握在 Claude Code、Cursor、Roo 等 AI 编程工具中安全地批量清理子任务并在清理后正确维护父任务与项目结构的完整方法。命令概览什么时候使用 clear-subtasks在 claude-task-master 的任务模型中一个父任务可以携带一组带编号的子任务如#5.1、#5.2用于细化复杂工作的拆解。当任务的分解方案需要整体推翻、重新规划或父任务范围大幅收缩时逐条执行remove-subtask效率过低此时应使用clear-subtasks一次性清空指定父任务的全部子任务。与之对应仓库还提供了两个相关的命令文档remove-subtask.md按 ID 删除单个子任务支持--convert将其转回独立任务remove-all-subtasks.md清理全项目所有父任务的子任务对应--all全局模式。三者的关系是remove-subtask是精确手术刀clear-subtasks是批量清理单个任务的分支clear-subtasks --all则是全局级的破坏性操作。命令参数与用法clear-subtasks在 CLI 层的完整参数定义位于 commands.js# 清除单个任务的子任务 task-master clear-subtasks --idtask-id # 一次性清除多个任务的子任务逗号分隔 task-master clear-subtasks --id1,2,3 # 清除所有任务的子任务全局模式需谨慎 task-master clear-subtasks --all参数说明默认值-f, --file file指向任务文件的路径tasks/tasks.json即TASKMASTER_TASKS_FILE-i, --id ids要清除子任务的任务 ID支持逗号分隔的多个 ID无--all清除所有任务的子任务无--tag tag指定任务操作的标签tag上下文当前激活的 tag命令注册代码对参数做了如下校验commands.js当--id与--all都未提供时命令会直接报错退出Error: Please specify task IDs with --idids or use --all to clear all tasks在执行前命令会先初始化 TaskMaster 实例、获取当前 tag 上下文并通过displayCurrentTagIndicator(tag)在终端展示当前所处的 tag确保用户清楚本次操作作用在哪个任务集上。若指定了--all会先读取全部任务 ID 拼接成逗号分隔串再统一交给核心清理函数处理。说明命令文档 remove-subtasks.md 中给出的执行示例为task-master clear-subtasks --idtask-id与 command-reference.md 中的官方用法一致且--id支持逗号分隔批量传入。核心实现清理逻辑与执行流程批量清理的核心逻辑位于 scripts/modules/task-manager/clear-subtasks.js 的clearSubtasks函数。其执行流程如下1. 读取任务数据通过readJSON(tasksPath, projectRoot, tag)读取任务文件若数据缺失或没有tasks数组则输出No valid tasks found.并退出对应测试用例 should handle invalid tasks data。随后在非静默模式下输出 Clearing Subtasks 标题横幅boxen 样式。2. 解析任务 ID 并逐任务处理const taskIdArray taskIds.split(,).map((id) id.trim());对每个 ID 依次执行ID 合法性检查parseInt后若为NaN记录Invalid task ID错误并跳过任务存在性检查在data.tasks中查找匹配 ID找不到则记录Task ${id} not found对应测试用例 should handle non-existent task IDs gracefully空子任务检查任务没有subtasks或数组为空时在汇总表中标记为 No subtasks不产生任何写操作对应测试用例 should handle tasks with no subtasks该场景下writeJSON不会被调用执行清理将task.subtasks置为空数组[]累计clearedCount并在汇总表中标记 N subtasks cleared。值得注意的是核心函数对子任务 ID本身不做区分——它直接清空父任务下subtasks数组的全部内容这与按 ID 删除单个子任务的 remove-subtask.md 语义不同。3. 写回与汇总只要存在任一成功清理的任务clearedCount 0就调用writeJSON将更新后的数据写回任务文件并以 cli-table3 渲染汇总表Task IDTask TitleSubtasks Cleared5Implement user authentication4 subtasks cleared随后输出成功提示与下一步建议Next Steps: 1. Run task-master expand --idid to generate new subtasks 2. Run task-master list --with-subtasks to verify changes若没有任何清理发生所有任务都无子任务或都未找到则输出黄色提示 No subtasks were cleared且不会触发任何文件写入——这是一个重要的安全性设计没有变更就不落盘。安全确认文档中的确认交互设计命令文档 remove-subtasks.md 明确要求在批量清理前展示确认信息示意交互如下Clear Subtasks Confirmation ━━━━━━━━━━━━━━━━━━━━━━━━━ Parent Task: #5 Implement user authentication Subtasks to remove: 4 - #5.1 Setup auth framework (done) - #5.2 Create login form (in-progress) - #5.3 Add validation (pending) - #5.4 Write tests (pending) ⚠️ This will permanently delete all subtask data Continue? (y/n)这份确认清单正是文档中Pre-Clear Analysis的落地形态要求清理前回答三个问题子任务摘要Subtask Summary子任务总数、每个子任务的完成状态done / in-progress / pending、已完成的工作量、受影响的依赖关系影响评估Impact Assessment会丢失哪些数据、要移除哪些依赖、对项目时间线的影响、对父任务本身的连带影响确认环节Confirmation Required明确提示这将永久删除所有子任务数据要求用户输入 y/n 后才继续。对于全项目级的清理--allremove-all-subtasks.md 要求双重确认甚至需要用户手动输入短语CLEAR ALL SUBTASKS才能放行可见破坏性越高确认门槛越严。清理过程的标准步骤结合文档的 Process 章节与源码实现一次完整的批量清理应遵循以下步骤列出所有子任务供确认——确认交互中的清单展示检查进行中的工作——识别 in-progress 子任务提示可能丢失的工作量见文档示例中 Warning: Subtask #5.2 is in-progress移除全部子任务——核心函数将subtasks数组置空更新父任务——清理后父任务的估算、状态与复杂度应被重新评估清理依赖关系——删除指向已移除子任务的依赖引用依赖清理在依赖管理模块如 dependency-manager.js 中统一维护。其中第 2 步检查进行中的工作尤为重要文档示例中#5.2处于 in-progress直接清空会丢失其进行中的成果因此需要人工权衡。智能特性与替代方案文档列出的 Smart Features 与 Alternative Options 本质上是一套删除前止损的策略库实际执行时可参考以下组合智能特性说明转换为独立任务将重要子任务提升为顶层任务避免信息丢失清理前备份任务数据导出 / 备份tasks.json或相关子任务数据保留已完成的工作历史对 done 状态的子任务保留记录只清 pending / in-progress合理更新父任务清理后重算父任务的时间估算、复杂度与状态文档建议的替代选项包括将重要子任务转换为独立任务、保留已完成子任务、归档而非删除、先导出子任务数据。其中转换为独立任务在单条场景下由remove-subtask --convert直接支持见 remove-subtask.md批量场景下可先对关键子任务执行转换再对父任务执行清理。清理后的收尾工作文档 Post-Clear 章节要求在清理完成后展示更新后的父任务——确认父任务现在处于干净状态重新计算时间估算——子任务被清空后父任务的累计估算需要更新更新任务复杂度——复杂任务清空子任务后其复杂度评级可能需重新评估可结合analyze-complexity/ complexity-report.md 命令建议后续步骤——CLI 实现中已内置该能力清理成功后自动提示1. Run task-master expand --idid to generate new subtasks 2. Run task-master list --with-subtasks to verify changes即清空后建议用expand重新拆解文档示例中也提示 Suggestion: Consider re-expanding with better breakdown并用list --with-subtasks验证结果。源码级边界行为测试用例验证clear-subtasks.test.js 完整覆盖了该模块的边界行为可作为使用时的行为契约场景预期行为清除单个任务子任务该任务subtasks变为[]文件被写回逗号分隔多 ID如3,4两个任务的子任务均被清空一次写回任务本无子任务不写文件汇总表标记 No subtasks任务 ID 不存在如99记录Task 99 not found错误不写文件混合有效与无效 ID如3,99有效 ID 正常清理并写回无效 ID 记录错误文件读取失败异常向上抛出数据无效无 tasks输出No valid tasks found.并调用process.exit(1)文件写入失败异常向上抛出从测试还能看出一个实现细节所有写回操作都通过writeJSON走统一的 tag 元数据维护路径测试中_rawTaggedData与tag契约被显式断言因此在 tag 场景下清理子任务也能保持多标签数据的完整性。MCP 调用方式与静默模式除 CLI 外clear-subtasks还被封装为 MCP 工具clear_subtasks定义在 mcp-server/src/tools/clear-subtasks.js其 Zod 参数模式为参数类型说明idstring可选逗号分隔的任务 IDallboolean可选是否清除所有任务的子任务filestring可选任务文件绝对路径默认tasks/tasks.jsonprojectRootstring必填项目根目录绝对路径tagstring可选操作的 tag 上下文该工具通过.refine()强制要求id或all至少提供一个并在注解中标记destructiveHint: true让 MCP 客户端在调用前展示破坏性操作提示。其执行体调用 direct-functions/clear-subtasks.js 中的clearSubtasksDirect该封装会先校验tasksJsonPath、id/all、文件存在性等前置条件然后开启静默模式enableSilentMode()调用核心函数以避免终端输出污染 JSON 响应完成后恢复并读取更新后的数据生成结构化摘要tasksCleared、tag返回给调用方。整个过程即便出错也会在finally路径恢复静默模式保证后续日志行为正常。使用建议与注意事项清理前先确认批量清理不可逆务必先执行task-master list --with-subtasks查看受影响子任务的完成状态与依赖区分单删与批量只需删除个别子任务时优先使用remove-subtask可--convert转为独立任务只有整组重构时才使用clear-subtasks--all是高风险操作会清空整个项目所有父任务的子任务请参照 remove-all-subtasks.md 的流程先备份再执行清理后及时重构清空后建议立即用task-master expand --idid重新拆解避免父任务长期处于无子任务的空转状态tag 场景注意上下文命令会默认作用于当前激活 tag跨 tag 操作请显式传--tag以免清错任务集。【免费下载链接】claude-task-masterAn AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-task-master创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考