Back to Details

iterative-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Iterative Development Skill (Ralph Wiggum Integration)

迭代开发技能（Ralph Wiggum 集成）

Load with: base.md
Concept: Self-referential development loops where Claude iterates on the same task until completion criteria are met. Based on the Ralph Wiggum plugin.
加载方式：base.md
核心概念： 自引用开发循环，Claude 会针对同一任务进行迭代，直至满足完成条件。基于 Ralph Wiggum 插件 实现。

Core Philosophy

核心理念

┌─────────────────────────────────────────────────────────────┐
│  ITERATION > PERFECTION                                     │
│  ─────────────────────────────────────────────────────────  │
│  Don't aim for perfect on first try.                        │
│  Let the loop refine the work. Each iteration builds on     │
│  previous attempts visible in files and git history.        │
├─────────────────────────────────────────────────────────────┤
│  FAILURES ARE DATA                                          │
│  ─────────────────────────────────────────────────────────  │
│  Failed tests, lint errors, type mismatches are signals.    │
│  Use them to guide the next iteration.                      │
├─────────────────────────────────────────────────────────────┤
│  CLEAR COMPLETION CRITERIA                                  │
│  ─────────────────────────────────────────────────────────  │
│  Define exactly what "done" looks like.                     │
│  Tests passing. Coverage met. Lint clean.                   │
│  No ambiguity about when to stop.                           │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│  ITERATION > PERFECTION                                     │
│  ─────────────────────────────────────────────────────────  │
│  不要追求一次就做到完美。                                   │
│  让循环来优化工作成果。每次迭代都基于文件和 git 历史中可见的│
│  之前的尝试进行构建。                                       │
├─────────────────────────────────────────────────────────────┤
│  FAILURES ARE DATA                                          │
│  ─────────────────────────────────────────────────────────  │
│  测试失败、Lint 错误、类型不匹配都是信号。                  │
│  利用它们来指导下一次迭代。                                 │
├─────────────────────────────────────────────────────────────┤
│  CLEAR COMPLETION CRITERIA                                  │
│  ─────────────────────────────────────────────────────────  │
│  准确定义“完成”的标准。                                     │
│  测试通过、达到覆盖率要求、Lint 检查无问题。                │
│  停止时机清晰明确，无歧义。                                 │
└─────────────────────────────────────────────────────────────┘

Installing Ralph Wiggum Plugin

安装 Ralph Wiggum 插件

bash
undefined
bash
undefined

Clone the plugin

Clone the plugin

git clone https://github.com/anthropics/claude-code.git /tmp/claude-code cp -r /tmp/claude-code/plugins/ralph-wiggum ~/.claude/plugins/
git clone https://github.com/anthropics/claude-code.git /tmp/claude-code cp -r /tmp/claude-code/plugins/ralph-wiggum ~/.claude/plugins/

Or add to project-local plugins

Or add to project-local plugins

mkdir -p .claude/plugins cp -r /tmp/claude-code/plugins/ralph-wiggum .claude/plugins/

---
mkdir -p .claude/plugins cp -r /tmp/claude-code/plugins/ralph-wiggum .claude/plugins/

---

How It Works

工作原理

┌─────────────────────────────────────────────────────────────┐
│  1. /ralph-loop "Your task prompt" --max-iterations 20      │
├─────────────────────────────────────────────────────────────┤
│  2. Claude works on task                                    │
├─────────────────────────────────────────────────────────────┤
│  3. Claude attempts to exit                                 │
├─────────────────────────────────────────────────────────────┤
│  4. Stop hook blocks exit, feeds SAME PROMPT back           │
├─────────────────────────────────────────────────────────────┤
│  5. Claude sees modified files + git history from before    │
├─────────────────────────────────────────────────────────────┤
│  6. Claude iterates and improves                            │
├─────────────────────────────────────────────────────────────┤
│  7. Loop continues until:                                   │
│     • Completion promise detected: <promise>DONE</promise>  │
│     • Max iterations reached                                │
└─────────────────────────────────────────────────────────────┘
Key insight: The prompt never changes. Only the file state evolves. Claude reads its own previous work and refines it.
┌─────────────────────────────────────────────────────────────┐
│  1. /ralph-loop "Your task prompt" --max-iterations 20      │
├─────────────────────────────────────────────────────────────┤
│  2. Claude works on task                                    │
├─────────────────────────────────────────────────────────────┤
│  3. Claude attempts to exit                                 │
├─────────────────────────────────────────────────────────────┤
│  4. Stop hook blocks exit, feeds SAME PROMPT back           │
├─────────────────────────────────────────────────────────────┤
│  5. Claude sees modified files + git history from before    │
├─────────────────────────────────────────────────────────────┤
│  6. Claude iterates and improves                            │
├─────────────────────────────────────────────────────────────┤
│  7. Loop continues until:                                   │
│     • Completion promise detected: <promise>DONE</promise>  │
│     • Max iterations reached                                │
└─────────────────────────────────────────────────────────────┘
关键洞察： 提示词始终保持不变，只有文件状态会演进。Claude 会读取自己之前的工作成果并进行优化。

TDD-Integrated Prompt Templates

集成TDD的提示词模板

Feature Development (TDD Loop)

功能开发（TDD循环）

bash
/ralph-loop "
bash
/ralph-loop "

Task: [Feature Name]

任务: [功能名称]

Requirements

需求

  • [Requirement 1]
  • [Requirement 2]
  • [Requirement 3]
  • [需求1]
  • [需求2]
  • [需求3]

TDD Workflow (MUST FOLLOW)

TDD工作流（必须遵循）

  1. Write failing tests based on requirements
  2. Run tests - verify they FAIL (RED phase)
  3. Implement minimum code to pass tests
  4. Run tests - verify they PASS (GREEN phase)
  5. Run lint and typecheck
  6. If any failures, debug and fix
  7. Repeat until all green
  1. 根据需求编写失败的测试用例
  2. 运行测试 - 验证测试失败（RED阶段）
  3. 实现最小化代码以通过测试
  4. 运行测试 - 验证测试通过（GREEN阶段）
  5. 运行Lint检查和类型校验
  6. 如果有任何失败，进行调试和修复
  7. 重复直至全部通过

Completion Criteria

完成标准

  • All tests passing
  • Coverage >= 80%
  • Lint clean (no errors)
  • TypeScript/type check passing
  • 所有测试通过
  • 测试覆盖率 ≥ 80%
  • Lint检查无错误
  • TypeScript/类型校验通过

Exit Condition

退出条件

When ALL criteria above are TRUE, output: <promise>ALL TESTS PASSING AND LINT CLEAN</promise> " --completion-promise "ALL TESTS PASSING AND LINT CLEAN" --max-iterations 30
undefined
当上述所有标准均满足时，输出： <promise>ALL TESTS PASSING AND LINT CLEAN</promise> " --completion-promise "ALL TESTS PASSING AND LINT CLEAN" --max-iterations 30
undefined

Bug Fix (TDD Loop)

Bug修复（TDD循环）

bash
/ralph-loop "
bash
/ralph-loop "

Bug: [Bug Description]

Bug: [Bug描述]

Reproduction

复现步骤

  1. [Step 1]
  2. [Step 2]
  3. Observe: [Wrong behavior]
  4. Expected: [Correct behavior]
  1. [步骤1]
  2. [步骤2]
  3. 观察到：[错误行为]
  4. 预期：[正确行为]

TDD Bug Fix Workflow (MUST FOLLOW)

TDD Bug修复工作流（必须遵循）

  1. Run existing tests - note if any catch the bug
  2. Write a failing test that reproduces the bug
  3. Run test - verify it FAILS (proves test catches bug)
  4. Fix the bug with minimum code change
  5. Run test - verify it PASSES
  6. Run FULL test suite for regressions
  7. Run lint and typecheck
  8. If any failures, debug and fix
  9. Repeat until all green
  1. 运行现有测试 - 记录是否有测试能捕获该Bug
  2. 编写一个能复现Bug的失败测试用例
  3. 运行测试 - 验证测试失败（证明测试能捕获Bug）
  4. 用最小化代码变更修复Bug
  5. 运行测试 - 验证测试通过
  6. 运行完整测试套件检查是否有回归
  7. 运行Lint检查和类型校验
  8. 如果有任何失败，进行调试和修复
  9. 重复直至全部通过

Completion Criteria

完成标准

  • New test for bug exists
  • New test passes
  • All existing tests pass
  • No regressions
  • Lint clean
  • 存在针对该Bug的新测试用例
  • 新测试用例通过
  • 所有现有测试通过
  • 无回归问题
  • Lint检查无错误

Exit Condition

退出条件

When ALL criteria are TRUE, output: <promise>BUG FIXED WITH TEST</promise> " --completion-promise "BUG FIXED WITH TEST" --max-iterations 25
undefined
当所有标准均满足时，输出： <promise>BUG FIXED WITH TEST</promise> " --completion-promise "BUG FIXED WITH TEST" --max-iterations 25
undefined

Refactoring (Safe Loop)

代码重构（安全循环）

bash
/ralph-loop "
bash
/ralph-loop "

Refactor: [What to refactor]

重构: [重构内容]

Goals

目标

  • [Goal 1: e.g., Extract function, reduce complexity]
  • [Goal 2: e.g., Improve naming]
  • [Goal 3: e.g., Split file if > 200 lines]
  • [目标1：例如，提取函数、降低复杂度]
  • [目标2：例如，优化命名]
  • [目标3：例如，若文件超过200行则拆分]

Safety Constraints

安全约束

  • All existing tests MUST continue to pass
  • No behavior changes (refactor only)
  • Coverage must not decrease
  • 所有现有测试必须继续通过
  • 不得改变行为（仅重构）
  • 测试覆盖率不得降低

Workflow

工作流

  1. Run all tests - establish baseline (must pass)
  2. Make ONE refactoring change
  3. Run tests - must still pass
  4. Run lint and typecheck
  5. If failures, REVERT and try different approach
  6. Commit working refactor
  7. Repeat for next change
  1. 运行所有测试 - 建立基准（必须全部通过）
  2. 进行一次重构变更
  3. 运行测试 - 必须仍然通过
  4. 运行Lint检查和类型校验
  5. 如果失败，回滚并尝试其他方法
  6. 提交可行的重构变更
  7. 重复进行下一次变更

Completion Criteria

完成标准

  • All refactoring goals met
  • All tests passing
  • Coverage same or higher
  • Lint clean
  • 所有重构目标达成
  • 所有测试通过
  • 测试覆盖率保持不变或提升
  • Lint检查无错误

Exit Condition

退出条件

<promise>REFACTOR COMPLETE ALL TESTS GREEN</promise> " --completion-promise "REFACTOR COMPLETE ALL TESTS GREEN" --max-iterations 20
undefined
<promise>REFACTOR COMPLETE ALL TESTS GREEN</promise> " --completion-promise "REFACTOR COMPLETE ALL TESTS GREEN" --max-iterations 20
undefined

API Development

API开发

bash
/ralph-loop "
bash
/ralph-loop "

Task: Build [API Name] API

任务: 构建 [API名称] API

Endpoints Required

所需端点

  • POST /api/resource - Create
  • GET /api/resource - List
  • GET /api/resource/:id - Get one
  • PUT /api/resource/:id - Update
  • DELETE /api/resource/:id - Delete
  • POST /api/resource - 创建
  • GET /api/resource - 列表
  • GET /api/resource/:id - 获取单个资源
  • PUT /api/resource/:id - 更新
  • DELETE /api/resource/:id - 删除

Requirements

需求

  • Input validation (Zod/Pydantic)
  • Error handling with proper status codes
  • Tests for each endpoint
  • OpenAPI/Swagger docs
  • 输入验证（Zod/Pydantic）
  • 带有正确状态码的错误处理
  • 每个端点的测试用例
  • OpenAPI/Swagger文档

TDD Workflow

TDD工作流

  1. Write integration tests for each endpoint
  2. Run tests - all should FAIL
  3. Implement endpoints one by one
  4. Run tests after each endpoint
  5. Continue until all pass
  6. Add validation and error handling
  7. Run full test suite
  8. Generate API docs
  1. 为每个端点编写集成测试
  2. 运行测试 - 全部应该失败
  3. 逐个实现端点
  4. 每个端点实现后运行测试
  5. 持续直至全部通过
  6. 添加验证和错误处理
  7. 运行完整测试套件
  8. 生成API文档

Completion Criteria

完成标准

  • All endpoint tests passing
  • Input validation working
  • Error responses correct
  • Coverage >= 80%
  • Lint clean
  • 所有端点测试通过
  • 输入验证正常工作
  • 错误响应正确
  • 测试覆盖率 ≥ 80%
  • Lint检查无错误

Exit Condition

退出条件

<promise>API COMPLETE WITH TESTS</promise> " --completion-promise "API COMPLETE WITH TESTS" --max-iterations 40

---
<promise>API COMPLETE WITH TESTS</promise> " --completion-promise "API COMPLETE WITH TESTS" --max-iterations 40

---

Prompt Writing Rules

提示词编写规则

1. Clear Completion Criteria (REQUIRED)

1. 明确的完成标准（必填）

markdown
❌ BAD: "Build a todo API and make it good."

✅ GOOD:
markdown
❌ 错误示例: "构建一个待办事项API并确保质量良好。"

✅ 正确示例:

Completion Criteria

完成标准

  • CRUD endpoints implemented
  • All tests passing
  • Input validation working
  • Coverage >= 80%
  • Lint clean
  • 实现CRUD端点
  • 所有测试通过
  • 输入验证正常工作
  • 测试覆盖率 ≥ 80%
  • Lint检查无错误

Exit Condition

退出条件

<promise>ALL TESTS PASSING</promise>
undefined
<promise>ALL TESTS PASSING</promise>
undefined

2. Always Set Max Iterations

2. 始终设置最大迭代次数

bash
undefined
bash
undefined

❌ DANGEROUS - runs forever

❌ 危险 - 循环会无限运行

/ralph-loop "Build something"
/ralph-loop "构建某个功能"

✅ SAFE - stops after 30 iterations

✅ 安全 - 30次迭代后停止

/ralph-loop "Build something" --max-iterations 30
undefined
/ralph-loop "构建某个功能" --max-iterations 30
undefined

3. Include TDD in Every Prompt

3. 在提示词中包含TDD流程

markdown
undefined
markdown
undefined

TDD Workflow (MUST FOLLOW)

TDD工作流（必须遵循）

  1. Write failing tests first
  2. Verify tests fail
  3. Implement feature
  4. Verify tests pass
  5. Run lint + typecheck
  6. Repeat if failures
undefined
  1. 先编写失败的测试用例
  2. 验证测试失败
  3. 实现功能
  4. 验证测试通过
  5. 运行Lint检查 + 类型校验
  6. 如果失败则重复
undefined

4. Break Large Tasks into Phases

4. 将大型任务拆分为多个阶段

markdown
undefined
markdown
undefined

Phase 1: Authentication

阶段1: 身份验证

  • Login endpoint with JWT
  • Tests passing
  • Output: <promise>AUTH COMPLETE</promise>
  • 基于JWT的登录端点
  • 测试通过
  • 输出: <promise>AUTH COMPLETE</promise>

Phase 2: User CRUD (after Phase 1)

阶段2: 用户CRUD（阶段1完成后）

  • User endpoints
  • Tests passing
  • Output: <promise>USERS COMPLETE</promise>
  • 用户端点
  • 测试通过
  • 输出: <promise>USERS COMPLETE</promise>

Phase 3: Products (after Phase 2)

阶段3: 产品管理（阶段2完成后）

...
undefined
...
undefined

5. Include Fallback Behavior

5. 包含回退行为

markdown
undefined
markdown
undefined

If Stuck After 15 Iterations

若15次迭代后仍受阻

  • Document what's blocking progress
  • List approaches attempted
  • Suggest alternative approaches
  • Output: <promise>BLOCKED NEED HELP</promise>

---
  • 记录阻碍进度的问题
  • 列出已尝试的方法
  • 建议替代方案
  • 输出: <promise>BLOCKED NEED HELP</promise>

---

Error Classification (Critical for Loops)

错误分类（循环的关键）

Not all test failures are equal. Claude MUST classify errors before iterating.
并非所有测试失败都相同。Claude在迭代前必须对错误进行分类。

Error Types

错误类型

TypeExamplesClaude Can Fix?Action
Code ErrorLogic bug, wrong algorithm, missing validation✅ YESContinue loop
Type ErrorWrong types, missing properties✅ YESContinue loop
Test ErrorWrong assertion, incomplete test✅ YESContinue loop
Access ErrorMissing API key, DB connection refused❌ NOSTOP + report
Permission ErrorFile access denied, auth failed❌ NOSTOP + report
Environment ErrorMissing dependency, wrong Node version❌ NOSTOP + report
Network ErrorService unreachable, timeout❌ NOSTOP + report
类型示例Claude能否修复？操作
代码错误逻辑Bug、错误算法、缺失验证✅ 是继续循环
类型错误错误类型、缺失属性✅ 是继续循环
测试错误错误断言、测试不完整✅ 是继续循环
访问错误缺失API密钥、数据库连接拒绝❌ 否停止 + 报告
权限错误文件访问被拒绝、身份验证失败❌ 否停止 + 报告
环境错误缺失依赖、Node版本错误❌ 否停止 + 报告
网络错误服务不可达、超时❌ 否停止 + 报告

Error Detection Pattern

错误检测模式

markdown
undefined
markdown
undefined

Before Each Iteration

每次迭代前

  1. Run tests
  2. If tests fail, classify the error:
    Code/Logic Error? (Claude can fix)
    • "Expected X but received Y"
    • "TypeError: cannot read property"
    • "AssertionError" → CONTINUE LOOP
    Access/Environment Error? (Human must fix)
    • "ECONNREFUSED" (DB not running)
    • "401 Unauthorized" (bad API key)
    • "ENOENT" (file/path not found)
    • "EACCES" (permission denied)
    • "MODULE_NOT_FOUND" (missing package)
    • "Connection timeout" → STOP LOOP + OUTPUT BLOCKER
undefined
  1. 运行测试
  2. 如果测试失败，对错误进行分类：
    代码/逻辑错误？（Claude可修复）
    • "预期X但收到Y"
    • "TypeError: 无法读取属性"
    • "AssertionError" → 继续循环
    访问/环境错误？（需人工修复）
    • "ECONNREFUSED"（数据库未运行）
    • "401 Unauthorized"（无效API密钥）
    • "ENOENT"（文件/路径不存在）
    • "EACCES"（权限被拒绝）
    • "MODULE_NOT_FOUND"（缺失包）
    • "连接超时" → 停止循环 + 输出阻碍信息
undefined

Blocker Report Format

阻碍报告格式

When Claude detects an access/environment error, output this IMMEDIATELY:
markdown
undefined
当Claude检测到访问/环境错误时，立即输出以下内容：
markdown
undefined

🛑 LOOP BLOCKED - Human Action Required

🛑 循环受阻 - 需要人工干预

Error Type: Access/Environment (cannot be fixed by code changes)
Error Message: ``` ECONNREFUSED 127.0.0.1:5432 - Connection refused ```
Root Cause: PostgreSQL database is not running or not accessible.
Required Human Actions:
  1. Start PostgreSQL: 
    brew services start postgresql
  2. Verify connection: 
    psql -U postgres -c "SELECT 1"
  3. Check DATABASE_URL in .env matches running instance
After Fixing: Run 
/ralph-loop
again with the same prompt, or tell me to continue.
<promise>BLOCKED ENVIRONMENT</promise>
undefined
错误类型: 访问/环境错误（无法通过代码变更修复）
错误信息: ``` ECONNREFUSED 127.0.0.1:5432 - Connection refused ```
根本原因: PostgreSQL数据库未运行或无法访问。
所需人工操作:
  1. 启动PostgreSQL: 
    brew services start postgresql
  2. 验证连接: 
    psql -U postgres -c "SELECT 1"
  3. 检查.env中的DATABASE_URL是否与运行实例匹配
修复后: 再次运行
/ralph-loop
并使用相同提示词，或告知我继续。
<promise>BLOCKED ENVIRONMENT</promise>
undefined

Common Blockers Checklist

常见阻碍检查表

Error PatternLikely CauseHuman Fix
ECONNREFUSED :5432
PostgreSQL not running
brew services start postgresql
ECONNREFUSED :6379
Redis not running
brew services start redis
ECONNREFUSED :27017
MongoDB not running
brew services start mongodb
401 Unauthorized
Invalid/missing API keyCheck 
.env
file
403 Forbidden
Wrong permissions/scopesCheck API key permissions
ENOENT .env
Missing .env fileCreate from 
.env.example
MODULE_NOT_FOUND
Missing npm packageRun 
npm install
ENOMEM
Out of memoryClose other apps, increase swap
错误模式可能原因人工修复方法
ECONNREFUSED :5432
PostgreSQL未运行
brew services start postgresql
ECONNREFUSED :6379
Redis未运行
brew services start redis
ECONNREFUSED :27017
MongoDB未运行
brew services start mongodb
401 Unauthorized
API密钥无效/缺失检查
.env
文件
403 Forbidden
权限/范围错误检查API密钥权限
ENOENT .env
缺失.env文件从
.env.example
创建
MODULE_NOT_FOUND
缺失npm包运行
npm install
ENOMEM
内存不足关闭其他应用、增加交换空间

Updated Prompt Template with Error Handling

包含错误处理的更新提示词模板

bash
/ralph-loop "
bash
/ralph-loop "

Task: [Feature Name]

任务: [功能名称]

Requirements

需求

  • [Requirements here]
  • [需求内容]

TDD Workflow

TDD工作流

  1. Write failing tests
  2. Run tests
  3. CLASSIFY ERROR:
    • Code/logic error → fix and continue
    • Access/env error → STOP and report blocker
  4. Implement fix
  5. Run tests again
  6. Repeat until pass or blocked
  1. 编写失败的测试用例
  2. 运行测试
  3. 错误分类:
    • 代码/逻辑错误 → 修复并继续
    • 访问/环境错误 → 停止并报告阻碍
  4. 实现修复
  5. 再次运行测试
  6. 重复直至通过或受阻

Completion Criteria

完成标准

  • All tests passing
  • Lint clean
  • 所有测试通过
  • Lint检查无错误

Exit Conditions

退出条件

  • SUCCESS: <promise>FEATURE COMPLETE</promise>
  • BLOCKED: <promise>BLOCKED ENVIRONMENT</promise> " --completion-promise "FEATURE COMPLETE" --max-iterations 25
undefined
  • 成功: <promise>FEATURE COMPLETE</promise>
  • 受阻: <promise>BLOCKED ENVIRONMENT</promise> " --completion-promise "FEATURE COMPLETE" --max-iterations 25
undefined

Multiple Completion Promises

多完成承诺

Since Ralph only supports one 
--completion-promise
, handle blockers in prompt:
markdown
undefined
由于Ralph仅支持一个
--completion-promise
，在提示词中处理受阻情况：
markdown
undefined

Exit Logic

退出逻辑

IF all tests pass AND lint clean: Output: <promise>COMPLETE</promise>
IF access/environment error detected: Output blocker report (see format above) Output: <promise>COMPLETE</promise> # Exits loop, user sees blocker report

---
如果所有测试通过且Lint检查无问题: 输出: <promise>COMPLETE</promise>
如果检测到访问/环境错误: 输出阻碍报告（参见上述格式） 输出: <promise>COMPLETE</promise> # 退出循环，用户可看到阻碍报告

---

When to Use Ralph Loops

何时使用Ralph循环

Good For

适用场景

Use CaseWhy It Works
TDD feature developmentTests provide clear pass/fail feedback
Bug fixesClear reproduction → test → fix cycle
RefactoringTests ensure no regressions
API developmentEach endpoint is independently testable
Greenfield projectsCan iterate without human oversight
Getting tests to passClear success criteria
使用场景为何适用
TDD功能开发测试提供明确的通过/失败反馈
Bug修复清晰的复现→测试→修复流程
代码重构测试确保无回归问题
API开发每个端点可独立测试
全新项目无需人工干预即可迭代
确保测试通过明确的成功标准

Not Good For

不适用场景

Use CaseWhy It Fails
Subjective design decisionsNo clear "done" criteria
UI/UX workRequires human judgment
One-shot operationsNo need for iteration
Unclear requirementsWill loop forever
Production debuggingNeeds human oversight
使用场景为何不适用
主观设计决策无明确的“完成”标准
UI/UX工作需要人工判断
一次性操作无需迭代
需求不明确会无限循环
生产环境调试需要人工监督

Monitoring and Control

监控与控制

Check Current Iteration

查看当前迭代次数

bash
grep '^iteration:' .claude/ralph-loop.local.md
bash
grep '^iteration:' .claude/ralph-loop.local.md

View Full State

查看完整状态

bash
head -10 .claude/ralph-loop.local.md
bash
head -10 .claude/ralph-loop.local.md

Cancel Loop

取消循环

bash
/cancel-ralph
bash
/cancel-ralph

State File Location

状态文件位置

.claude/ralph-loop.local.md
.claude/ralph-loop.local.md

Integration with Claude Bootstrap

与Claude Bootstrap集成

Project Structure Addition

项目结构新增内容

project/
├── _project_specs/
│   └── ralph-prompts/           # Saved Ralph prompts
│       ├── feature-template.md
│       ├── bug-fix-template.md
│       └── refactor-template.md
└── .claude/
    └── ralph-loop.local.md      # Active loop state (gitignored)
project/
├── _project_specs/
│   └── ralph-prompts/           # 保存的Ralph提示词
│       ├── feature-template.md
│       ├── bug-fix-template.md
│       └── refactor-template.md
└── .claude/
    └── ralph-loop.local.md      # 活跃循环状态（已加入git忽略）

Gitignore Addition

Gitignore新增内容

gitignore
undefined
gitignore
undefined

Ralph loop state (session-specific)

Ralph循环状态（会话特定）

.claude/ralph-loop.local.md
undefined
.claude/ralph-loop.local.md
undefined

Todo Integration

待办事项集成

markdown
undefined
markdown
undefined

[TODO-042] Add email validation

[TODO-042] 添加邮箱验证

Status: in-progress Method: Ralph loop
状态: 进行中 方法: Ralph循环

Ralph Prompt

Ralph提示词

/ralph-loop "..." --max-iterations 20 --completion-promise "..."
/ralph-loop "..." --max-iterations 20 --completion-promise "..."

TDD Execution Log

TDD执行日志

IterationTestsLintStatus
10/5 passerrorsRED
22/5 passerrorsRED
35/5 passcleanGREEN ✓
迭代次数测试结果Lint结果状态
10/5通过有错误RED
22/5通过有错误RED
35/5通过无错误GREEN ✓

Completion

完成情况

  • Iterations used: 3/20
  • Promise detected: <promise>ALL TESTS PASSING</promise>

---
  • 使用迭代次数: 3/20
  • 检测到承诺: <promise>ALL TESTS PASSING</promise>

---

Anti-Patterns

反模式

  • ❌ No max iterations - Loop runs forever
  • ❌ Vague completion criteria - Can't determine when done
  • ❌ No TDD in prompt - No objective success metric
  • ❌ Lying to exit - Outputting false promise to escape
  • ❌ Manual intervention - Loop is designed for autonomy
  • ❌ Skipping test verification - Tests must fail first
  • ❌ 未设置最大迭代次数 - 循环会无限运行
  • ❌ 模糊的完成标准 - 无法确定何时完成
  • ❌ 提示词中未包含TDD - 无客观成功指标
  • ❌ 伪造承诺以退出 - 输出虚假承诺来逃离循环
  • ❌ 手动干预 - 循环设计为自主运行
  • ❌ 跳过测试验证 - 测试必须先失败

Example: Real TDD Ralph Session

示例：真实的TDD Ralph会话

bash
/ralph-loop "
bash
/ralph-loop "

Task: Add email validation to signup form

任务: 为注册表单添加邮箱验证

Requirements

需求

  • Email field shows error for invalid format
  • Error clears when user fixes email
  • Form cannot submit with invalid email
  • Valid emails pass without error
  • 邮箱格式无效时显示错误
  • 用户修复邮箱后错误消失
  • 邮箱无效时表单无法提交
  • 有效邮箱可正常通过

Test Cases

测试用例

InputExpected
user@example.comValid
user@sub.example.comValid
notanemailError
user@Error
@example.comError
输入预期结果
user@example.com有效
user@sub.example.com有效
notanemail错误
user@错误
@example.com错误

TDD Workflow

TDD工作流

  1. Create test file: signup-validation.test.ts
  2. Write tests for ALL test cases above
  3. Run: npm test -- --grep 'email validation'
  4. Verify: All 5 tests FAIL (RED)
  5. Implement: validateEmail function
  6. Run: npm test -- --grep 'email validation'
  7. Verify: All 5 tests PASS (GREEN)
  8. Run: npm run lint && npm run typecheck
  9. If any errors, fix and re-run
  10. When all green, output completion
  1. 创建测试文件: signup-validation.test.ts
  2. 编写上述所有测试用例
  3. 运行: npm test -- --grep 'email validation'
  4. 验证: 全部5个测试失败（RED）
  5. 实现: validateEmail函数
  6. 运行: npm test -- --grep 'email validation'
  7. 验证: 全部5个测试通过（GREEN）
  8. 运行: npm run lint && npm run typecheck
  9. 如果有任何错误，修复并重新运行
  10. 全部通过时输出完成信息

Completion Criteria

完成标准

  • 5 tests exist for email validation
  • All 5 tests passing
  • Lint clean
  • TypeCheck passing
  • 存在5个邮箱验证测试用例
  • 全部5个测试通过
  • Lint检查无错误
  • TypeCheck通过

Exit Condition

退出条件

<promise>EMAIL VALIDATION COMPLETE</promise> " --completion-promise "EMAIL VALIDATION COMPLETE" --max-iterations 15

---
<promise>EMAIL VALIDATION COMPLETE</promise> " --completion-promise "EMAIL VALIDATION COMPLETE" --max-iterations 15

---

Checklist

检查清单

Before Starting Ralph Loop

启动Ralph循环前

  • Clear completion criteria defined
  • --max-iterations
    set (safety net)
  • --completion-promise
    set
  • TDD workflow included in prompt
  • Test cases defined
  • 定义了明确的完成标准
  • 设置了
    --max-iterations
    （安全保障）
  • 设置了
    --completion-promise
  • 提示词中包含了TDD工作流
  • 定义了测试用例

During Loop

循环运行中

  • Monitor iteration count
  • Check test results each iteration
  • Watch for stuck patterns
  • 监控迭代次数
  • 每次迭代检查测试结果
  • 留意停滞模式

After Completion

完成后

  • Verify tests actually pass
  • Run full test suite
  • Check coverage threshold
  • Commit changes
  • 验证测试确实通过
  • 运行完整测试套件
  • 检查覆盖率阈值
  • 提交变更