ralph-loop-template

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Input

输入

text

$ARGUMENTS

text

$ARGUMENTS

Instructions

说明

Step 1: Gather Plan

步骤1：收集计划

If an argument is provided: Read the file to understand the plan content.

If no argument: Search for a plan in the following order:

Search for plan files in the project root:
```
PLAN.md
```
,
```
plan.md
```
,
```
PLAN-*.md
```
,
```
plan-*.md
```
,
```
TODO.md
```
,
```
prd.md
```
,
```
PRD.md
```
- 1 found → Use it (inform the user which file was detected)
- Multiple found → Present the list and ask for selection
- 0 found → Proceed to next step
Use the plan discussed in the current conversation context.
If no plan exists in the conversation context, ask the user to describe the plan.

若提供参数：读取文件以理解计划内容。

若无参数：按以下顺序搜索计划：

在项目根目录搜索计划文件：
```
PLAN.md
```
,
```
plan.md
```
,
```
PLAN-*.md
```
,
```
plan-*.md
```
,
```
TODO.md
```
,
```
prd.md
```
,
```
PRD.md
```
- 找到1个 → 使用该文件（告知用户检测到的文件名称）
- 找到多个 → 列出文件列表并请用户选择
- 未找到 → 进入下一步
使用当前对话上下文中讨论的计划。
若对话上下文中也无计划，请用户描述计划内容。

Step 2: Identify Project Environment

步骤2：识别项目环境

Collect project-specific information to embed in the PROMPT file.

If
CLAUDE.md
exists: Read it and extract:

Verification commands: Combine build, test, lint into a single chain (e.g.,
```
npm run lint && npm run build && npm test
```
)
Key code style rules (items to insert into the PROMPT's absolute rules
```
{CLAUDE_MD_RULES}
```
, max 3)

If
CLAUDE.md
does not exist: Infer from project structure:

```
package.json
```
→ npm/yarn commands
```
Makefile
```
/
```
Justfile
```
→ make/just commands
```
Cargo.toml
```
→ cargo commands
```
pyproject.toml
```
/
```
setup.py
```
→ python toolchain
If undetectable, ask the user for build/test commands

收集项目特定信息以嵌入到PROMPT文件中。

若存在
CLAUDE.md
文件：读取该文件并提取：

验证命令：将构建、测试、lint命令组合成一条链式命令（例如：
```
npm run lint && npm run build && npm test
```
）
关键代码风格规则（需插入到PROMPT的绝对规则
```
{CLAUDE_MD_RULES}
```
中，最多3条）

若不存在
CLAUDE.md
文件：从项目结构推断：

```
package.json
```
→ npm/yarn命令
```
Makefile
```
/
```
Justfile
```
→ make/just命令
```
Cargo.toml
```
→ cargo命令
```
pyproject.toml
```
/
```
setup.py
```
→ Python工具链
若无法检测，请用户提供构建/测试命令

Step 3: Analyze Plan

步骤3：分析计划

Extract the following from the plan:

Goal: What is being built
Non-goals: What will NOT be done in this task (to prevent Feature Invention)
Phase list: Ordered implementation steps
Key content per phase: Files to change, implementation details
Reference docs/files: Pattern references, design document paths
Completion criteria: Criteria for determining the entire task is complete

Completion criteria must be mechanically verifiable (e.g., command execution returns exit code 0). Do not use subjective criteria like "works well" or "looks clean".

从计划中提取以下信息：

目标：要构建的内容
非目标：本次任务中不会做的事情（防止功能冗余开发）
阶段列表：有序的实施步骤
各阶段关键内容：需修改的文件、实现细节
参考文档/文件：模式参考、设计文档路径
完成标准：确定整个任务完成的标准

完成标准必须可机械验证（例如：命令执行返回退出码0）。请勿使用“运行良好”或“看起来整洁”等主观标准。

Step 4: Phase Splitting

步骤4：阶段拆分

Split the plan into phases suitable for Ralph Loop iterations.

Splitting principles:

One iteration = exactly one phase. Processing 2+ phases is strictly forbidden.
When a phase is completed, immediately end the iteration. The next phase is handled in the next iteration.
Each phase must be the minimum unit that can independently pass verification.
Split phases that are too large, merge phases that are too small.

Size guideline (reference, not absolute):

If description needs 3+ sentences → candidate for splitting
If it's a single-line change to one file → candidate for merging with adjacent phase
The appropriate size is one the agent can implement + verify within a single context

max-iterations calculation:

number of phases + 2

+1: Buffer for automatic retry on verification failure
+1: Buffer for promise output iteration after final phase completion

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

拆分原则：

一次迭代 = 恰好一个阶段。严格禁止处理2个及以上阶段。
当一个阶段完成后，立即结束本次迭代。下一阶段将在下一次迭代中处理。
每个阶段必须是可独立通过验证的最小单元。
拆分过大的阶段，合并过小的阶段。

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

若阶段描述需要3句及以上文字 → 考虑拆分
若仅需对单个文件进行单行修改 → 考虑与相邻阶段合并
合适的规模是Agent可在单个上下文内完成实现+验证的内容

最大迭代次数计算：

阶段数量 + 2

+1：验证失败时自动重试的缓冲次数
+1：最终阶段完成后输出承诺的缓冲迭代次数

Step 5: Generate PROMPT File

步骤5：生成PROMPT文件

Use

references/prompt-template.md

as the base template and

references/iteration-procedure.md

as the iteration procedure block to generate the PROMPT file.

Create a

PROMPT-{kebab-case-name}.md

file in the project root.

Placeholder mapping:

Placeholder	Source	Fallback
`{goal title}`	Step 3	Ask user
`{project name}`	Project directory name or CLAUDE.md	Ask user
`{goal}`	Step 3	Ask user
`{CLAUDE_MD_RULES}`	Step 2 (CLAUDE.md rules)	Omit entire line if no CLAUDE.md
`{non-goals}`	Step 3 + non-goal writing rules for inference	Min 2 items
`{reference doc rows}`	Step 2-3	Omit entire reference docs section if 0 docs
`{iteration procedure}`	Entire `references/iteration-procedure.md`	—
`{checklist}`	Step 4 phase splitting result	—
`{verification command}`	Step 2 (project detection)	Ask user
`{COMPLETION_PROMISE}`	COMPLETION_PROMISE generation rules	—

Note: Example text that uses curly braces (such as the recording format for out-of-scope findings) should be left as-is without substitution.

以

references/prompt-template.md

为基础模板，

references/iteration-procedure.md

为迭代流程块，生成PROMPT文件。

在项目根目录创建

PROMPT-{kebab-case-name}.md

文件。

占位符映射：

占位符	来源	备选方案
`{goal title}`	步骤3	询问用户
`{project name}`	项目目录名称或CLAUDE.md	询问用户
`{goal}`	步骤3	询问用户
`{CLAUDE_MD_RULES}`	步骤2（CLAUDE.md规则）	若无CLAUDE.md则省略整行
`{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: Output Result

步骤6：输出结果

Provide the generated PROMPT file path and output the

/ralph-loop

command in the following format:

undefined

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

undefined

Generated File

生成的文件

{PROMPT file path}

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

{PROMPT文件路径}

执行前请检查生成的PROMPT文件，尤其注意验证命令和阶段结构。

Ralph Loop Execution Command

Ralph Loop执行命令

/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}"


Output the command block above so it can be copied and used directly.

---


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

---

Generation Rules

生成规则

Checklist Writing Rules

清单编写规则

Phase = iteration unit: A single
```
### Phase N
```
block is processed in one iteration
Sub-items = detailed tasks within a phase: Place 2-5
```
- [ ]
```
sub-items under each Phase
Sub-items should specify files to change and implementation details
Verification is not a checklist item — it runs automatically in STEP 4 of the iteration procedure. Use the project's build/test commands detected in Step 2

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

Non-Goal Writing Rules

非目标编写规则

In addition to items explicitly excluded by the plan, infer and add:

Refactoring outside the plan's scope
Unrequested test/documentation/configuration changes
Existing API or interface changes (if not specified in the plan)

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

计划范围外的重构
未被请求的测试/文档/配置变更
现有API或接口变更（若计划中未指定）

COMPLETION_PROMISE Generation Rules

COMPLETION_PROMISE生成规则

Uppercase English, space-separated
Briefly summarize the goal (e.g., "HELP OVERLAY COMPLETE", "AUTH REFACTOR DONE")

大写英文，空格分隔
简要总结目标（例如："HELP OVERLAY COMPLETE", "AUTH REFACTOR DONE"）