afk-cook

AFK runner

afk-cook 是一个 bash for 循环，每个 GitHub issue 都会启动一次全新的 claude -p 调用。每次迭代都会从空上下文开始。状态保存在 git 树、CLAUDE.md 和 GitHub issue 正文中。提示模板内嵌了 TDD 准则，让无头调用知道要执行 RED、GREEN、REFACTOR 并提交。

为什么每个切片都使用全新上下文

单个持续很久的 Claude 会话会在切片之间累积上下文，逐渐偏离方向，最终丢失重点。afk-cook 每个切片都会调用一次 claude -p，且每次都使用空上下文。Agent 从 issue 中读取规格，而不是依赖记忆。这正是此脚本采用 bash for 循环，而不是单个长时间运行会话的全部原因。

安装

安装采用薄包装器模式，分为两层：

• 技能文件夹。 npx skills@latest add GuillermoMurillo/memo-flow -a claude-code 会将真正的 runner 脚本及其提示模板并排放置在 .claude/skills/afk-cook/afk-cook 和 .claude/skills/afk-cook/slice-prompt.md。
• 包装器。 /memo-flow 只会在技能文件夹之外写入一个文件——位于 <project-root>/.claude/memo-flow/bin/afk-cook 的薄包装器：

#!/usr/bin/env bash
exec "$(dirname "$0")/../../skills/afk-cook/afk-cook" "$@"

采用间接调用的原因是，slice-prompt.md 绝不会复制到包装器旁边：exec 会用通过解析后的路径调用真正脚本的进程替换包装器进程，因此 runner 内的 $0 指向 .claude/skills/afk-cook/ 下的真正脚本，而不是包装器；默认提示路径（$(dirname "$0")/slice-prompt.md）也就会指向真正脚本旁边的模板。正确安装的项目在技能文件夹之外恰好只有一个 afk-cook 文件。不要通过复制文件来“修复”这一点。

请在项目根目录运行 ./.claude/memo-flow/bin/afk-cook。

如果缺少文件：

• .claude/memo-flow/bin/afk-cook 中没有包装器 → 重新运行 /memo-flow，并在出现提示时确认安装 AFK；这会重写包装器。
• .claude/skills/afk-cook/ 中没有真正的脚本或 slice-prompt.md → 技能本身未完整安装；重新运行 npx skills@latest add GuillermoMurillo/memo-flow -a claude-code，然后运行 /memo-flow。

用法

完整路径 .claude/memo-flow/bin/afk-cook 是有意为之——memo-flow 不会修改你的 PATH。有关 alias、direnv 和符号链接的配置方法，请参阅根 README 中的 afk-cook 的可选快捷方式。

./.claude/memo-flow/bin/afk-cook                  # all open ready-for-agent issues
./.claude/memo-flow/bin/afk-cook <N>              # one slice (good for first try)
./.claude/memo-flow/bin/afk-cook <N> <M> <O>      # explicit batch

依赖排序

运行前，afk-cook 会读取每个 issue 正文中的 Blocked by #N 标记来解析依赖（格式与 /to-issues 生成的相同）。然后按拓扑顺序运行队列：只有在某个 issue 所依赖的所有 issue 都已在跟踪器上 CLOSED，或已在本次运行中完成后，该 issue 才会开始处理。

启动时会公布排序结果：

afk: resolving dependencies for 4 issue(s): 9 10 11 12
afk: dependency-ordered queue: 9 10 11 12

如果队列中存在依赖环，或引用了无法解析的 issue（处于开放状态且不在队列中），afk-cook 会以状态码 4 退出，报告每个 issue 的阻塞项，并且不运行任何任务。

在同一个拓扑层（图中深度相同的切片）内，为确保结果确定，按数字顺序排列。

环境变量覆盖

变量	默认值	作用
MAX_RETRIES	2	如果 Agent 首次尝试未输出 SLICE_COMPLETE，则设置每个 issue 的重试次数。设为 1 可启用严格单次尝试模式。
LABEL	ready-for-agent	未传入参数时用于查询的标签
PROMPT_FILE	<script-dir>/slice-prompt.md	覆盖提示模板

示例：MAX_RETRIES=1 ./.claude/memo-flow/bin/afk-cook <N>，对单个切片启用单次尝试模式。

运行时会看到什么

• 每个切片显示一个横幅（═══...），每次尝试显示一个横幅（─── attempt N of M ───）
• Agent 的完整输出会流式传输到终端，同时通过 tee 写入 /tmp/ralph-slice-<N>-<attempt>.log
• 成功时：显示 ─── slice #<N>: SLICE_COMPLETE after attempt <N> ───，然后处理下一个切片
• Agent 报告阻塞时：显示 ─── slice #<N>: SLICE_BLOCKED ... ───，脚本以状态码 2 退出
• 重试次数耗尽时：显示 ─── slice #<N>: exhausted <N> attempts without completion ───，脚本以状态码 3 退出
• 依赖项无法解决时：显示 afk: cannot proceed — dependency cycle or unsatisfiable deps，脚本以状态码 4 退出

出现 SLICE_COMPLETE 时，运行器会验证本次尝试期间是否产生了新提交（比较尝试前后的 HEAD）。如果 Agent 发出了哨兵标记却没有提交，本次尝试会被视为失败并重试。确认有提交后，系统会在跟踪器上移除该问题的标签并将其关闭，同时添加引用 SHA 的评论。这样后续运行（今天或下周）会将其视为已满足依赖项的条件。

按 Ctrl-C 会中止当前迭代。除默认行为外，脚本不会捕获信号；部分写入的提交会留在工作树中。

如何理解退出状态码 4

exit 4 表示队列中至少有一个未关闭的问题，其依赖项既未在跟踪器上关闭，也未在本次运行中提前完成。脚本会打印逐个问题的阻塞报告，并添加上下文提示：

• 如果机器上有另一个 afk-cook 进程正在运行，阻塞项最有可能正由该进程处理。请等待它完成后再重新运行——不要启动并行运行，也不要在假定存在逻辑错误的情况下开始检查问题状态。正确的做法是将所有相互依赖的切片批量放在一次调用中，让依赖解析器安排顺序。
• 如果没有其他 afk-cook 正在运行，则阻塞项确实尚未交付，或者之前已交付但未在跟踪器上关闭。请在 GitHub 上检查该问题；如果已交付，请手动关闭，然后重新运行。

在同一仓库中并发运行是不安全的（它们会争抢 git HEAD、工作树和标签更新），但 afk-cook 不会通过锁来强制避免并发——依赖检查只覆盖并行运行会触及正在处理的阻塞项之依赖项这一常见情况。不要同时针对同一仓库运行两个 afk-cook 调用；请合并为一次调用。

何时使用它，何时交互式使用 /tdd

使用 afk-cook：

• 切片状态为 ready-for-agent（PRD 清晰，不需要设计判断）
• 你希望离开后让它自行交付
• 批量处理 2 个或更多可以顺序运行的切片

使用 /tdd：

• 切片状态为 ready-for-human（需要设计判断、文案选择或架构权衡）
• 你希望交互式监督 RED、GREEN 循环
• 只有一个切片，且你有时间参与

如果标记为 ready-for-agent 的切片因某种原因被错误分类，会以 SLICE_BLOCKED 退出。Agent 会在问题下留言，说明需要什么输入。

交接约定

在针对 ready-for-agent 切片完成 /tdd 交互式会话时，请在会话备注末尾为剩余切片添加一行可直接复制粘贴的命令：

#<N> done. Remaining ready-for-agent: #<M>, #<O>, #<P>.
To batch them, run:
  ./.claude/memo-flow/bin/afk-cook <M> <O> <P>

请使用通过 gh issue list --label ready-for-agent --state open --json number,title 查询到的当前未关闭问题编号。不要在本文档中写死编号；它们会过时。

故障模式

子进程挂起

如果切片挂起（测试运行器卡住，或 pre-commit 钩子一直没有返回），claude -p 调用也会挂起。可能的表现：

• 几分钟没有新输出
• 没有发出 SLICE_COMPLETE 或 SLICE_BLOCKED
• ps aux | grep claude 显示有进程在运行

恢复方法：按 Ctrl-C 中止脚本。手动终止孤立的 claude 和测试运行器进程。排查底层挂起原因（常见原因包括测试数据库尚未初始化、缺少迁移，或 Agent 留下了监视模式进程）。

Agent 在错误的分支上提交

脚本不会检查或切换分支。你当前所在的分支就是提交的目标分支。如果你不小心在 main 上，提交就会进入 main。启动前请检查 git branch --show-current。

Pre-commit hook 失败

提示词会要求 Agent 在提交前运行项目的测试和类型检查，因此 pre-commit hook 通常应该能通过。如果仍然失败，说明该任务切片的测试确实有问题。修复后重新运行。

切勿在 AFK 循环中使用 --no-verify 绕过 pre-commit hook。脚本不会传递该标志。如果某个任务切片确实需要这样做，请在循环外手动提交，并明确说明理由。

Agent 忘记在提交说明中注明 issue 编号

提示词明确要求在提交说明中加入 [#<N>] 或 Refs #<N>。如果某个任务切片提交时没有包含这些内容，说明提示词没有得到遵循。重新阅读提示词模板并加以完善。