Ralph Wiggum 플러그인으로 자가 반복 개발 루프 돌리기

핵심 요약

Ralph Wiggum은 "같은 프롬프트를 반복해서 먹이는 AI 개발 루프"를 Claude Code 안에서 자동으로 돌려주는 방식이다.

한 번만 명령을 실행하면, 종료를 가로채 다시 같은 작업을 반복하게 만들어 코드·테스트·문서화를 점진적으로 완성해 나간다.

스타트업의 반복적인 빌드·수정·테스트 작업을 자동화하는 데 특히 유용하다.

Ralph Wiggum이란 무엇인가

Ralph는 "AI에게 같은 과제를 계속 다시 시키면서, 파일과 git 변경 내역을 통해 스스로 개선하게 만드는 개발 방식"이다.

원래는 단순한 while true Bash 루프 아이디어에서 출발했지만, 여기서는 Claude Code 플러그인으로 구현되어 별도 스크립트나 서버 없이도 현재 세션 안에서만 반복이 돌아간다.

핵심은 프롬프트는 그대로 두고, 코드와 테스트 결과, 파일 상태가 매 반복마다 업데이트된다는 점이다.

Stop Hook 기반 루프 메커니즘

이 플러그인은 "Stop hook"이라는 훅을 사용해 Claude가 세션을 종료하려 할 때 이를 가로챈다.

종료를 막는 동시에, 같은 프롬프트를 다시 Claude에게 전달해 "한 번 더 같은 일을 하되, 지금까지의 변경사항을 보고 개선하라"는 효과를 만든다.

이 반복은 사용자가 명시한 완료 신호(completion promise)를 발견하거나 최대 반복 횟수에 도달할 때까지 계속된다.

기본 사용법과 실행 패턴

핵심 명령은 /ralph-loop 하나다.

형태는 다음과 비슷하다:

/ralph-loop "할 일 설명..." --completion-promise "COMPLETE" --max-iterations 50

예를 들어, todo REST API를 만들고 싶다면 다음과 같이 쓸 수 있다:

/ralph-loop "Todo REST API 구현. CRUD, 입력 검증, 테스트 포함. 완료 시 <promise>COMPLETE</promise> 출력." \
  --completion-promise "COMPLETE" \
  --max-iterations 50

한 번 실행하면 Claude가 코드를 만들고, 테스트를 돌리고, 실패를 보고 수정하는 과정을 여러 번 반복하면서 목표 상태에 근접해 간다.

완료 조건과 반복 제한 설계하기

루프가 멈추는 기준은 두 가지다.

첫째, 프롬프트 안에 "완료되면 정확히 이 문자열을 출력하라"는 약속(예: <promise>COMPLETE</promise>)을 넣고, --completion-promise에 그 문자열을 지정하면, Claude가 그 문구를 출력하는 순간 루프가 종료된다.

둘째, --max-iterations 옵션으로 안전한 상한선을 정해두면, 작업이 애매하거나 불가능할 때도 무한 반복 없이 빠져나올 수 있다.

중요한 점은 completion promise는 "정확한 문자열 매칭"만 하기 때문에, 성공·실패를 여러 문구로 나누어 처리하는 용도로 쓰기보다는 "완료" 신호 하나만 명확히 쓰고, 실패·막힘 상황은 반복 제한과 리포트 작성 규칙으로 처리하는 편이 낫다.

좋은 프롬프트를 쓰는 전략

Ralph 루프의 성능은 사실상 "프롬프트 설계력"에 달려 있다.

먼저, 완료 기준을 구체적으로 적어야 한다. 예를 들어 "Todo API 잘 만들어줘" 대신 "CRUD 동작, 입력 검증, 테스트 통과, README에 API 문서, 마지막에 <promise>COMPLETE</promise> 출력"처럼 체크리스트 수준으로 명시하는 것이 좋다.

또한, 단계별 목표를 나눈 프롬프트가 효과적이다. "1단계: 인증, 2단계: 상품 목록, 3단계: 장바구니"처럼 페이즈를 정의하고, 모두 끝나면 completion promise를 출력하도록 지시하면 장기 작업에서도 점진적으로 완성도를 높인다.

마지막으로, 자가 수정 전략을 포함시키면 루프의 강점이 극대화된다. "실패하는 테스트를 먼저 쓰고, 구현하고, 테스트를 반복 실행하며 모두 통과할 때까지 수정하고, 그 후 리팩터링하라"처럼 TDD 루틴 자체를 프롬프트에 박아두면 된다.

막힐 때를 대비한 안전장치 설계

실제 프로젝트에서는 항상 성공만 있는 것이 아니므로, "막혔을 때 어떻게 행동해야 하는지"도 프롬프트에 미리 적어두는 것이 좋다.

예를 들어 "15회 이상 반복했는데도 완료 조건을 충족하지 못하면, 무엇이 막고 있는지 정리하고, 시도했던 접근들을 나열하고, 대체 전략을 제안하라"라고 써두면, 실패조차 유용한 리포트로 변한다.

여기에 --max-iterations 20 정도의 상한을 걸어 두면, 예측 불가한 상황에서도 프로젝트나 세션이 잠기지 않고, 적당한 시점에 사람이 개입해 방향을 재설계할 수 있다.

진짜 "비상 브레이크"가 필요할 때는 /cancel-ralph 명령으로 현재 루프를 즉시 중단할 수 있다.

언제 Ralph 방식을 쓰면 좋은가

Ralph는 "정답이 명확하고, 자동 검증이 가능하며, 반복적으로 다듬을수록 좋아지는 작업"에 강하다.

예를 들면 테스트가 있는 기능 개발, 새 프로젝트 초기 버전 만들기, 코드 리팩터링 및 커버리지 개선, 간단한 언어나 DSL 구현 등이다. 이런 작업은 테스트·린터·타입체커 같은 도구가 있어 AI가 스스로 실패를 감지하고 수정할 수 있다.

반대로, 디자인 감각이나 제품 전략처럼 인간의 판단이 핵심인 문제, 한 번만 실행해야 하는 민감한 운영 작업, 성공 정의가 모호한 탐색적 과제에는 맞지 않는다. 이 경우에는 "대화형으로 논의→결정 후 일부를 자동화"하는 식의 하이브리드 접근이 낫다.

인사이트

스타트업 입장에서 Ralph는 "엔지니어 한 명을 반복 작업 전담 봇으로 복제하는 느낌"에 가깝다.

핵심은 두 가지다. 하나, 작업을 테스트·체크리스트·완료 조건으로 정형화할수록 루프가 잘 돈다. 둘, --max-iterations와 '막혔을 때의 행동 지침'을 잘 설계해 두면 실패조차 가치 있는 산출물로 바뀐다.

실전 팁을 정리하면, 작은 단위 기능부터 Ralph로 돌려보며 "내 팀의 표준 프롬프트 템플릿"을 쌓고, 잘 먹히는 패턴이 생기면 그 템플릿을 복제·변형해 점점 더 큰 기능·프로젝트로 확장하는 방식이 가장 효율적이다.

출처 및 참고 : claude-code/plugins/ralph-wiggum at main · anthropics/claude-code

다른 AI 코드 도구에서의 응용

Ralph식 루프는 Claude Code 전용 아이디어가 아니라, “외부에서 프롬프트를 반복 호출하는 런너” 패턴이라서 Codex, OpenCode, Qwen Coder, GitHub Copilot CLI 같은 다른 코드 모델에도 거의 그대로 이식되고 있다.¹² 기본 구조는 bash나 Node/Go 스크립트로 while 루프를 돌리면서, 매번 같은 과제 설명과 현재 코드베이스(또는 PRD)를 모델에 넘기고, 테스트·빌드 결과를 보고 스스로 수정하게 만드는 것이다. 이때 종료 조건은 Claude의 Stop hook 대신, 스크립트가 출력 안에서 COMPLETE나 체크리스트 완료 여부를 검사하는 방식으로 구현한다.²

실제 구현들은 “모델 무관 Ralph 오케스트레이터”나 “Copilot CLI용 Ralph 러너” 형태로 나와 있고, 하나의 루프 스크립트에서 Claude Code, Codex, OpenCode, Qwen 등을 선택해서 돌릴 수 있게 하는 경우도 많다.¹ VS Code 같은 IDE에서는 이 루프를 확장/플러그인 명령으로 래핑해, 특정 GitHub 이슈나 PR에 대해 “테스트 통과할 때까지 자동 수정→커밋→푸시”를 반복하게 만드는 식으로 쓰기도 한다.³⁴ 요약하면, Stop hook이 없더라도 “외부 루프 + 완료 문자열/테스트 통과 여부 검사 + 에디터/CI 연동” 조합만 있으면, 어떤 코드 특화 모델 위에서도 Ralph Wiggum 스타일의 자가 반복 개발 루프를 재현할 수 있다.¹²

참고

¹ralph-wiggum 토픽 리포지토리 모음 – Copilot CLI, Codex, OpenCode 등 멀티 툴용 Ralph 러너들

²From ReAct to Ralph Loop – Ralph 루프 개념과 외부 제어 기반 연속 반복 패턴

³Hacker News 댓글 – Codex exec와 GitHub 이슈를 묶은 반복 빌드·리뷰·수정 워크플로우 사례

⁴LinkedIn – Codex 5.1 Max를 VS Code 코딩 에이전트로 설정해 주말 동안 워크플로 앱을 빌드한 사례