ralph-loop

⚠️ WARNING：此技能已弃用，取而代之的是使用 Python 编排脚本的新命令 ralph-loop-v2。 旧的 /specs:ralph-loop 命令即将移除。请迁移到新命令。

Ralph Loop — Python 编排器

⚠️ IMPORTANT：此技能使用 Python 编排脚本。请勿执行任意 bash 命令。只能使用 Bash 运行 ralph_loop.py。所有任务命令（例如 /developer-kit-specs:specs.task-implementation）都会显示给用户，由用户手动执行。

概述

Ralph Loop 将 Geoffrey Huntley 的“Ralph Wiggum as a Software Engineer”技术应用于规范驱动开发。它使用一个 Python 编排脚本来管理状态机：每次调用执行一个步骤，状态保存在 fix_plan.json 中。

关键见解：在一次调用中完成实现、审查和同步，会导致上下文窗口爆满。解决方案：每次循环迭代只执行一个步骤，将状态保存到 fix_plan.json，然后停止。下一次迭代会从已保存的状态继续。

关键改进：Python 脚本 ralph_loop.py 负责所有状态管理、任务选择和命令生成。它不会直接执行任务命令，而是显示应在 CLI 中执行的正确命令。

适用场景

• 用户运行 /loop 命令执行重复自动化任务
• 用户要求“自动化实现”或“循环运行任务”
• 用户希望“逐步遍历任务”或“运行工作流自动化”
• 用户需要在多个 SDD 命令之间“管理上下文窗口”
• 用户希望从 TASK-N 到 TASK-M“处理任务范围”
• 用户需要多 Agent 支持（不同任务使用不同 CLI）

架构

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   ralph_loop.py │────▶│   fix_plan.json │────▶│  User executes  │
│   (orchestrator)│     │   (state file)  │     │  command in CLI │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                                               │
         │                                               ▼
         │                                      ┌─────────────────┐
         └──────────────────────────────────────│   Task result   │
                                                │   (success/     │
                                                │   failure)      │
                                                └─────────────────┘

单步流程：

1. 运行 ralph_loop.py --action=loop
2. 脚本读取 fix_plan.json 并确定当前步骤
3. 脚本显示要执行的命令（例如 /developer-kit-specs:specs.task-implementation）
4. 用户在其 CLI 中执行该命令
5. 用户再次运行 ralph_loop.py --action=loop
6. 脚本根据结果更新状态并显示下一条命令

状态机

fix_plan.json state machine:
┌─────────────────────────────────────────────────────────────┐
│  state: "init"                                            │
│    → --action=start: Initialize fix_plan.json              │
│    → Load tasks from tasks/TASK-*.md files                │
│    → Apply task_range filter                              │
│                                                             │
│  state: "choose_task"                                      │
│    → Pick next pending task (within range, deps satisfied)│
│    → No tasks in range → state: "complete"               │
│    → Task found → state: "implementation"                │
│                                                             │
│  state: "implementation"                                  │
│    → Show /developer-kit-specs:specs.task-implementation command             │
│    → User executes, then runs loop again                  │
│    → Next state: "review"                                │
│                                                             │
│  state: "review"                                          ││    → Show /developer-kit-specs:specs.task-implementation --action=cleanup command│},{find:                    │
│    → User reviews results, then runs loop again          │
│    → Issues found → state: "fix" (retry ≤ 3)             │
│    → Clean → state: "cleanup"                            │
│                                                             │
│  state: "fix"                                             │
│    → Show commands to fix issues                         │
│    → User applies fixes, then runs loop again            │
│    → Next state: "review"                                │
│                                                             │
│  state: "cleanup"                                         │
│    → Show /developer-kit-specs:specs.task-implementation --action=cleanup command│
│    → Next state: "sync"                                  │
│                                                             │
│  state: "sync"                                            │
│    → Show /developer-kit-specs:specs.sync command             │
│    → Next state: "update_done"                           │
│                                                             │
│  state: "update_done"                                     │
│    → Mark task done, commit git changes                  │
│    → Re-evaluate dependencies                            │
│    → state: "choose_task"                                │
│                                                             │
│  state: "complete" | "failed"                            │
│    → Print result, stop                                   │
└─────────────────────────────────────────────────────────────┘

文件位置要求

⚠️ CRITICAL：fix_plan.json 文件必须始终位于：

docs/specs/[ID-feature]/_ralph_loop/fix_plan.json

脚本会强制执行此要求，以防止大模型在错误位置创建文件。

迁移：如果你的规范文件夹根目录中有旧版 fix_plan.json，脚本会在首次运行时自动将其迁移到 _ralph_loop/。

使用说明

阶段 1：初始化

运行带有 --action=start 的 Python 脚本，扫描任务文件并在正确位置创建 fix_plan.json：

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-036 \
  --to-task=TASK-041

阶段 2：执行循环步骤

运行带有 --action=loop 的脚本，获取当前状态和要执行的命令：

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/

脚本会显示当前步骤要执行的准确命令。在 CLI 中执行该命令，然后再次运行循环命令。

阶段 3：推进状态（手动）

执行显示的命令后，手动推进到下一步：

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=next \
  --spec=docs/specs/001-feature/

这会将 fix_plan.json 更新到下一状态（例如，从 implementation → review）。

阶段 4：监控进度

随时使用 --action=status 查看状态：

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=status \
  --spec=docs/specs/001-feature/

快速开始

1. 初始化

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-036 \
  --to-task=TASK-041 \
  --agent=claude

2. 运行循环

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/

脚本会显示要执行的命令。运行该命令，然后再次运行循环。

3. 查看状态

python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=status \
  --spec=docs/specs/001-feature/

参数

参数	描述
--action	start（初始化）、loop（运行一个步骤）、status、resume、next（推进步骤）
--spec	规范文件夹路径（例如 docs/specs/001-feature/）
--from-task	任务范围起始处（例如 TASK-036）
--to-task	任务范围结束处（例如 TASK-041）
--agent	默认 Agent：claude、codex、copilot、kimi、gemini、glm4、minimax
--no-commit	跳过 git 提交（用于测试）

步骤详情

步骤 1：初始化（--action=start）

脚本：

1. 扫描规范文件夹中的 tasks/TASK-*.md 文件
2. 从 YAML frontmatter 中提取元数据（id、title、status、lang、dependencies、agent）
3. 应用 --from-task 和 --to-task 筛选条件
4. 创建包含完整状态的 fix_plan.json

步骤 2：选择任务（choose_task）

脚本：

1. 查找范围内待处理的任务
2. 检查依赖项是否已满足
3. 选择下一个任务
4. 使用 current_task 更新 fix_plan.json
5. 显示要执行的命令

步骤 3：实施（implementation）

脚本显示：

→ Implementation: TASK-037

Execute:
  /developer-kit-specs:specs.task-implementation --task=TASK-037

After execution, update state:
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/

步骤 4：审查（review）

脚本显示：

→ Review: TASK-037 | Retry: 0/3

Execute:
  /developer-kit-specs:specs.task-review --task=TASK-037

Review the generated review report, then update state:
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/

步骤 5：修复（fix）——审查未通过时

如果发现问题，脚本会显示修复说明。完成修复后，用户再次运行循环。

步骤 6：清理（cleanup）

脚本显示：

→ Cleanup: TASK-037

Execute:
  /developer-kit-specs:specs.task-implementation --task=TASK-037 --action=cleanup

步骤 7：同步（sync）

脚本显示：

→ Sync: TASK-037

Execute:
  /developer-kit-specs:specs.sync docs/specs/001-feature/ --after-task=TASK-037

步骤 8：更新完成状态（update_done）

脚本：

1. 在 fix_plan.json 中将任务标记为已完成
2. 提交 Git 更改（除非指定了 --no-commit）
3. 更新迭代次数
4. 返回 choose_task

多 Agent 支持

为所有任务指定默认 Agent

python3 ralph_loop.py --action=start --spec=... --agent=codex

为每个任务指定 Agent

在任务文件的 YAML frontmatter 中指定 Agent：

---
id: TASK-036
title: Refactor user service
status: pending
lang: java
agent: codex
---

支持的 Agent：claude、codex、copilot、kimi、gemini、glm4、minimax

与 /loop 搭配使用（Claude Code）

要每 5 分钟自动调度一次：

/loop 5m python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/001-feature/

这会反复运行循环，每次向你显示下一个命令。

注意：Ralph Loop 现在由 Python 脚本直接管理。已移除弃用的 /developer-kit-specs:specs.ralph-loop 命令。

任务文件格式

每个任务应单独存放在一个文件中：tasks/TASK-XXX.md

---
id: TASK-036
title: Implement user authentication
status: pending
lang: java
dependencies: []
complexity: medium
agent: claude
---

## Description

Implement JWT-based authentication for the API.

## Acceptance Criteria

- [ ] Login endpoint returns JWT token
- [ ] Token validation middleware
- [ ] Refresh token mechanism

示例

示例 1：基本用法

# Initialize
python3 ralph_loop.py --action=start \
  --spec=docs/specs/001-feature/ \
  --from-task=TASK-001 \
  --to-task=TASK-005

# Loop until complete
while true; do
  python3 ralph_loop.py --action=loop --spec=docs/specs/001-feature/
  # Execute the shown command manually
  # Then continue loop
done

示例 2：搭配 Claude Code /loop 使用

# Start with specific range
/loop 5m python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
  --action=loop \
  --spec=docs/specs/002-tdd-command \
  --from-task=TASK-001 \
  --to-task=TASK-010

示例 3：多 Agent 设置

# Initialize with Claude as default
python3 ralph_loop.py --action=start \
  --spec=docs/specs/001-feature/ \
  --agent=claude

# Some tasks have "agent: codex" in their frontmatter
# Those will show Codex-formatted commands

最佳实践

• 每次调用执行一个步骤：恰好执行一个步骤，保存状态，然后停止
• 以状态为准：从 fix_plan.json 读取状态，并写入 fix_plan.json
• 不累积上下文：状态保存在文件中，而非上下文中
• 手动执行命令：脚本会显示命令；你需要在 CLI 中执行
• 审查未通过时重试：最多重试 3 次，否则判定失败
• 按范围筛选：始终通过 task_range 进行筛选
• 优先处理依赖项：仅选择所有依赖项均已完成的任务
• Git 提交：每个任务完成后，脚本都会自动提交

限制和警告

• 上下文膨胀：不要在一次调用中同时执行实施、审查和同步，否则上下文会溢出
• 最多重试次数：审查未通过时最多重试 3 次，然后判定失败
• Git 状态：开始前确保 Git 状态干净
• 测试基础设施：循环要求测试通过；没有测试时，反压机制无效
• 严格的状态验证：有效的 state.step 值仅限于：init、choose_task、implementation、review、fix、cleanup、sync、update_done、complete、failed
• 不会自动执行命令：脚本会显示命令，但不会执行；你必须在 CLI 中运行

故障排除

“未找到 fix_plan.json”

首先运行 --action=start：

python3 ralph_loop.py --action=start --spec=docs/specs/001-feature/

脚本会在正确的位置创建 fix_plan.json：

docs/specs/001-feature/_ralph_loop/fix_plan.json

“fix_plan.json 位于错误位置”

如果看到有关文件位置错误的警告，脚本会指导你完成迁移：

# Manual migration if needed
mkdir -p docs/specs/001-feature/_ralph_loop
mv docs/specs/001-feature/fix_plan.json docs/specs/001-feature/_ralph_loop/fix_plan.json

首次运行时，脚本会自动迁移旧文件。

“规范文件夹无效”

首先运行 --action=start：

python3 ralph_loop.py --action=start --spec=docs/specs/001-feature/

未找到任务文件

确保任务文件采用 tasks/TASK-XXX.md 格式，并包含 YAML frontmatter。

Agent 命令错误

检查 --agent 参数或任务的 agent: frontmatter 字段。

参考资料

• references/state-machine.md - 完整的状态机文档
• references/multi-cli-integration.md - 多 CLI 设置指南
• references/loop-prompt-template.md - Shell 循环提示词模板