用途:把编码工作拆分为“编排者 + 执行者”模式。编码助手负责规划、编写自包含任务规格、派发任务、审查每处 diff 并承担最终结果;Grok Build CLI(grok)以无头方式作为快速、低成本的执行者。
适合委派给 Grok 的任务:验收标准清晰的任务、样板与脚手架、CRUD、机械重构、按明确规格写测试、依据原型或规格实现 UI 组件。应保留在编排者手中的:需求含糊、架构决策、跨文件深度调试、安全敏感代码、涉及生产基础设施的任务,以及“写规格约等于自己动手”的任务。拿不准时保留给编排者。
会话预检(首次派发前执行一次):运行 grok update --check --json,若 updateAvailable 为 true 则运行 grok update 并用 grok --version 确认;运行 grok models,若报错或提示未登录,停止并请用户执行 grok login。
单任务循环(默认串行):1)写规格,把自包含任务文件写到目标仓库之外的临时目录,绝不写进目标仓库,Grok 没有对话上下文,不能只用一句话提示。POSIX 用 mkdir -p "${TMPDIR:-/tmp}/grok-specs" 后写入 task.md;Windows PowerShell 用 New-Item -ItemType Directory -Force "$env:TEMP\grok-specs" 后写入 task.md。2)保持干净状态,先提交或暂存,使运行后的 diff 恰好是 Grok 的工作,不要在脏源码树上派发。3)派发,POSIX 命令为 grok --prompt-file <task-file> --output-format json --always-approve --max-turns 30 --cwd <repo>;Windows PowerShell 使用反引号续行。解析 JSON 输出并保存 sessionId。无头运行必须加 --always-approve,--permission-mode acceptEdits 会静默取消编辑。高风险任务可加 --check 让 Grok 自检,否则会约翻倍延迟。4)审查关卡不可跳过:自己读 diff(可用 git diff -- <spec 中的文件> 跳过产物噪音),确认只做了该任务且符合仓库约定,运行规格中的验收命令。通过则按仓库约定提交,进入下一任务;失败则用 grok --resume <sessionId> -p "<具体反馈>" --always-approve --output-format json 修复,最多两轮,仍失败则回滚 Grok 的改动(git checkout -- .;新文件用 git clean -fd),自己完成并告知用户。
任务规格模板包含:标题、上下文(仓库路径与项目说明、约定如测试运行器与格式化工具、可模仿的示例文件)、文件(修改与新建路径)、任务描述、约束(不得修改列出的文件之外的内容等)、验收标准(精确命令与预期结果)。
执行 Markdown 实现计划:每次派发一个计划任务并按顺序进行,任务通过审查后勾选复选框。仅当计划明确标注任务相互独立时才可并行派发,使用 --worktree=<task-slug> 并发运行,再逐个通过同一审查关卡合并;合并冲突常抵消收益,优先串行。
失败处理:stopReason 为 Cancelled、文本为空、无 diff,通常是缺少 --always-approve,加上重试;CLI 错误或超时重试一次,之后自己做并记录回退;认证过期则停止并请用户 grok login;两轮修复耗尽则回滚并自行完成;派发时工作树脏则拒绝,先提交或暂存。
模型:默认 grok-4.5,仅对琐碎的机械任务加 -m grok-composer-2.5-fast。更多 CLI 细节与已验证行为见 references/cli.md。