claude-delegate

Claude Delegate

你是协调者。将一项范围明确的编码任务委派给单独的实现者——一个 Claude Code CLI 会话——然后审查其成果并由你亲自提交。你编写任务说明并负责判断；单独的 Claude 会话修改工作树；你负责验证并提交。

此技能并不表示当前 Claude 应直接实现任务。只有在人类明确要求委派给另一个 Claude Code 进程或会话后，才使用此技能。

何时不要使用

• 人类要求当前 Agent 直接实现任务。
• 任务小到可以直接完成，且人类没有要求委派。
• 缺少 claude CLI，或该 CLI 未通过身份验证（claude auth status）。
• 任务需要比 Claude Code 的工具权限和仅限 shell 的沙箱更强的主机隔离。对此要求，请使用隔离容器或虚拟机。

前提条件

1. claude --version 成功运行。
2. claude auth status 显示会话已通过身份验证。在 macOS 上，当前凭据保存在登录 Keychain 中；如果协调者自己的沙箱阻止访问 Keychain（Codex 的沙箱会这样），claude 会改用可能已过期的凭据文件，并报告 loggedIn: false，即使登录仍然有效。下结论认定 CLI 未通过身份验证之前，请在提升沙箱权限或沙箱外重新运行检查，并重新执行派发。
3. 目标仓库是通过 --cd 传入的目录。
4. 在 Linux/WSL2 上，已安装 Claude 的沙箱依赖。常规中继配置文件在沙箱不可用时会报错，而不会悄悄在无沙箱状态下运行 shell 命令。现有的合并设置仍可能影响实际生效的隔离边界。

工作流程

1. 编写任务说明

单独的会话没有协调者的聊天记录。它会通过 stdin 接收任务说明，并可检查目标工作树。

Claude Code 会自动发现目标项目的 CLAUDE.md 和常规本地 Claude 配置，因为中继不会使用 --bare。它不会通用地自动加载 AGENTS.md。请自行阅读 AGENTS.md，并将所有关键约束和实际的检查命令复制到任务说明中。告知实现者不要提交代码。每份任务说明只包含一项任务。

模板和详情：references/writing-the-brief.md。

2. 派发

对于由 Codex 协调的后台工作，请先安装并配置独立的 codex-background 支持工具。如果缺少其 MCP 工具或注册表，请停止并报告设置要求；不要悄悄改用由模型驱动的轮询。然后调用其已注册的 delegate_run MCP 工具，取代下面的 shell 示例。 遵循该技能中的结构化通用参数、保持提供程序标志不变以及按 runId 重新连接的说明。保持请求待处理状态，直到任务完成，然后继续执行本技能中的审查和提交步骤。其他协调者继续使用下面的 shell 工作流程。

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# review/diagnosis only:                 add --read-only
# continue the latest session:           add --resume-last
# continue the recorded session:         add --session <id>
# choose limits:                         add --max-turns 40 --max-budget-usd 10
# set the auto-compact window:           add --autocompact 400k
# hard relay deadline:                   add --timeout 2h
# inspect every option:                  node .../relay.mjs --help

<skill-dir> 是此技能的安装目录，即包含此 SKILL.md 的文件夹。

中继运行 claude -p --output-format stream-json --verbose，通过 stdin 发送任务说明，并默认将产物写入系统临时目录。它不会使用 --bg 或 --bare，也不会提交代码。请参阅 references/dispatch-and-poll.md。

--autocompact <auto|tokens> 会在每次新建或恢复调用时传递 Claude Code 的自动压缩窗口设置，并且需要 Claude Code 2.1.221 或更高版本——较旧的版本会因 unknown option '--autocompact' 而导致派发失败。可接受的取值范围由已安装的 CLI 决定（auto 或 100k–1M tokens）；中继会记录请求的值，但不会声称 Claude 已应用或强制执行该设置。

3. 等待

使用 codex-background 的 Codex 会让原始 MCP 请求保持待处理状态：不会由模型驱动休眠、 状态轮询或日志轮询。只有在请求中断后重新连接时，才使用 delegate_wait。

中继会阻塞，直到 Claude 退出。使用编排器的后台命令功能，或在前台运行并等待。完成意味着 进程已退出，且 result.json 已存在。

• 运行前用法错误会以代码 2 退出，且不会写入 result.json。
• 找不到 claude 时会以代码 127 退出，并写入 status: "claude_unavailable"。
• 超时和捕获到的中继信号会终止整个实现者进程树，并保留结果文件。

读取 result.json 中的 finalMessage、touchedFiles、resultSubtype 和原始产物路径。

4. 审查

将实现者的报告和门禁结果视为未经证实的说法：

• 绿色门禁结果并不意味着一切无误；先审查对现有测试的修改。
• 亲自重新运行项目的实际门禁。
• 根据简报检查完整差异，从 touchedFiles 开始。
• 除常规差异外，也检查未跟踪和已暂存的内容。
• 如果已安装相关守护技能，请运行它们。

完整清单：references/review-and-land.md。

5. 合并

只有在门禁通过且差异检查无误后，编排器才会提交。如需返工，请使用增量简报恢复同一个 Claude 会话：

echo "Keep the implementation, replace the mocked DB test with the migrated fixture, and remove the
unused import." | node "<skill-dir>/scripts/relay.mjs" --session <id> --cd /path/to/repo

对恢复后的运行进行审查，流程与首次运行完全相同。

权限配置

常规配置刻意采用明确限制：

• 使用 acceptEdits 权限模式。
• 内置工具仅限 Read、Glob、Grep、Edit、Write 和平台 shell。
• 在 macOS、Linux 和 WSL2 上，启用 Claude 的 shell 沙盒；若缺少依赖则启动失败，且不会重试非沙盒模式。保持在沙盒中的命令会自动获批，因此常规门禁可在无交互的情况下运行。沙盒仅约束 shell 进程及其子进程；合并后的本地或受管理沙盒设置可能会添加有效路径或排除项。
• 禁用已配置的 MCP 发现和 Claude.ai 连接器，拒绝所有 MCP 工具，并禁止子进程使用技能、命令和 Claude 的 Agent 工具。项目 CLAUDE.md、钩子、常规身份验证、会话持久化和其他本地设置仍会加载。
• 字符串规则会拒绝常见的直接 shell 命令形式 git commit、git push 和嵌套的 claude，以及任何包含 claude-delegate 的命令。别名、脚本和包装器可以绕过这些规则，因此它们只能增加操作阻力；简报中的禁止提交说明和编排器审查才是真正的边界。

原生 Windows 不支持 Claude 的 shell 沙盒。中继会限制工具范围，并预先批准 PowerShell，让运行保持非交互状态，但该 shell 不受操作系统隔离。已实现原生 claude.exe 和 npm claude.cmd 启动路径。claude.cmd 路径已有记录在案的原生 Windows 运行结果（见 README 的验证状态）；直接启动的 claude.exe 尚未验证。

--read-only 使用 plan 模式，仅允许 Read、Glob 和 Grep。它会移除编辑、写入和 shell 路径，然后比较解析后的 git porcelain，并为此前已修改的 Git 可见路径记录工作树身份和索引条目的指纹。 如果任一信号证实发生了更改，readOnlyViolation 为 true；如果覆盖完整且未检测到更改，则为 false；如果覆盖不完整，则为 null。这是一种用于报告的触发机制，并非操作系统边界：忽略的路径和完美还原不在其检测范围内，本地钩子仍可写入，并且无法将并发更改归因于 Claude。

--dangerously-skip-permissions 是明确选择启用 Claude bypassPermissions 模式。受限的工具范围、直接提交和推送的拒绝规则以及受支持平台上的 shell 沙盒仍然有效，但直接文件工具可以越过常规权限边界。仅在用户明确接受后使用。

与 Claude 原生功能互补

当当前 Claude 环境已经充当编排器，且目标是使用原生协调功能时，Claude 子 Agent、Agent 团队和后台会话都很有用。这项技能与之互补：它提供一套跨编排器契约——自包含简报 → 分派 → 产物 → 审查 → 合并——并让编排器保留提交操作。

参考资料

• references/writing-the-brief.md — 上下文、CLAUDE.md 与 AGENTS.md 的区别、实际门禁、报告契约和增量简报。
• references/dispatch-and-poll.md — 标志、配置、产物、result.json、轮询和故障恢复。
• references/review-and-land.md — 生成代码审查、提交边界和会话返工。
• references/multi-task-queues.md — 顺序队列、进度跟踪、约束延续和最终一致性。