/batch 是 Claude Code 里针对大规模代码变更的专用命令，可以在 5-30 个并行 git worktree 上同时执行同一个任务，大幅缩短跨越大型代码库的重构时间。本文是 /batch 的完整实战指南。
/batch 是什么？
/batch 把一个大任务分解成多个并行子任务，每个子任务在独立的 git worktree 里执行，互不干扰。
适用场景：
- 把整个代码库里的 callback 全部改成 async/await
- 为所有 API 端点添加统一的错误处理
- 在所有文件里替换弃用的 API 调用
- 批量添加 JSDoc 注释
- 全库 lint 规则应用
不适用场景：
- 跨文件有强依赖的变更（需要按顺序执行）
- 变更会互相冲突的情况
- 单个文件的修改
基础用法
/batch 把 src/ 目录下所有 .js 文件里的 var 声明改为 const 或 let
Claude Code 会：
- 分析任务，确定可以并行的范围
- 创建 5-30 个 git worktree（数量由 Claude 根据任务规模决定）
- 在每个 worktree 里运行独立的 Claude 实例执行子任务
- 完成后汇总所有变更，你可以一次性审查全部 diff
实战示例
示例 1：全库 async/await 迁移
/batch 把 src/ 下所有使用 .then().catch() 链式调用的代码改为 async/await 语法，
保持功能不变，错误处理方式不变
执行过程：
- Claude 扫描 src/ 目录，找到所有包含
.then(的文件 - 按模块分组（auth/api/utils/models 等）
- 创建对应数量的 worktree
- 并行处理
完成后审查：
/diff # 查看所有 worktree 里的变更合并 diff
示例 2：统一错误处理格式
/batch 所有 try-catch 块里的 catch(e) 改为 catch(error)，
所有 console.error(e) 改为 console.error(error)，
在 src/services/ 和 src/controllers/ 目录里执行
示例 3：添加统一的 API 响应格式
/batch 在所有 Express 路由文件里，把 res.json({})
替换为 res.json({ success: true, data: {} }) 格式，
错误响应替换为 res.json({ success: false, error: message }) 格式，
目录范围：src/routes/
示例 4：批量添加 TypeScript 类型注解
/batch 为 src/utils/ 目录下所有函数添加 TypeScript 类型注解，
根据使用方式推断参数类型和返回类型，
不改变函数的实现逻辑
/batch 和 /worktree 的区别
| 功能 | /batch | git worktree（手动） |
|---|---|---|
| 创建 worktree | 自动 | 手动 |
| 任务分配 | Claude 自动分解 | 手动指定每个 worktree |
| 并行度 | 5-30 个 | 你创建多少个就多少个 |
| 适合场景 | 同质化大规模变更 | 不同功能并行开发 |
| 结果汇总 | 自动 | 手动合并 |
与 /batch 配合的最佳实践
提交前完整审查
bash
# 查看所有 batch 变更的汇总 diff
/diff
# 或在终端里
git diff main --stat # 变更文件统计
git diff main # 完整 diff写好测试再 /batch
1. 先写好测试，确保现有功能全部测试覆盖
2. 运行 /batch 执行变更
3. 运行完整测试套件验证变更不破坏现有功能
4. 如果测试失败，Claude 会在对应 worktree 里调试修复
限制 /batch 的范围
太大的范围可能导致变更冲突或超时。推荐策略：
- 指定具体目录（
src/services/而非整个src/） - 指定文件类型（
**/*.ts而非所有文件） - 分批执行（先改 services 层，确认没问题再改 controllers 层）
全局 Hooks + /batch 配合
在 /batch 执行时，Hooks 会在每个 worktree 里独立触发：
json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "npm run lint --fix 2>/dev/null || true"
}
]
}
]
}
}每个并行 worktree 里的文件修改都会触发 lint，确保 batch 执行结果符合代码规范。
大规模变更的风险控制
1. 创建 batch 前打标签
bash
git tag pre-batch-$(date +%Y%m%d-%H%M%S)如果 batch 结果不满意，可以快速恢复：
bash
git checkout pre-batch-20260506-1415222. 先在小范围测试
# 先在一个小目录测试
/batch 把 src/utils/ 下的 var 改为 const
# 确认结果正确后，再扩大范围
/batch 把 src/ 下所有文件的 var 改为 const
3. 结合 Code Review
batch 完成后运行 /ultrareview 做并行审查：
/ultrareview # 云端多 Agent 并行审查 batch 的所有变更
/loop 命令：定期重复任务
相关命令 /loop 让 Claude Code 定期重复执行某个任务：
bash
# 每 30 分钟检查一次是否有新的 lint 错误
/loop 30m 运行 lint 检查，有错误就报告
# 每小时运行一次完整测试套件
/loop 1h 运行完整测试套件，记录失败的测试
# 省略间隔时，Claude 自动根据任务类型决定频率
/loop 监控 logs/error.log，有新错误就分析原因/loop 特别适合：
- 监控长时间运行的进程
- 定期检查 CI 状态
- 在等待外部服务时定期轮询
来源：Claude Code 官方文档 - /batch 命令 | computingforgeeks.com | 整理：ClaudeEagle