用途
claude-delegate 用于在用户明确要求时,将一项有边界的编码任务委派给独立的实现者——一个 Claude Code CLI 会话,然后由编排者审查其产出并自行落地提交。编排者负责编写任务简报并承担判断责任;独立的 Claude 会话编辑工作树;编排者负责验证与提交。
该技能不是让当前 Claude 直接实现的信号。只有在人类明确要求委派给另一个 Claude Code 进程或会话后才使用。
何时不使用
- 人类要求当前智能体直接实现任务。
- 任务足够小,可以内联完成,且人类未要求委派。
- claude CLI 缺失或未认证(claude auth status)。
- 任务需要比 Claude Code 的工具权限和仅 shell 沙箱更强的宿主边界。此类需求应使用隔离容器或虚拟机。
前置条件
- claude --version 成功。
- claude auth status 报告已认证会话。如果编排者无法访问凭据存储,应报告该边界并使用经批准的隔离环境;不要自动禁用或提升其沙箱以获取凭据。
- 目标仓库是通过 --cd 传入的目录。
- 在 Linux/WSL2 上,Claude 的沙箱依赖已安装。正常 relay 配置在沙箱不可用时失败,而不是静默地以无沙箱方式运行 shell 命令。已合并的设置仍可能影响实际边界。
工作循环
1. 编写简报
独立会话没有编排者的聊天历史。它通过 stdin 接收简报,并可检查目标工作树。
Claude Code 会自动发现目标项目的 CLAUDE.md 和常规本地 Claude 配置,因为 relay 不使用 --bare。它不会通用地自动加载 AGENTS.md。编排者需自行阅读 AGENTS.md,并将每条关键约束和真实门禁命令复制到简报中。告知实现者不要提交。每份简报只包含一个任务。
模板与细节见 references/writing-the-brief.md。
2. 派发
该分发为纯文档:scripts/relay.mjs 不存在。以下命令需要另行获取、固定版本并经过审查的上游运行时。不要声称这些配置由已安装的文档强制执行,也不要运行缺失的本地路径。
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# 仅审查/诊断: add --read-only
# 继续最近会话: add --resume-last
# 继续已记录会话: add --session <id>
# 选择限制: add --max-turns 40 --max-budget-usd 10
# 硬性 relay 截止时间: add --timeout 2h
# 查看所有选项: node .../relay.mjs --help
<skill-dir> 是已安装的技能目录,即包含此 SKILL.md 的文件夹。
relay 运行 claude -p --output-format stream-json --verbose,通过 stdin 发送简报,并默认将产物写入系统临时目录。它从不使用 --bg 或 --bare,也从不提交。见 references/dispatch-and-poll.md。
3. 等待
relay 会阻塞直到 Claude 退出。使用编排者的后台命令设施,或在前台运行并等待。完成意味着进程退出且 result.json 存在。
- 运行前用法错误退出码为 2,不写入 result.json。
- 缺少 claude 退出码为 127,并写入 status: "claude_unavailable"。
- 超时和捕获到的 relay 信号会终止整个实现者进程树,并保留结果产物。
从 result.json 读取 finalMessage、touchedFiles、resultSubtype 和原始产物路径。
4. 审查
将实现者的报告和门禁结果视为声明:
- 在绿色门禁有意义之前,先审查对现有测试的编辑。
- 自行重新运行项目的实际门禁。
- 对照简报阅读完整 diff,从 touchedFiles 开始。
- 检查未跟踪和已暂存内容,以及普通 diff。
- 如果安装了相关防护技能,运行它们。
完整清单见 references/review-and-land.md。
5. 落地
编排者仅在门禁通过且 diff 成立后提交。如需返工,用增量简报恢复同一 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 沙箱。relay 限制工具面并预批准 PowerShell,使运行保持非交互,但该 shell 不是操作系统隔离的。原生 claude.exe 和 npm claude.cmd 启动路径已实现;Windows 验证待定。
--read-only 使用计划模式,仅 Read、Glob 和 Grep。它移除编辑、写入和 shell 路径,然后比较解析后的 git porcelain,并对已脏的 Git 可见路径的工作树身份和索引条目进行指纹识别。当任一信号证明有变更时 readOnlyViolation 为 true,当覆盖完整且未检测到变更时为 false,当覆盖不完整时为 null。这是一个报告绊线,不是操作系统边界:被忽略的路径和完美恢复在其之外,本地钩子可以写入,并发变更无法归因于 Claude。
--dangerously-skip-permissions 是显式选择加入 Claude 的 bypassPermissions 模式。受限工具面、直接 commit/push 拒绝规则和支持平台上的 shell 沙箱仍然保留,但直接文件工具可以跨越正常权限边界。仅在人类明确接受时使用。
与原生 Claude 功能互补
Claude 子智能体、智能体团队和后台会话在当前 Claude 环境已经是编排者且目标是原生协调时很有用。此技能是互补的:它提供跨编排者契约——自包含简报 → 派发 → 产物 → 审查 → 落地——并将提交保留在编排者手中。
参考资料
- 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 — 顺序队列、进度跟踪、约束延续和最终一致性。
限制
- 纯文档导入——不包含可执行的 scripts/relay.mjs;完整运行时见上游。需要 claude CLI、Node 18+、git。
- relay 从不提交——它只返回结构化结果 JSON;由你审查并落地提交。
- 改编自 amElnagdy/delegate-skills(MIT)——纯文档,未捆绑运行时。