Ralph Wiggum 入门第 2 部分：三阶段方法论

specs/
├── authentication.md    # 登录、JWT、会话
├── api-design.md        # 接口端点、请求/响应格式
├── database.md          # 数据库 Schema、关系
└── testing.md           # 覆盖率要求、测试策略

你: "我想构建一个管理 todo 的 REST API"

Claude: "让我们分解一下。你需要什么操作？"

你: "CRUD 操作 - 创建、读取、更新、删除 todo"

Claude: "明白了。认证怎么处理？用户账户呢？"

你: "要的，用户只应该看到自己的 todo"

Claude: "有道理。我们应该怎么处理……"

/ralph-loop "$(cat PROMPT_plan.md)" --max-iterations 5 --completion-promise "PLAN COMPLETE"

./loop.sh plan

# PLANNING MODE

You are in PLANNING mode. Your job is analysis, not implementation.

## Your Task
1. Read all files in specs/
2. Review the existing codebase in src/
3. Perform gap analysis between requirements and current implementation
4. Create/update IMPLEMENTATION_PLAN.md with prioritized tasks

## Task Structure
Each task in the plan should include:
- Unique ID (e.g., TASK-001, TASK-002)
- Priority level (high/medium/low)
- Clear description (what needs to be built)
- Acceptance criteria (how you'll know it's done)
- Required tests (specific test files or patterns)
- Dependencies (tasks that must complete first)

## File Organization
Organize tasks by priority:
- High Priority: Critical path items
- Medium Priority: Important but not blocking
- Low Priority: Nice-to-haves

## Critical Rules
- DO NOT write any code
- DO NOT make any commits
- DO NOT implement features
- DO NOT run tests or builds
- ONLY analyze and plan

When complete, output "PLAN COMPLETE"

# Implementation Plan

## High Priority

### TASK-001: User Authentication
- **Status**: pending
- **Description**: Implement JWT-based auth with login/logout
- **Acceptance Criteria**:
  - User can register with email/password
  - User can login and receive JWT token
  - Protected routes require valid JWT
- **Tests**: `auth.test.ts`
- **Dependencies**: none

### TASK-002: Todo CRUD Endpoints
- **Status**: pending
- **Description**: Create POST, GET, PUT, DELETE endpoints for todos
- **Acceptance Criteria**:
  - POST /api/todos creates a todo
  - GET /api/todos returns user's todos
  - PUT /api/todos/:id updates a todo
  - DELETE /api/todos/:id deletes a todo
- **Tests**: `todos.test.ts`
- **Dependencies**: TASK-001

## Medium Priority

### TASK-003: Input Validation
- **Status**: pending
- **Description**: Add Zod validation for all endpoints
...

/ralph-loop "$(cat PROMPT_build.md)" --max-iterations 50 --completion-promise "ALL TASKS COMPLETE"

./loop.sh              # 默认为构建模式
./loop.sh build 100    # 自定义迭代限制

# BUILDING MODE

You are in BUILDING mode. Your job is implementation with quality gates.

## Your Task Loop
For each iteration:
1. Read IMPLEMENTATION_PLAN.md and progress.txt
2. Pick the SINGLE highest priority task with status: pending
3. Study existing code before implementing
4. Implement the feature completely
5. Write comprehensive tests
6. Run all tests and type checks: npm test && npm run type-check
7. If tests fail, fix them immediately—DO NOT proceed
8. When all tests pass:
   - Commit with descriptive message format: "feat(area): description"
   - Update task status to completed in IMPLEMENTATION_PLAN.md
   - Append learnings to progress.txt with timestamp

## Critical Rules
- Work on ONE task at a time—no exceptions
- NEVER commit failing tests
- NEVER skip test execution
- Tests are your backpressure—respect them
- Each commit must be atomic and working
- Don't add features not in the plan
- Don't refactor unrelated code

## Backpressure Enforcement
Tests MUST pass before committing:
```bash
npm test && npm run type-check && npm run lint
```

If any check fails, fix it in the same iteration.

## Progress Tracking
After completing each task, append to progress.txt:
```
[YYYY-MM-DD HH:MM] Completed TASK-XXX: Task Title
- What was implemented
- Key decisions made
- Challenges encountered
- Learnings for next tasks
```

When all tasks show status: completed, output "ALL TASKS COMPLETE"

#!/bin/bash
# loop.sh - 每次迭代全新上下文

MODE=${1:-build}  # 默认为构建模式
MAX_ITERATIONS=${2:-50}

if [[ "$MODE" == "plan" ]]; then
  PROMPT_FILE="PROMPT_plan.md"
  COMPLETION="PLAN COMPLETE"
  MAX_ITERATIONS=${2:-5}  # 规划需要更少的迭代
else
  PROMPT_FILE="PROMPT_build.md"
  COMPLETION="ALL TASKS COMPLETE"
fi

echo "Running in $MODE mode with max $MAX_ITERATIONS iterations"
echo "Using prompt: $PROMPT_FILE"
echo "Completion signal: $COMPLETION"
echo "=========================================="

for ((i=1; i<=$MAX_ITERATIONS; i++)); do
  echo "Iteration $i / $MAX_ITERATIONS"
  echo "--------------------------------"

  # -p 标志让 Claude 以单次模式运行（参见精通第 1 部分：https://jocv.dev/blog/claude-code-mastery-01-getting-started#one-shot-mode-quick-questions）
  result=$(claude -p "$(cat $PROMPT_FILE)" --output-format text 2>&1) || true
  echo "$result"

  if [[ "$result" == *"$COMPLETION"* ]]; then
    echo "=========================================="
    echo "$MODE complete after $i iterations."
    exit 0
  fi

  echo "--- End of iteration $i ---"
done

echo "Reached max iterations ($MAX_ITERATIONS)"
exit 1

chmod +x loop.sh

./loop.sh plan      # 运行规划模式（默认 5 次迭代）
./loop.sh build     # 运行构建模式（默认 50 次迭代）
./loop.sh           # 等同于 ./loop.sh build
./loop.sh build 30  # 构建模式，最多 30 次迭代

# 阶段 1：定义需求（对话式，不是循环）
# 和 Claude 对话，创建 specs/*.md 文件
# 示例：specs/authentication.md、specs/api-design.md、specs/database.md

# 阶段 2：生成计划（运行一次，或在计划需要刷新时运行）
./loop.sh plan
# 或使用插件：/ralph-loop "$(cat PROMPT_plan.md)" --max-iterations 5 --completion-promise "PLAN COMPLETE"
# 创建包含优先级任务的 IMPLEMENTATION_PLAN.md

# 阶段 3：自主构建（持续循环）
./loop.sh
# 或使用插件：/ralph-loop "$(cat PROMPT_build.md)" --max-iterations 50 --completion-promise "ALL TASKS COMPLETE"
# 逐个实现任务，提交，循环

# 当计划变得过时（功能变更、新需求）时：
rm IMPLEMENTATION_PLAN.md
./loop.sh plan          # 重新生成计划
./loop.sh               # 继续构建

your-project/
├── specs/
│   ├── authentication.md
│   ├── api-design.md
│   ├── database.md
│   └── testing.md
├── PROMPT_plan.md          # 规划模式提示
├── PROMPT_build.md         # 构建模式提示
├── IMPLEMENTATION_PLAN.md  # 由规划生成，由构建更新
├── progress.txt            # 只追加的心得日志
├── loop.sh                 # Bash 编排脚本
└── src/                    # 你的实际代码
    ├── api/
    ├── auth/
    └── tests/

在你的提示中，指示代理：
"After each task, APPEND (don't overwrite) your learnings to progress.txt"

[2026-01-16 14:30] Completed TASK-001: User Authentication
- Implemented JWT signing/verification using jsonwebtoken
- Added httpOnly cookie storage for tokens
- All auth tests passing (12/12)
- Learning: Cookie sameSite setting needed for cross-origin requests
- Challenge: Had to debug token expiry edge case
- Next: Tackle TASK-002 (Todo CRUD endpoints)

# Implementation Plan

## High Priority

- [ ] TASK-001: User Authentication (status: pending)
  - Tests: auth.test.ts
  - Dependencies: none

## Medium Priority

- [ ] TASK-002: Todo CRUD (status: pending)
  - Tests: todos.test.ts
  - Dependencies: TASK-001

## Completed

- [x] TASK-000: Project Setup (status: completed)
  - Completed: 2026-01-15 22:00

Read progress.txt to see what's been accomplished.
After completing each task, APPEND (never overwrite) your progress.

Each commit MUST pass all tests and type checks.
Run: npm test && npm run type-check && npm run lint
If anything fails, fix it before moving on.
NEVER commit broken code.

Pick the SINGLE highest priority task from IMPLEMENTATION_PLAN.md.
Work ONLY on that task—don't add features or refactor unrelated code.

Study the codebase first.
Don't assume something isn't implemented—verify by reading files.
Use ultrathink before making changes.