ralphify-spec

ralphify-spec

将用通俗英语描述的迭代任务转换为有效、可运行的 ralphify ralph 目录——其中包含带有格式正确的 YAML 前置元数据、实用命令块，以及遵循 Ralph Wiggum 方法的提示词正文的 RALPH.md。

用户不需要了解 ralphify 的工作原理。不要向他们解释前置元数据、占位符或 shlex 的特殊行为。将他们的目标转换为可运行的 ralph，并提供建议的运行命令。

适用场景

对于每次迭代都能取得渐进式进展，并且有停止条件告知循环何时终止的工作，ralph 很有用：

• 将测试覆盖率提升至某个阈值
• 清除 lint 或类型检查错误
• 将文件从一种语言／框架迁移到另一种
• 逐条解决 PR 审查意见
• 持续处理队列中的项目，直到队列清空

如果任务只需一次完成（例如“在此页面添加一个按钮”“解释这个函数”），ralph 并无帮助。建议一次性实现，然后停止。

工作流

1. 确认意图（最多提问 2～3 个问题）

只询问无法从对话或当前工作目录推断的信息。跳过用户已经回答过的问题。

1. 完整运行一次后，什么状态算“完成”？（覆盖率超过 90%、没有 clippy 警告、所有审查讨论串都已解决。）这决定停止条件，以及 ralph 每次迭代展示哪些命令。
2. 使用什么语言和工具？ 先检查 pyproject.toml、Cargo.toml 或 package.json；只有无法确定时才提问。
3. 有哪些硬性约束？ 需要避开的文件、提交格式、风格指南。只有在不明显时才提问。

不要询问命令块、前置元数据字段、占位符或 YAML。翻译是你的工作。

2. 选择名称和位置

• 除非用户已提供名称，否则推导一个 kebab-case 名称（coverage-climber、ts-porter、clippy-burndown）。验证器（第 7 步）会强制检查 ralphify 接受的确切字符集。
• 默认位置：当前仓库中的 ralphs/NAME/。只有当当前工作目录不适合作为存放位置时才确认。

3. 从规范模板创建脚手架，然后改写

从 ralphify 自带的模板开始，确保文件可解析：

ralph init ralphs/NAME

如果 ralph 不在 PATH 中，则改用 ~/.local/bin/ralph（uv tool install ralphify 会将其安装到此处）。创建脚手架后，根据用户的任务改写文件——不要直接使用原始模板。

4. 设计前置元数据

references/schema.md 是权威的架构参考。需要精确规则时请阅读；不要从本技能正文重新推导。

默认 Agent：根据上下文判断——claude -p --dangerously-skip-permissions（Claude Code）、gemini -p --yolo（Gemini CLI）或 cursor-agent -p（Cursor）。如果无法确定用户使用哪种运行环境，则询问。

如果仓库禁止自动提交尾注，请设置 credit: false。

根据技术栈选择默认 commands：

• 任何仓库：git-log → git log --oneline -10
• Python：tests → uv run pytest，lint → uv run ruff check .
• Rust：tests → cargo test，lint → cargo clippy --all-targets -- -D warnings
• Node/TS：tests → npm test，lint → npm run lint
• 停止条件探测：编写脚本（第 5 步），并将其引用为 ./check-done.sh

只有当 ralph 需要在不同目标间重复使用时才添加 args。否则直接硬编码——之后再泛化很容易。

防护脚本（短路模式）

如果 ralph 有明确的“全部完成”条件，且能在启动 Agent 前检查，请用防护脚本封装 Agent 调用，并将 agent: 指向该脚本。完整模式见 references/guards.md，其中包含迭代上限防护和 COMPLETE 哨兵防护；所有生成的 ralph 都必须包含这两项。

收尾门禁（仅适用于 burn-down-todos ralph）

当循环模式为 burn-down-todos（一种由队列驱动的 ralph，队列耗尽时触发收尾操作——打开 PR、推送整个提交栈、标记版本发布）时，请在 ralph 目录中将以下两个规范脚本与 RALPH.md 一同安装：

1. assets/next-issue.sh.template → next-issue.sh。队列读取脚本 RALPH.template.md 的 commands.next-issue 会在每次迭代中调用它。它的标准输出（Path: … / QUEUE EMPTY / QUEUE READ ERROR）用于决定 Task 区块中的互斥分支。
2. assets/closer-gate.sh.template → closer-gate.sh。收尾迭代必须通过 Guard 4 的判定门禁，之后才能推送、提交、创建 PR 或输出 COMPLETE 标记。

在两个脚本中填入相同的 PLACEHOLDER_* 标记（队列目录、glob、状态字段、规划分支），并执行 chmod +x，同时在 RALPH.md 中将收尾区块设为必须先执行 CLOSER GATE PASS，作为收尾操作的第 1 步。这是 references/guards.md 中的 Guard 4；之所以存在，是因为此类 ralph 中所有已观察到的失败都涉及在同一迭代中触发收尾操作和单项工作，并在仍有未处理项时输出 COMPLETE。

5. Shell 功能应放在脚本中

commands[].run 使用 shlex.split 解析。不支持管道、&&、重定向或 $(...)。对于任何非简单操作，请在 ralph 目录中编写脚本，并通过 ./name.sh 引用：

commands:
  - name: coverage
    run: ./check-coverage.sh

• 使用 chmod +x 让脚本可执行。
• 通过 ./ 前缀调用的脚本以 ralph 目录为当前工作目录；不带此前缀的命令则从项目根目录运行。
• 脚本应简短且用途单一——Agent 只能看到脚本的输出。

6. 编写提示词正文

每次迭代都会从全新上下文开始。提示词必须在每次迭代中重新建立足够的情境信息，确保内容有用。遵循规范结构：

1. 角色与循环认知。“你是一名在循环中运行的自主 {role} Agent。”在 ## Iteration 标题下加入 {{ ralph.iteration }}，让 Agent 知道当前所处的位置——这对“在最后一次迭代中执行清理”等逻辑很有用。
2. 确认上下文重置。“每次迭代都会从全新上下文开始。你的进度保存在代码和 git 中。”以免 Agent 试图记忆状态。
3. **命令输出区块。**将 {{ commands.<name> }} 放在 ## <Title> 标题下。Agent 只能看到提示词中呈现的内容。
4. **任务区块。**准确说明每次迭代要完成什么工作。范围越窄越好：“为一个尚未测试的函数添加测试”胜过“提升覆盖率”。应让上下文全新的 Agent 选定目标，并在一次迭代中完成。
5. **停止条件。**当循环的“完成”条件满足时，由 Agent 输出 <promise>COMPLETE</promise> 标记。ralph run 退出后，scripts/run.sh 中的运行器包装脚本会扫描捕获的日志，找到此标记则以 0 退出；否则会将本次运行标记为达到上限的失败。（运行期间不会提前终止——ralph 会运行至自然结束。）
6. **规则。**使用项目符号列出——应避免的事项以及必须始终遵循的事项。
7. **提交约定。**每次迭代提交一次；指定格式（Conventional Commits 或仓库规范）；说明是否推送。

对于 burn-down-todos ralph，Task 区块必须是一个互斥分支区块：单项工作、收尾和恢复是三种不同的迭代模式，由队列读取输出（Path: … / QUEUE EMPTY / QUEUE READ ERROR）决定。单项工作迭代必须以明确的 STOP 标记（ITERATION DONE: <id>）结束；收尾迭代必须先运行 Guard 4 的 closer-gate.sh，且没有 CLOSER GATE PASS 就不得继续。assets/RALPH.template.md 提供了规范结构——复制该文件，填入占位符，并确保单项工作和收尾步骤不会在同一次迭代中执行。

HTML 注释（``）会在传递给 Agent 前剥除——适合用于维护备注，且不会浪费令牌。

7. 使用捆绑脚本进行验证

对草稿运行捆绑的验证器。这是必经关卡——不要跳过，也不要自行猜测它检查的内容：

uv run --with pyyaml python scripts/validate.py PATH/TO/RALPH.md

（根据此技能在你的运行环境中的位置调整脚本路径。）

它会强制检查 references/schema.md 中的架构规则——必填字段、名称正则表达式、shlex 安全性、占位符覆盖情况、Agent 是否在 PATH 中、超时类型。退出码 0 = 无问题（警告仅供参考），1 = 存在必须修复的错误，2 = 环境问题。

留意警告——已声明但未使用的命令或参数意味着需要清理。

8. 配置运行器包装脚本

将此技能的 scripts/run.sh 复制到生成的 ralph 目录中，与 RALPH.md 放在同一层级（或将其符号链接为 ralphs/NAME/run.sh）。将包装脚本保留在 ralph 目录中，可让运行命令独立运行；如果移动或共享该目录，包装脚本也会随之带上。该包装脚本会强制执行裸 ralph run 不会执行的迭代次数上限规则：

• 如果缺少 -n / --max-iterations，则拒绝启动——每个生成的 ralph 都必须声明上限。
• 打印包含上限值的启动横幅，让用户清楚迭代上限。
• ralph run 退出后，扫描捕获的日志以查找 <promise>COMPLETE</promise>；如果找到则退出码为 0，否则显示 CAP HIT WITHOUT COMPLETE 横幅并以非零状态退出——禁止静默继续。（不会在运行中提前终止；ralph 会运行至自然结束：达到上限、出错或触发 --stop-on-error。）

完整的保护规则请参阅 references/guards.md。

9. 报告结果

向用户展示：

1. 文件树：展示所创建目录的文件结构。
2. 一句话：描述单次迭代会做什么。
3. 建议的首次运行命令： ralphs/NAME/run.sh ralphs/NAME -n 50 -t 1800 -s -l ralphs/NAME/logs —— 50 次迭代、30 分钟超时、出错时停止，并捕获日志。包装脚本路径符合第 8 步“复制到 ralph 目录中”的说明；第二个 ralphs/NAME 是包装脚本传递给 ralph run 的 ralph 目录参数。先从 -n 50 开始，可以观察循环的运行情况，之后再取消上限——包装脚本会拒绝完全省略上限。

不要做的事

• 不要臆造 ralphify 不支持的 frontmatter 字段。架构刻意保持精简——除 agent、commands、args、credit 外的任何内容都是冗余。
• 不要在 run: 中通过管道或链式调用命令。应使用脚本。
• 不要留下没有对应声明的占位符——它们会作为字面文本呈现，并使 Agent 感到困惑。
• 不要向用户询问 ralphify 的内部细节。如果他们想写 YAML，就不会来这里。
• 首次运行时不要默认使用不设上限的 -n。应从 -n 50 开始。运行器包装脚本会强制执行这一规则。
• 不要省略 <promise>COMPLETE</promise> 哨兵。没有明确终止条件的循环会持续消耗令牌，直到达到上限，并以含糊的状态退出。
• 不要生成一种 burn-down-todos RALPH.md，使其 Task 块允许收尾步骤与单项工作在同一次迭代中触发。一次迭代只能采用一种模式（或执行恢复工作），不能同时执行两种模式。单项处理步骤必须以 ITERATION DONE: <id> 结束；收尾步骤在执行任何推送或 COMPLETE 步骤之前，必须等待 CLOSER GATE PASS。跳过这种模式正是 Guard 4 要防止的故障。

捆绑脚本

# Validate a draft RALPH.md against the v0.3.0 schema.
#   exit 0 = clean, 1 = errors, 2 = environment problem
uv run --with pyyaml python scripts/validate.py PATH/TO/RALPH.md

# Wrap `ralph run` so the iteration cap is mandatory and the COMPLETE
# sentinel decides the exit code. Forwards every other flag to ralph run.
scripts/run.sh PATH/TO/RALPH_DIR -n 50 -t 1800 -s -l PATH/TO/RALPH_DIR/logs

参考资料

• references/schema.md — 需要了解准确的 frontmatter 规则（v0.3.0）时阅读：必填字段、正则表达式约束、默认值。
• references/guards.md — 为新 ralph 设计防护方案时阅读：迭代次数上限、COMPLETE 哨兵、收尾门禁（Guard 4）、 Agent 执行前短路、规范的 next-issue.sh、常见错误。
• assets/RALPH.template.md — 复制到新的 ralph 目录中，作为 burn-down-todos 循环的 起始模板；在原处填写 PLACEHOLDER_* 标记。
• assets/next-issue.sh.template — 对于 burn-down-todos ralph，将其复制到 RALPH.md 旁边； 模板会在每次迭代中通过 commands.next-issue 调用该队列读取脚本。
• assets/closer-gate.sh.template — 对于 burn-down-todos ralph，将其复制到 RALPH.md 旁边； 填入队列目录、glob、状态字段和规划分支，并为收尾 Agent 设置门禁（Guard 4）。