ralph-loop-template

Ralph Loop 模板

输入

$ARGUMENTS

说明

步骤 1：收集计划

如果提供了参数：读取文件以了解计划内容。

如果未提供参数：按以下顺序搜索计划：

1. 在项目根目录中搜索计划文件：PLAN.md、plan.md、PLAN-*.md、plan-*.md、TODO.md、prd.md、PRD.md
   • 找到 1 个 → 使用该文件（告知用户检测到的文件）
   • 找到多个 → 列出文件并请用户选择
   • 未找到 → 继续下一步
2. 使用当前对话上下文中讨论的计划。
3. 如果对话上下文中没有计划，请用户描述计划。

步骤 2：识别项目环境

收集项目特定信息，以便将其嵌入 PROMPT 文件。

按以下优先级顺序搜索 Agent／项目配置文件：

1. CLAUDE.md（Claude Code）
2. .cursorrules（Cursor）
3. .windsurfrules（Windsurf）
4. AGENTS.md、COPILOT.md、GEMINI.md

如果找到配置文件，请提取：

• 验证命令：将构建、测试、lint 命令合并为一条命令链（例如，npm run lint && npm run build && npm test）
• 关键代码风格规则（插入 PROMPT 绝对规则 {AGENT_RULES} 的条目，最多 3 条）

如果未找到配置文件：根据项目结构推断：

• package.json → npm/yarn 命令
• Makefile / Justfile → make/just 命令
• Cargo.toml → cargo 命令
• pyproject.toml / setup.py → Python 工具链
• 如果无法判断，请用户提供构建／测试命令

步骤 3：分析计划

从计划中提取以下内容：

• 目标：要构建什么
• 非目标：此任务中不会完成什么（以防止功能臆造）
• 阶段列表：按顺序排列的实现步骤
• 各阶段的关键内容：要修改的文件、实现细节
• 参考文档／文件：模式参考、设计文档路径
• 完成标准：判断整个任务是否完成的标准

完成标准必须可通过机械方式验证（例如，命令执行后返回退出代码 0）。不要使用“运行良好”或“看起来整洁”等主观标准。

步骤 4：拆分阶段

将计划拆分为适合 Ralph Loop 迭代的阶段。

拆分原则：

• 一次迭代 = 恰好一个阶段。 在一次迭代中执行两个阶段，会导致验证失败时无法追溯到具体阶段，且下一次迭代的恢复状态不明确。
• 阶段完成后，立即结束本次迭代。下一阶段在下一次迭代中处理。
• 每个阶段必须是能够独立通过验证的最小单元。
• 拆分过大的阶段，合并过小的阶段。

规模指南（仅供参考，并非绝对标准）：

• 如果描述需要 3 句以上 → 可考虑拆分
• 如果只是修改一个文件中的一行 → 可考虑与相邻阶段合并
• 合适的规模是 Agent 能在单个上下文中完成实现和验证的规模

max-iterations 计算方式：阶段数 + 2

• +1：验证失败时自动重试的缓冲
• +1：最后一个阶段完成后输出 promise 的缓冲迭代

Step 5：生成 PROMPT 文件

使用 references/prompt-template.md 作为基础模板，并将 references/iteration-procedure.md 作为迭代流程块，生成 PROMPT 文件。

在项目根目录中创建 PROMPT-{kebab-case-name}.md 文件。

占位符映射：

占位符	来源	后备方案
{goal title}	第 3 步	询问用户
{project name}	项目目录名称或 CLAUDE.md	询问用户
{goal}	第 3 步	询问用户
{AGENT_RULES}	第 2 步（Agent 配置规则）	如果没有配置文件，则省略整行
{non-goals}	第 3 步 + 用于推断的非目标编写规则	至少 2 项
{reference doc rows}	第 2-3 步	如果没有文档，则省略整个参考文档部分
{iteration procedure}	完整的 references/iteration-procedure.md	—
{checklist}	第 4 步的阶段划分结果	—
{verification command}	第 2 步（项目检测）	询问用户
{COMPLETION_PROMISE}	COMPLETION_PROMISE 生成规则	—

注意：包含花括号的示例文本（例如范围外发现项的记录格式）应保持原样，不要进行替换。

Step 6：输出结果

按以下格式提供生成的 PROMPT 文件路径，并输出 /ralph-loop 命令：

### Generated File

`{PROMPT file path}`

> Review the generated PROMPT file before execution. Check the verification commands and phase structure in particular.

### Ralph Loop Execution Command

/ralph-loop "Read {PROMPT file path} and implement the next unchecked phase. Always read the file first to find the first phase with [ ] items." --max-iterations {number of phases + 2} --completion-promise "{COMPLETION_PROMISE}"

输出上方的命令块，以便直接复制使用。

---

生成规则

清单编写规则

• 阶段 = 迭代单元：单个 ### Phase N 块会在一次迭代中处理
• 子项 = 阶段内的详细任务：在每个 Phase 下放置 2-5 个 - [ ] 子项
• 子项应指定要更改的文件和实现细节
• 验证不是清单项——它会在迭代流程的 STEP 4 中自动运行。使用第 2 步中检测到的项目构建/测试命令

非目标编写规则

除计划中明确排除的项目外，还要推断并添加：

• 计划范围之外的重构
• 未被要求的测试/文档/配置变更
• 对现有 API 或接口的更改（除非计划中有说明）

COMPLETION_PROMISE 生成规则

• 使用大写英文，并以空格分隔
• 简要概述目标（例如，“HELP OVERLAY COMPLETE”“AUTH REFACTOR DONE”）