grok-build

Grok Build 编排

编码助手是编排者：它负责规划、编写自包含的任务规范、以无头模式将任务分派给 Grok Build、审查每个差异，并对最终结果负责。 Grok 是快速、低成本的执行者。完整的 CLI 详情和已验证行为：references/cli.md。

何时委派，何时由编排者处理

委派给 Grok	由编排者处理
验收标准明确的任务规划	需求模糊、架构决策
样板代码、脚手架、CRUD	深入的跨文件调试
机械式重构	对安全敏感的代码
根据明确规范编写测试	任何涉及生产基础设施的工作
根据模型图/规范编写 UI 组件	编写规范几乎等同于完成工作的任务

拿不准时，就由编排者处理。

会话预检（首次分派前执行一次）

1. grok update --check --json — 如果 updateAvailable 为 true，运行 grok update，并通过 grok --version 确认。
2. 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. 清理状态。 不得有未提交的源代码更改 — 先提交或暂存，这样运行后的差异才恰好是 Grok 的工作。忽略构建产物（__pycache__、dist/ 等）；如果它们出现在 git status 中，通常只是没有被 Git 忽略，无需处理。切勿在源代码树状态不干净时分派任务。

3. 分派。

   POSIX：

   grok --prompt-file <task-file> \
     --output-format json \
     --always-approve \
     --max-turns 30 \
     --cwd <repo>
   

   Windows（PowerShell）— 使用反引号续行：

   grok --prompt-file <task-file> `
     --output-format json `
     --always-approve `
     --max-turns 30 `
     --cwd <repo>
   

   解析 JSON 输出并保存 sessionId。（无头运行必须使用 --always-approve — --permission-mode acceptEdits 会在没有交互式审批者时静默取消编辑。参见 references/cli.md。）对于高风险任务，添加 --check，让 Grok 在你审查前进行自我验证；其他情况则跳过（这会使延迟大约翻倍）。

4. 审查关卡 — 不可妥协。

   • 亲自查看差异（使用 git diff -- <files from the spec> 跳过产物噪声）：它是否完成了任务、没有做任务之外的事，并符合仓库惯例？
   • 运行规范中的验收命令。
   • 通过 → 按照仓库惯例使用清晰的提交信息进行提交 → 开始下一项任务。
   • 未通过 → 修正：grok --resume <sessionId> -p "<specific feedback>" --always-approve --output-format json。最多修正 2 轮。 仍然失败 → 撤销 Grok 的更改（对新文件运行 git checkout -- .；运行 git clean -fd），自己完成任务，并告知用户 Grok 未能完成任务。

任务规范模板

# Task: <one-line title>

## Context
- Repo: <path> — <one line on what the project is>
- Conventions: <test runner, formatter, a good example file to imitate>

## Files
- Modify: <path>
- Create: <path>

## Task
<precise description of the change>

## Constraints
- Do not modify any files other than those listed above.
- <other constraints>

## Acceptance criteria
- `<exact command>` <expected result>

执行 Markdown 实施计划

• 每次分派一个计划任务，并按顺序执行。
• 每项任务完成并通过审查关卡后，勾选计划中的任务复选框（- [ ] → - [x]）。
• 如果计划明确标记任务相互独立，请参阅下文的并行分派；否则按顺序执行。

并行分派（选择加入的例外情况，并非默认方式）

仅当计划明确标记任务相互独立时：使用 --worktree=<task-slug> 分派每项任务，并发运行，然后按照同一审查关卡逐个审查并合并工作树。合并冲突通常会抵消并行带来的收益 — 优先按顺序执行。

失败处理

失败情况	操作
stopReason: "Cancelled"、文本为空、没有差异	缺少 --always-approve — 使用此选项重试
CLI 错误 / 超时	重试一次；之后自行完成任务并注明回退方案
身份验证已过期	停止；请用户运行 grok login
2 轮修正已用尽	还原 Grok 的差异；由编排器完成任务
分派时工作树不干净	拒绝；先提交或暂存

模型

默认使用 grok-4.5。仅对简单的机械性任务添加 -m grok-composer-2.5-fast。