Ralph Loop - Claude Code가 완료될 때까지 자동으로 도는 루프

Claude Code 플러그인 큐레이션 시리즈 · 4편 Ralph Loop

이 글에서 다루는 내용

Ralph Loop는 Anthropic 공식 마켓플레이스에 등록된 자동 반복 플러그인입니다. 동작 원리가 인상적일 만큼 단순합니다 - Stop hook으로 Claude의 종료 시도를 가로채 같은 프롬프트를 다시 주입합니다. "테스트가 통과할 때까지", "요건이 충족될 때까지" 한 세션 안에서 자동으로 반복하게 만드는 도구입니다. 이 글은 정체와 동작 원리, 설치 명령, 안전한 사용을 위한 반복 한도 설정, 활용 시나리오와 비용 관리까지 정리합니다. 기준 시점은 2026년 4월입니다.

---

1. Ralph Loop의 자리

이름은 심슨 가족의 캐릭터 Ralph Wiggum에서 따왔습니다. "끈질기게 다시 시도한다"는 분위기를 그대로 가져온 작명입니다. 공식 README의 한 줄을 그대로 옮기면 다음과 같습니다.

"Ralph is a simple while loop concept that repeatedly feeds an AI agent a prompt file."

핵심은 "한 세션 안에서 자동 반복"이라는 점입니다. 외부에서 bash 루프를 돌리는 게 아니라, Claude Code 세션 내부에서 종료 시도를 가로채 다시 시키는 방식이라 git 히스토리·파일 변경·이전 시도 결과가 그대로 보존됩니다. Claude는 매 반복마다 직전 시도의 결과를 보고 더 나은 방향을 잡을 수 있습니다.

---

2. 동작 원리 - Stop hook으로 종료 가로채기

Claude Code는 작업 종료 시점에 Stop hook을 발동합니다. 일반적으로 이 hook은 정리·로깅 용도로 쓰이는데, Ralph Loop는 이 단계에서 exit code 2를 반환해 종료 자체를 차단합니다. 차단된 직후 같은 프롬프트가 다시 모델에 주입되어 작업이 이어집니다.

단계	동작
1	Claude가 작업을 마쳤다고 판단해 종료 시도
2	Stop hook이 exit code 2로 종료 차단
3	동일 프롬프트가 모델에 다시 주입
4	Claude가 직전 결과를 보고 더 정교한 시도
5	반복 한도에 닿거나 완료 조건 충족 시 정상 종료

중요한 건 이 동작이 같은 세션 안에서 일어난다는 점입니다. 컨텍스트와 파일 변경이 그대로 유지되므로 Claude가 "전 시도에서 무엇이 안 됐는지"를 직접 참조할 수 있습니다.

---

3. 설치

Anthropic 공식 마켓플레이스에 등록되어 있어 한 줄로 끝납니다.

> /plugin install ralph-wiggum@claude-plugins-official

플러그인 이름이 마켓플레이스에선 ralph-wiggum이고, 사용 시 표기는 보통 Ralph Loop로 부릅니다. 같은 도구입니다.

---

4. 안전한 사용 - 반복 한도가 가장 중요하다

"끝날 때까지 반복"은 잘못 쓰면 토큰을 빠르게 태웁니다. Ralph Loop를 사용할 때 가장 먼저 챙겨야 할 건 반복 한도(--max-iterations) 설정입니다.

> /ralph "결제 모듈 단위 테스트가 모두 통과할 때까지 고쳐 줘" --max-iterations 8

경험적으로 다음 정도의 한도가 안전합니다.

작업 종류	권장 반복 한도
단위 테스트 통과 / 린트 정리	3~5
소규모 리팩터·버그 수정	5~8
통합 테스트·E2E 안정화	8~12 (대신 큰 비용)
탐색적 작업 (불확실성 큼)	2~3 (Ralph Loop보다 다른 접근 권장)

⚠️ 반복 한도를 두지 않거나 너무 크게 잡으면 같은 실수를 반복하면서 토큰만 소진하는 사례가 흔합니다. 첫 시도에선 항상 작은 한도로 시작해서 결과를 보고 늘리는 방향이 안전합니다.

---

5. 활용 시나리오 세 가지

5-1. 단위 테스트 통과까지 자동 수정

Ralph Loop가 가장 빛나는 사례입니다. 완료 조건이 명확하고 검증이 빠른 작업이라 반복 효율이 좋습니다.

> /ralph "tests/services/payment_test.py 의 실패 테스트 7개를 모두 통과시켜 줘. 구현 코드만 수정하고 테스트 자체는 건드리지 마." --max-iterations 6

"테스트 자체는 건드리지 마"라는 한 줄이 중요합니다. 이 단서가 없으면 AI가 테스트를 수정해 통과시키는 가짜 성공이 발생할 수 있습니다(활용 매뉴얼 2번 항목의 reward hacking 함정과 같은 메커니즘입니다).

5-2. 린트·타입 체크 무결까지

> /ralph "프로젝트 전체에서 mypy strict mode 에러를 모두 해소해 줘. 타입 의미를 바꾸지 말고 명시적으로 채울 것." --max-iterations 5

5-3. CI 그린 빌드 확보

로컬에서 빌드는 되는데 CI에서만 실패하는 케이스에 잘 맞습니다. CI 로그를 첨부해 두면 매 반복에서 새 단서를 보고 시도할 수 있습니다.

> /ralph "최근 main 빌드가 빨간색이다. ci-log.txt 를 읽고 원인을 찾아 고쳐 그린 빌드까지 만들어 줘." --max-iterations 8

---

6. Superpowers와의 차이

3편 Superpowers와 같은 "작업 방법론" 카테고리이지만 결이 다릅니다.

관점	Superpowers	Ralph Loop
접근	한 사이클을 깔끔하게 만든다	완료될 때까지 반복한다
잘 맞는 작업	새 기능 설계·구현, 신중한 리팩터	테스트 통과, 린트 정리, CI 그린
완료 조건	사용자 승인 단계 포함	기계가 검증 가능한 명확한 조건
비용 특성	예측 가능	반복 한도에 비례

두 도구는 서로 보완이 됩니다. Superpowers로 새 기능을 만든 뒤 Ralph Loop로 테스트 통과까지 자동 마무리하는 흐름이 가장 자연스럽습니다.

---

트러블슈팅

문제 1: 같은 실수를 반복하면서 한도까지 다 쓴다

한도를 너무 크게 잡았거나 완료 조건이 모호한 경우입니다. 첫 시도는 한도 3 정도로 줄이고, 첫 한 사이클의 결과를 보고 한도를 늘리는 흐름이 안전합니다. 또 "어떤 조건이 충족되면 종료"인지 프롬프트에 한 줄로 못 박아 두면 헛도는 시간이 줄어듭니다.

문제 2: 테스트는 통과했는데 의미가 없다

"통과를 위해 테스트 자체를 수정"한 케이스입니다. 5-1에서 다룬 reward hacking입니다. 프롬프트에 "테스트 파일은 수정하지 말 것"을 명시하고, 머지 전에 PR diff를 사람이 한 번 확인합니다.

문제 3: 반복 도중 컨텍스트가 가득 찬다

매 반복마다 컨텍스트가 누적되어 후반부엔 모델 응답 품질이 떨어질 수 있습니다. 작업이 길게 이어진다면 한도를 작게 잡아 한 번 끊고, 다음 사이클에서 핵심 정보만 새 프롬프트에 담아 다시 시작하는 분할 방식이 안정적입니다.

문제 4: 종료 가로채기와 다른 hook이 충돌한다

OMC·ECC 같은 다른 강화 플러그인과 함께 쓰면 Stop hook이 겹칠 수 있습니다. 한 환경엔 한 가지 강화 플러그인을 두는 원칙(시리즈 인덱스 5번 항목)을 따르거나, Ralph Loop만 쓰는 별도 프로젝트 설정으로 분리하는 것이 깔끔합니다.

---

마무리

Ralph Loop는 동작이 단순하기 때문에 강력합니다. 한 줄짜리 아이디어("종료를 차단하고 같은 프롬프트를 다시 주입한다")가 실제 워크플로우에선 큰 차이를 만듭니다. 다만 "끈질기게 반복한다"는 본성 때문에 잘못 쓰면 비용이 빠르게 쌓이므로, 항상 반복 한도와 명확한 완료 조건을 함께 박아 두는 습관이 핵심입니다.

다음 편에서는 카테고리를 바꿔 Claude-Mem을 다룹니다. 한 세션 안에서의 자동 반복이 아니라, 세션과 세션 사이를 잇는 메모리 도구입니다.

 

• Anthropic 공식 플러그인 페이지: claude.com/plugins/ralph-loop
• Anthropic GitHub README: github.com/anthropics/claude-code/.../ralph-wiggum/README.md
• 이전 편: 3편 Superpowers
• 다음 편: 5편 Claude-Mem
• 시리즈 인덱스: Claude Code 플러그인 큐레이션 시리즈