[Claude Code] Ralph Loop 플러그인 사용법. (자동 반복 루프)

몇일사이에 Ralph Wiggum 에서 Ralph Loop로 이름을 변경해서, 글 다 수정함;; 이름은 제발 한번에 잘 짓자.

 

개요

Ralph Loop은 Claude Code의 공식 플러그인으로, 자동 반복 루프를 통해 작업을 자율적으로 완성함.

"Ralph is a Bash loop" - Geoffrey Huntley

핵심 개념

동작 원리

while true:
  1. 프롬프트를 AI에게 전달
  2. AI가 작업 수행
  3. AI가 종료 시도
  4. Stop hook이 종료 차단
  5. 동일 프롬프트 재전달
  6. 완료될 때까지 반복

핵심 특징:

• ✅ 프롬프트는 반복 간 변하지 않음
• ✅ 작업은 파일에 지속됨
• ✅ Git 히스토리가 자동으로 쌓임
• ✅ Claude가 자신의 이전 작업을 읽으며 자율 개선

설치

클로드 실행 후 다음 명령어로 설치

/plugin

ralph-loop 검색

설치

설치 후 바로 사용

명령어

/ralph-loop:ralph-loop

Ralph 루프를 시작한다.

사용법:

/ralph-loop:ralph-loop "<프롬프트>" [옵션]

옵션:

• --max-iterations <n> - N번 반복 후 중지 (기본값: 무제한)
• --completion-promise "<text>" - 완료를 알리는 특정 문구

기본 예시:

/ralph-loop:ralph-loop "간단한 계산기 앱을 만들어.
완료하면 <promise>DONE</promise> 출력해" \
  --completion-promise "DONE" \
  --max-iterations 10

/ralph-loop:cancel-ralph

활성 Ralph 루프를 즉시 취소한다.

/ralph-loop:cancel-ralph

실전 예시

1. REST API 구축

/ralph-loop:ralph-loop "TODO REST API를 구현해:

**요구사항:**
- CRUD 엔드포인트 (GET, POST, PUT, DELETE)
- 입력 검증 (빈 값, 타입 체크)
- 에러 핸들링 (400, 404, 500)
- 유닛 테스트 (커버리지 80% 이상)
- API 문서 (README.md)

**완료 기준:**
- 모든 테스트 통과
- 빌드 성공
- README 작성 완료

완료하면 <promise>COMPLETE</promise> 출력해." \
  --completion-promise "COMPLETE" \
  --max-iterations 50

2. TDD로 기능 구현

/ralph-loop:ralph-loop "TDD 방식으로 사용자 인증 모듈을 구현해:

**작업 순서:**
1. 실패하는 테스트 작성 (회원가입, 로그인, 토큰 검증)
2. 최소 코드로 테스트 통과시키기
3. 리팩토링
4. 다음 테스트로 이동
5. 모든 테스트가 통과할 때까지 반복

**요구사항:**
- JWT 기반 인증
- 비밀번호 해싱 (bcrypt)
- 토큰 만료 처리
- 테스트 커버리지 90% 이상

**검증:**
- npm test 실행 → 모두 통과
- npm run build 실행 → 성공

완료하면 <promise>COMPLETE</promise> 출력해" \
  --completion-promise "COMPLETE" \
  --max-iterations 30

3. 버그 수정

/ralph-loop:ralph-loop "다음 버그를 수정해:

**문제:**
- 사용자 목록 API가 간헐적으로 500 에러 발생
- 로그에 'Cannot read property id of undefined' 표시

**작업:**
1. 에러 재현 테스트 작성
2. 버그 원인 파악
3. 수정
4. 테스트로 검증
5. 회귀 테스트 추가

**완료 조건:**
- 재현 테스트 작성 및 통과
- 기존 테스트 모두 통과
- 회귀 테스트 추가

완료하면 <promise>FIXED</promise> 출력해" \
  --completion-promise "FIXED" \
  --max-iterations 20

4. 리팩토링

/ralph-loop:ralph-loop "UserService.ts를 리팩토링해:

**목표:**
- 순환 복잡도 < 5
- 함수 길이 < 30줄
- 중복 코드 제거
- 테스트는 변경하지 않음

**프로세스:**
1. 현재 복잡도 측정
2. 복잡한 함수 분해
3. 중복 코드 추출
4. 테스트 실행
5. 모든 테스트 통과 확인
6. 복잡도 재측정

**완료 조건:**
- 모든 테스트 통과
- 복잡도 목표 달성
- 타입 에러 없음

완료하면 <promise>REFACTORED</promise> 출력해" \
  --completion-promise "REFACTORED" \
  --max-iterations 15

프롬프트 작성 가이드

✅ 좋은 프롬프트

# 명확한 성공 기준
"기능 X를 구현해.

완료 조건:
- 테스트 통과 (커버리지 > 80%)
- 빌드 성공
- 타입 에러 없음
- README 업데이트

완료하면 <promise>DONE</promise> 출력해"

# 증분 목표
"E-commerce API를 구축해.

Phase 1: 사용자 인증 (JWT, 테스트)
Phase 2: 상품 CRUD (검증, 테스트)
Phase 3: 주문 처리 (결제 제외, 테스트)

각 Phase 완료할 때마다 테스트 통과 확인해
모든 Phase 완료하면 <promise>COMPLETE</promise> 출력해"

# 자체 검증 포함
"API 엔드포인트 /users를 구현해.

작업 후 다음을 실행해:
1. npm test -- users.test.ts
2. npm run build
3. npx tsc --noEmit

모두 통과하면 <promise>COMPLETE</promise> 출력해
실패하면 수정 후 재시도해"

❌ 나쁜 프롬프트

# 너무 모호함
"좋은 API를 만들어줘"

# 성공 기준 없음
"기능을 구현하고 최선을 다해"

# 안전 장치 없음 (무한 루프 위험)
"완벽할 때까지 계속 개선해"

안전 장치

1. 항상 max-iterations 설정하자

# ✅ 좋은 예
/ralph-loop:ralph-loop "..." --max-iterations 50

# ❌ 나쁜 예 (무한 루프 위험)
/ralph-loop:ralph-loop "..."

2. 프롬프트에 탈출 조건 명시하자

/ralph-loop:ralph-loop "기능 X를 구현해.

15회 반복 후에도 미완료면:
- 현재까지 진행 상황 문서화
- 시도한 접근법 나열
- 차단 요소 설명
- 대안 제시
- <promise>BLOCKED</promise> 출력

완료하면 <promise>COMPLETE</promise> 출력해" \
  --max-iterations 20

3. 검증 단계 포함하자

"작업 완료 후 다음을 실행해:
1. npm test
2. npm run build
3. npx tsc --noEmit

모두 통과할 때만 <promise>COMPLETE</promise> 출력해"

사용 시나리오

✅ Ralph가 효과적인 경우

• 자동 검증 가능한 작업
  • 테스트 스위트가 있는 기능 개발
  • 빌드 성공 여부로 확인 가능한 작업
  • 린터로 검증 가능한 코드 스타일 수정
• 반복과 개선이 필요한 작업
  • TDD 방식 개발
  • 테스트 커버리지 향상
  • 복잡도 감소 리팩토링
• Greenfield 프로젝트
  • 새로운 마이크로서비스 구축
  • PoC 프로토타입 개발
  • 독립적인 모듈 개발

❌ Ralph가 부적절한 경우

• 인간 판단 필요
  • 아키텍처 설계 결정
  • UX/UI 디자인
  • 비즈니스 로직 정의
• 일회성 작업
  • 간단한 버그 수정 (1-2분 작업)
  • 설정 파일 수정
  • 문서 업데이트
• 프로덕션 이슈
  • 긴급 장애 대응
  • 복잡한 디버깅

실전 팁

1. 작은 단위로 시작하자

# ✅ 작은 목표
/ralph-loop:ralph-loop "User 모델만 구현해 (CRUD, 테스트)" --max-iterations 10

# ❌ 큰 목표
/ralph-loop:ralph-loop "전체 시스템 구축해" --max-iterations 100

2. 검증 자동화하자

"작업 완료 후:
- /verify-app 실행해
- 모든 검증 통과하면 <promise>COMPLETE</promise>"

3. Git 커밋 활용하자

"각 Phase 완료할 때마다:
1. git add .
2. git commit -m 'Phase X complete'
3. 다음 Phase 진행

모든 Phase 완료하면 <promise>COMPLETE</promise>"

4. 진행 상황 로깅하자

"각 반복마다 progress.md 업데이트해:
- 완료된 작업
- 남은 작업
- 발견한 이슈

완료하면 <promise>COMPLETE</promise>"

실제 성과

Ralph Loop 플러그인의 실제 사용 사례:

• ✅ Y Combinator 해커톤에서 하룻밤에 6개 저장소 생성했음
• ✅ $50,000 계약을 $297의 API 비용으로 완료했음
• ✅ 3개월에 걸쳐 전체 프로그래밍 언어 생성함 (프로젝트명: "cursed")

추가 자료

• 원본 기법: https://ghuntley.com/ralph/
• Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator
• Claude Code 공식 플러그인: https://github.com/anthropics/claude-plugins-official

문제 해결

Q: Ralph가 무한 루프에 빠졌어

A: /ralph-loop:cancel-ralph로 즉시 중지하고, --max-iterations를 더 낮게 설정해.

Q: 완료 조건이 계속 충족 안 돼

A: 프롬프트에 구체적인 검증 단계를 추가하고, 각 단계별 출력을 확인해봐.

Q: Ralph가 같은 에러를 반복해

A: 프롬프트에 "에러 발생하면 다른 접근법 시도해" 지시를 추가해.

Q: 언제 Ralph를 중단해야 해?

A: 5-10회 반복해도 진전이 없거나, 같은 작업을 반복하면 중단하고 프롬프트를 수정해.