setup-ralph-loop

设置 Ralph Loop

创建运行 Ralph 所需的本地脚本和仓库约定，确保安全。

调用位置

这是一项基础设施技能，而不是常规的功能交付阶段。

当项目希望在可重复的 HITL 到 AFK 循环中运行 /execute 时，使用 /setup-ralph-loop。

**自动调用：**当 /execute 检测到涉及多个切片的 GitHub issue 工作（PRD、大批量工作，或多个用户故事），且仓库根目录中不存在 ralph-once.sh 或 ralph.sh 时，会自动调用此技能。这意味着即使用户没有明确调用此技能，也可能进入此技能——检测和调用会在 /execute 内作为前置步骤进行。

不要将其作为默认功能流水线的一部分。它会为仓库做好准备，让后续的 /execute 执行能够在 Ralph 模式下运行，并具备有界迭代、明确的反馈循环，以及由 GitHub 支持的持久状态。

此设置会创建什么

• ralph-once.sh，用于单次迭代的 HITL Ralph
• ralph.sh，用于有界的 AFK Ralph 运行
• 可选的 package.json 脚本，便于调用
• 仓库本地循环提示词，告知 Ralph 优先处理风险最高且未受阻的切片、运行反馈循环，并在工作完成后停止

设置前的规则

• Ralph 是 /execute 的一种执行模式，不是单独的工作流。
• 首先使用 HITL Ralph。只有当提示词、反馈循环和质量标准运行良好后，才切换到 AFK。
• 在此工作流中，Ralph 的持久进度状态保存在 GitHub issue、issue 评论和提交中，而不是 progress.txt 或其他本地任务状态文件中。
• 每次迭代都应恰好实现一个可供审查的切片。
• 每个 AFK 循环都必须有界。不要生成无限循环。

步骤

1. 确认任务来源和状态模型

询问 Ralph 应从哪里读取工作项。

优先顺序如下：

1. 带有依赖关系的 GitHub issue
2. 仓库实际使用的其他持久待办系统
3. 仅在用户明确要求时，使用临时备用文件

如果仓库使用 GitHub issue，请让 Ralph 原生使用 GitHub：

• 未关闭的 PRD issue 定义最终状态
• 切片 issue 定义当前工作队列
• issue 评论记录具体错误或部分进度的上下文
• 提交作为执行日志

除非用户明确选择偏离仓库的 GitHub 优先模式，否则不要引入 progress.txt 作为持久状态。

2. 检测反馈循环

生成脚本前，检查目标仓库。

检查 package.json 或同等工具中可用的命令：

• typecheck
• test
• lint
• build

同时注意仓库是否已有：

• /setup-pre-commit
• 容器或沙盒工具
• 已配置的 GitHub CLI

生成的 Ralph 提示词只能列出实际存在的反馈循环。

3. 检测执行环境

询问 Ralph 应在以下哪种环境中运行：

• 当前仓库 Shell
• 沙盒 Shell 或容器
• 通过现有任务运行器（例如 pnpm）

默认建议：

• 首先在当前仓库中使用 HITL
• 尽可能在沙盒或隔离环境中使用 AFK

4. 生成 ralph-once.sh

先创建一个用于人工监督的一轮脚本。

脚本应：

• 恰好运行一轮 Ralph
• 指定 Ralph 的任务来源
• 在脚本中计算未受阻任务集，并告诉 Ralph 从中挑选风险最高的部分
• 告诉 Ralph 使用 /execute
• 告诉 Ralph 运行仓库的实际反馈循环
• 告诉 Ralph 在完成一个可审查的部分后停止

建议结构：

#!/bin/bash
set -e

# Compute the frontier in bash rather than asking the model to reconstruct it
# by reading `Blocked by` prose out of N issue bodies. Native GitHub issue
# dependencies (wired by /prd-to-issues §7) make this a lookup; filtering to
# OPEN blockers keeps it current with no bookkeeping.
#
# `gh issue list` excludes pull requests by definition, so no filter is
# needed. `state` is the GraphQL enum: uppercase OPEN, not REST's lowercase.
FRONTIER=$(gh issue list --state open --limit 100 --json number,blockedBy \
  --jq '[.[]
        | select([.blockedBy.nodes[] | select(.state == "OPEN")] | length == 0)
        | .number] | join(", ")')

if [ -z "$FRONTIER" ]; then
  echo "No unblocked issues — either all work is done, or the graph has a cycle."
  exit 0
fi

claude --message "Unblocked GitHub issues, takeable right now: $FRONTIER. Pick the highest-risk one of those that still needs implementation. Use /execute to implement exactly one reviewable slice. Run the repo's feedback loops. If all issue work is complete, say DONE and stop."

根据实际任务来源和可用命令调整提示词。

将计算好的候选集交给模型——而不是指示它“遵守阻塞关系”——正是这种结构的关键。要求模型遵循一张必须先从文字中重新构建的图，背后并没有任何机制；一旦失败，结果不是报错，而是看似合理却选错了部分。AFK 阶段没有人监看，因此最无法承受这种问题。确定性选择留在 bash 中；模型真正擅长的判断（这些候选中哪一个风险最高）则留在提示词中。

如果仓库中的部分 issue 早于原生依赖关系接入，那么 $FRONTIER 会列出所有内容。信任它之前先检查：如果每个未关闭 issue 都显示 .blockedBy.totalCount == 0，而正文中却有 Blocked by #N 这样的文字行，就说明根本没有写入任何依赖边。先接入这些依赖边——参见 /prd-to-issues §7——否则循环又会变成猜测。AFK 阶段最无法承受这种问题，因为没人监看时，可能会选错部分。

5. 生成 ralph.sh

创建一个有界的 AFK 循环。

脚本必须：

• 要求提供迭代次数参数
• 未提供参数时立即失败
• 每次循环运行一轮
• 避免使用 while true
• 保持与 ralph-once.sh 相同的任务挑选逻辑

建议结构：

#!/bin/bash
set -e

if [ -z "$1" ]; then
  echo "Usage: $0 <iterations>"
  exit 1
fi

for ((iteration=1; iteration<=$1; iteration++)); do
  # Recompute each iteration — closing a blocker un-gates its dependents,
  # so the frontier grows as the loop makes progress.
  FRONTIER=$(gh issue list --state open --limit 100 --json number,blockedBy \
    --jq '[.[]
          | select([.blockedBy.nodes[] | select(.state == "OPEN")] | length == 0)
          | .number] | join(", ")')

  if [ -z "$FRONTIER" ]; then
    echo "No unblocked issues — stopping after $((iteration - 1)) iteration(s)."
    break
  fi

  claude --message "Unblocked GitHub issues, takeable right now: $FRONTIER. Pick the highest-risk one of those that still needs implementation. Use /execute to implement exactly one reviewable slice. Run the repo's feedback loops. If all issue work is complete, say DONE and stop."

  echo "Ralph iteration $iteration complete."
done

在循环内重新计算前沿，才能让依赖图在多轮迭代中发挥实际作用：第 1 轮被阻塞的部分，一旦其阻塞项关闭，就会立即变为可处理状态，无须修改任何 issue 正文。

如果用户需要，也可以在 package.json 中添加便利脚本，例如：

{
  "scripts": {
    "ralph:once": "./ralph-once.sh",
    "ralph": "./ralph.sh 5"
  }
}

如果添加 package 脚本，请设置较小的默认迭代次数。

6. 明确写出质量标准

确保生成的循环提示词清楚说明仓库的质量要求。

提示词应说明 Ralph 必须：

• 一次实现一个可审查的部分
• 每轮运行反馈循环
• 避免悄悄变更范围
• 未受阻时优先处理高风险部分
• 受阻时在 issue 评论中留下确切的错误输出
• 多次失败后停止并升级处理，而不是无限重试
• 多次未取得进展（停滞）后停止并升级处理，而不只是多次失败——未取得进展是指在同一个部分上连续两轮迭代中，没有任何未满足的验收标准、失败的检查或未解决的问题转为已解决；有一轮取得进展即可重置计数器。完整规则见 /execute“AFK progress and plateau detection”以及 references/SYSTEM-OVERVIEW.md（与此技能一起打包）。
• 实现后，以 /pre-merge 的 loop-mode 运行审查——只有当 PR 的处置台账中每条审查发现都有对应条目时，AFK 迭代才算完成，而不是代码提交时
• 记录发现；不要处理它们。Loop-mode 不会提交任何内容，也不会解决任何事项：修复、登记、接受和搁置都是操作人员的决定，应在早上依据台账作出
• 绝不要把“审查结果很干净”当作停止的理由——在审查结果干净时退出的循环，只会产出干净的审查结果，而不会让代码变得更好

暂时不要在 ralph.sh 中添加审查阶段。 从 /execute 第 6 步的 AFK 退出流程进入 loop-mode 已足以验证这一点。只有在循环先以 HITL 优先的方式运行之后，才会考虑将其作为显式的实现后阶段接入脚本——这与 Ralph 本身遵循的 HITL 优先于 AFK 规则相同（见下文第 8 步）。

如果仓库显然是长期维护的生产代码，请在提示词中明确说明。

7. 验证生成的设置

检查：

• ralph-once.sh 存在且可执行
• ralph.sh 存在且可执行
• 如果有相关要求，已正确添加 package.json 脚本
• 生成的提示词引用了真实的任务来源
• 生成的提示词只引用了真实的反馈循环
• 除非用户明确要求，否则未引入 progress.txt

完成后： 创建 Ralph 标记，以便强制执行钩子知道设置已完成。

mkdir -p "$CLAUDE_PROJECT_DIR/.claude" && touch "$CLAUDE_PROJECT_DIR/.claude/.ralph-checked"

8. 建议首次使用方式

指导用户：

1. 先运行 ./ralph-once.sh
2. 检查结果
3. 如果任务选择或质量不理想，优化提示词
4. 只有完成上述步骤后，才运行有界 AFK Ralph，例如 ./ralph.sh 5

验证

在认为设置已完成之前，检查：

• Ralph 有一个 HITL 入口点
• Ralph 有一个有界 AFK 入口点
• AFK 循环不会无限运行
• 任务选择优先考虑风险，而不只是列表顺序
• 提示词使用 /execute
• 提示词列出了仓库中真实的反馈循环
• 除非用户明确选择其他方式，否则持久状态仍以 GitHub 为基础

交接

• 预期输入： 一个希望围绕 /execute 实现可重复 Ralph 执行的仓库
• 产出： 可正常工作的 Ralph 循环脚本，以及仓库本地的约定，支持先 HITL、再进行有界 AFK 执行
• 支持下游： /execute、/pre-merge 和基于 GitHub issue 的执行，让 AFK 工作更安全、更可重复
• 后续步骤： 回到常规功能开发，先试用 ralph-once.sh，然后在确认设置可靠后使用有界 AFK Ralph