Ralph Loop

Geoffrey Huntley의 Ralph 기법 기반 자율 반복 개발 루프.

핵심 원리: 동일한 작업을 반복 실행하되, 매 이터레이션마다 이전 결과(파일, 변경 내역)를 보고 점진적으로 개선한다.

호출 형식

/ralph-loop <작업 설명> [--max-iterations N] [--completion-promise "완료 문구"]

예시:

/ralph-loop "할 일 관리 REST API 구현해줘" --max-iterations 5
/ralph-loop "auth 버그 고쳐줘" --completion-promise "FIXED" --max-iterations 10
/ralph-loop "코드 리팩토링해줘" --max-iterations 3

기본값:

--max-iterations: 5
--completion-promise: 없음 (max-iterations까지 실행)

저장 구조

[프로젝트 루트]/.ralph/
  ├── PROMPT.md       ← 작업 목표 (고수준)
  ├── fix_plan.md     ← 구체적 작업 목록 (체크리스트)
  ├── AGENT.md        ← 빌드/테스트 명령어
  └── logs/
      └── iteration-N.md   ← 이터레이션별 진행 기록

실행 흐름

Phase 0: 인수 파싱

스킬이 호출되면 사용자 입력에서 다음을 추출한다:

작업 설명 (<작업 설명>): 수행할 작업의 핵심 목표
max-iterations (--max-iterations N): 최대 반복 횟수. 없으면 기본값 5
completion-promise (--completion-promise "문구"): 완료 신호 문구. 없으면 max-iterations까지만 실행

인수가 모호하면 AskUserQuestion으로 확인한다.

Phase 1: 셋업

.ralph/ 디렉토리를 생성하고 아래 파일들을 만든다.

`.ralph/PROMPT.md` 생성

# Ralph Loop - 작업 목표

## 작업 설명
[사용자가 입력한 작업 설명 그대로]

## 완료 조건
[--completion-promise가 있으면: "아래 문구를 출력하면 완료: <promise>문구</promise>"]
[없으면: "max-iterations 도달 시 완료"]

## 규칙
- 매 이터레이션 시작 시 .ralph/fix_plan.md를 읽고 미완료 항목을 확인한다
- 작업 후 .ralph/fix_plan.md에서 완료된 항목을 체크한다
- 이터레이션 결과를 .ralph/logs/iteration-N.md에 기록한다
- 완료 신호는 <promise>문구</promise> 형식으로 출력한다

`.ralph/fix_plan.md` 생성

작업 설명을 분석해서 구체적인 하위 작업으로 분해한다:

# Fix Plan

## 상태: 진행중
## 마지막 업데이트: [현재 날짜]

## 작업 목록

- [ ] [하위 작업 1]
- [ ] [하위 작업 2]
- [ ] [하위 작업 3]
...

## 완료 기록
(완료된 항목이 여기로 이동)

`.ralph/AGENT.md` 생성

# Agent Instructions

이 프로젝트에서 사용할 주요 명령어:
- 빌드: [감지된 빌드 명령, 없으면 "N/A"]
- 테스트: [감지된 테스트 명령, 없으면 "N/A"]
- 실행: [감지된 실행 명령, 없으면 "N/A"]

.ralph/logs/ 디렉토리도 생성한다.

셋업 완료 후 사용자에게 보고:

🔄 Ralph Loop 시작!

작업: [작업 설명]
최대 이터레이션: N회
완료 조건: [문구 or "N회 완료 후"]

.ralph/ 구조 생성 완료.
이터레이션 1 시작...

Phase 2: 이터레이션 루프

current_iteration = 1부터 시작하여 아래를 반복한다.

각 이터레이션 실행

Task 에이전트로 이터레이션을 실행한다:

Task(
  description="Ralph Loop 이터레이션 N",
  prompt="""
당신은 Ralph Loop의 이터레이션 N을 실행하는 에이전트입니다.

## 작업 목표
[PROMPT.md 내용]

## 현재 상태
[fix_plan.md 내용]

## 이전 이터레이션 요약
[iteration-(N-1).md 내용, 없으면 "첫 번째 이터레이션"]

## 지시사항

1. fix_plan.md에서 미완료 항목을 확인한다
2. 가장 중요한 미완료 항목부터 작업한다
3. 실제로 파일을 수정/생성하며 작업한다
4. 작업 완료 후 fix_plan.md에서 해당 항목을 [x]로 표시한다
5. .ralph/logs/iteration-N.md에 이터레이션 기록을 남긴다:
   - 이번에 한 작업
   - 완료된 항목
   - 남은 항목
   - 전체 진행률 (%)
   - [completion-promise가 있을 경우] 완료 조건 달성 여부

[completion-promise가 있을 경우]
완료 조건("문구")이 달성되면 반드시 다음 형식으로 출력하라:
<promise>문구</promise>

모든 작업이 완료되었다면 iteration 기록 마지막에 EXIT_SIGNAL: true를 추가하라.
"""
)

완료 조건 확인

에이전트 출력과 iteration-N.md를 확인한다:

completion-promise가 있는 경우: 에이전트 출력에 <promise>문구</promise>가 있으면 → 루프 종료
fix_plan.md 전체 완료: 모든 항목이 [x]면 → 루프 종료
EXIT_SIGNAL: true: iteration 기록에 있으면 → 루프 종료
max-iterations 도달: current_iteration >= max_iterations → 루프 종료

위 조건 중 하나도 해당 없으면 current_iteration += 1 후 다음 이터레이션 실행.

Phase 3: 완료 보고

루프 종료 후 최종 보고서를 출력한다:

✅ Ralph Loop 완료!

작업: [작업 설명]
총 이터레이션: N회
종료 이유: [완료 조건 달성 / 전체 태스크 완료 / max-iterations 도달]

## 진행 요약
[각 이터레이션별 한 줄 요약]

## 최종 fix_plan.md 상태
[완료된 항목들]
[미완료 항목들 (있다면)]

## 생성/수정된 파일
[변경된 파일 목록]

다음 단계: [미완료 항목이 있다면 제안, 없다면 "모든 작업 완료"]

중단 방법

루프 중 사용자가 중단하면:

현재 이터레이션 완료 후 종료
fix_plan.md에 현재 상태 저장
중단 보고 출력

/cancel-ralph 또는 /ralph-cancel 호출 시에도 동일하게 처리.

주의사항

각 이터레이션은 독립적인 Task 에이전트로 실행된다 (이전 이터레이션 파일을 통해 컨텍스트 공유)
.ralph/ 디렉토리가 이미 존재하면 기존 fix_plan.md를 이어받아 계속 진행
작업 성격에 따라 max-iterations 추천값: 단순 구현 3-5회, 복잡한 리팩토링 5-10회, 버그 수정 3-7회

ralph-loop