命令字典
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
并行编排大规模代码库变更和提交
/batch <instruction>/batch 是 Claude Code 内置的一个 Skill（不是独立的编排原语）。它接受一条自然语言变更描述，将整个工作拆解为 5 到 30 个相互独立的单元，在每个单元的独立 git worktree 中各启动一个 background subagent，最终每个 agent 各自开一个 Pull Request。
官方文档原文（code.claude.com/docs/en/agents）：
/batchis a skill that has Claude split one large change into 5 to 30 worktree-isolated subagents that each open a pull request. It's a packaged use of subagents and worktrees, not a separate coordination style.
这意味着 /batch 不能与 agent view、agent teams 或 dynamic workflows 并列为同级协调机制——它本质上是 subagents + worktrees 的封装快捷方式。
/batch <变更描述（自然语言）>
/batch migrate all API calls from axios to fetch
/batch replace all uses of lodash with native equivalents
/batch add JSDoc type annotations to all untyped function parameters
/batch convert class components to functional components with hooks
<变更描述> 是纯自然语言，没有子标志或选项。
orchestrator 进入 plan mode，启动 Explore agents 深入扫描代码库，识别所有目标文件、调用点和变更模式，然后将工作分解为 5–30 个可独立实施的单元，并确定验证要求。规划完成后，呈现计划等待你批准，才继续执行。
你审批后，orchestrator 在同一条消息块中批量启动所有 worker agent，实现真正的并行执行。每个 worker：
/simplify 做质量精简gh pr create 提交并推送、开 PRorchestrator 渲染一张状态表，随着各 agent 完成工作而更新（来源原文 "renders a status table updating as agents complete work"）。
/batch 底层依赖 git worktree 机制，以下配置会影响其行为：
.worktreeinclude — 拷贝被 gitignore 的文件fresh worktree 不含 .env、config/secrets.json 等未跟踪文件。在仓库根目录新建 .worktreeinclude（语法同 .gitignore），Claude Code 会在创建每个 worktree 时自动复制匹配的文件：
.env
.env.local
config/secrets.json
此配置对所有 subagent worktree（包括 /batch 启动的 worker）均生效。
worktree.baseRef — 控制分支基点在 settings.json 中配置：
{
"worktree": {
"baseRef": "head"
}
}
| 值 | 行为 |
|---|---|
"fresh"（默认） | 从 origin/HEAD（远端默认分支）检出，保证干净起点 |
"head" | 从当前本地 HEAD 检出，worker 会携带你本地未推送的提交 |
当你的变更依赖本地还未合并的 in-progress 工作时，需要设置为 "head"。
| 约束 | 原因 |
|---|---|
| 必须在 git 仓库中运行 | 每个 worker 依赖独立 git worktree，非 git 目录无法创建 worktree |
| 各单元必须相互独立 | 单元 A 的输出不能是单元 B 的输入；不满足则会产生分支冲突或逻辑错误 |
| 不适合强耦合变更 | 如"文件 A 需要导入文件 B 新建的工具函数"此类依赖链，不能拆分到独立 worktree |
依赖 gh CLI 且已登录 | 每个 worker 通过 gh pr create 开 PR，未安装或未认证 gh 会导致 PR 创建失败 |
| 并行执行乘以 token 消耗 | 官方文档明确："Running several sessions or subagents at once multiplies token usage"，大型任务费用可观 |
来源：code.claude.com/docs/en/agents
| 方式 | 协调者 | Worker 间通信 | 文件隔离 | 适用场景 |
|---|---|---|---|---|
/batch | Claude（固定模式） | 无（各自独立） | git worktree（自动） | 一条大变更拆成多个独立 PR |
| Subagents | Claude（当前会话） | 通过父会话汇报 | 可选（手动指定 worktree） | 侧边任务，结果返回主会话 |
| Agent view | 你 | 无（各自独立汇报给你） | git worktree（自动） | 多个独立任务，手动分派并监控 |
| Agent teams | Claude（lead 角色） | 共享任务列表 + 互发消息 | 无（需手动分区文件） | Claude 自主规划、分配、监督多 worker |
| Dynamic workflows | 脚本（确定性控制流） | 脚本协调 | worktree 可选 | 500+ 文件迁移、结果交叉验证等超大规模任务 |
axios 迁移到 fetch，或从 lodash 迁移到原生 ES，各模块独立 PR 便于逐个 Review非 git 目录无法运行：/batch 强依赖 git worktree。来源原文明确 "/batch requires a git repository. This isn't optional."；非 git 目录下的具体退出行为来源未描述，以实测为准。
单元间存在隐性依赖：orchestrator 在规划阶段可能无法发现所有耦合点，若某个 worker 的变更依赖另一个 worker 尚未合并的代码，后续 PR 在合并时会产生冲突或编译错误。拆分前应确认各单元在逻辑上真正独立。
并行执行成倍放大 token 消耗：官方原文 "Running several sessions or subagents at once multiplies token usage"——同时运行多个 worker 会成倍增加 token 用量，大型迁移任务费用可能远超预期。审批规划时留意 agent 数量。
PR 创建依赖 gh CLI：worker 在最后一步通过 gh pr create 开 PR（来源:claudefa.st）。因此 PR 能否创建取决于 gh 是否已安装并认证;gh 未配置时的具体失败行为来源未描述,以实测为准。
/batch 执行后会在磁盘上留下若干 git worktree 和对应 branch。清理规则（来源：官方 worktrees 文档）：
cleanupPeriodDays（见 settings.json）到期后自动删除git worktree list # 查看所有 worktree
git worktree remove .claude/worktrees/xxx # 删除指定 worktree
git worktree remove --force .claude/worktrees/xxx # 强制删除（含未提交改动）
.claude/worktrees/ 加入 .gitignore，避免 worktree 内容出现在主 checkout 的未跟踪文件列表中/batch 在并行工作流中的定位描述/batch 的规范定义：5–30 个 worktree-isolated subagents，各开一个 PR.worktreeinclude、worktree.baseRef、清理策略gh pr create 调用、git 强制要求新增 bundled slash 命令。