랄프 위검 루프(Ralph Wiggum Loop)는 같은 작업 프롬프트를 AI 코딩 에이전트에 반복 투입하고, 파일·테스트 결과를 다음 반복의 피드백으로 쓰는 개발 방식이다. 핵심은 밤새 무한 실행하는 데 있지 않다. 명확한 완료 조건, 자동 검증, 반복 한도, 제한된 권한을 함께 설계해야 실무에 쓸 수 있다. 2026년 5월부터는 Claude Code가 완료 조건 기반 반복의 내장 명령 /goal를 기본 제공하므로, 플러그인을 설치하기 전에 이 내장 기능부터 확인한다.
핵심 요약
- 뜻: 동일한 프롬프트를 반복해 에이전트가 이전 파일 변경과 테스트 결과를 바탕으로 다음 작업을 이어가는 방식이다.
- 현재 사용법: Claude Code에서는 Anthropic 플러그인 디렉터리의
ralph-loop를 설치해 Stop hook 기반 루프를 실행할 수 있다. - 내장 대안: Claude Code는 2026년 5월부터 완료 조건을 별도 모델이 매 턴 판정하는
/goal명령을 기본 제공한다. 플러그인 설치 전에 먼저 확인한다. - 안전 조건:
--max-iterations, 기계적으로 판정 가능한 테스트, 비밀값 차단, 제한된 실행 권한을 반드시 둔다.
랄프 위검 루프란?
Geoffrey Huntley가 공개한 원형은 놀랄 만큼 단순하다. 프롬프트 파일을 코딩 에이전트에 넣는 과정을 셸의 while 루프로 반복한다. 한 번의 실행이 끝나도 수정된 코드, 작업 메모, Git 기록은 저장소에 남는다. 다음 실행은 이 결과를 읽고 남은 일을 계속한다.
while :; do
cat PROMPT.md | claude-code
done이름은 심슨 가족의 캐릭터 랄프 위검에서 왔다. 첫 시도에 완벽한 답을 기대하기보다 실패 결과를 다시 입력해 끈질기게 개선한다는 비유다. 다만 “사람 없이 알아서 완성하는 개발자”라기보다 검증 가능한 작업을 반복 실행하는 자동화 패턴으로 이해하는 편이 정확하다.
출처: Anthropic Ralph Loop 플러그인 문서
원형 Bash 루프와 Claude Code 플러그인의 차이
| 구분 | 원형 Bash 루프 | Claude Code Ralph Loop 플러그인 |
|---|---|---|
| 반복 방식 | 에이전트 프로세스를 셸에서 다시 실행 | 현재 세션의 종료 시도를 Stop hook이 가로챔 |
| 프롬프트 | 파일의 같은 내용을 다시 전달 | 명령에 넣은 같은 프롬프트를 다시 전달 |
| 진행 상태 | 파일·Git·작업 문서에 남김 | 현재 세션과 수정된 파일·Git 기록을 함께 사용 |
| 종료 | 외부 조건이나 수동 중단을 별도 구현 | 완료 문구 또는 최대 반복 횟수로 종료 |
Anthropic 플러그인은 Claude가 종료하려 할 때 Stop hook으로 이를 막고 같은 프롬프트를 다시 넣는다. 플러그인 README 기준 --max-iterations의 기본값은 제한 없음이므로, 실제 작업에서는 숫자를 명시하는 편이 안전하다. 완료 문구는 정확한 문자열 일치 방식이라 테스트 통과 여부를 대신 검증해 주지는 않는다.
Claude Code에서 설치하고 실행하는 법
2026년 8월 28일 확인 기준 Anthropic 공식 플러그인 디렉터리에는 ralph-loop가 development 카테고리로 등록되어 있다. Claude Code 안에서 다음 명령으로 설치한다.
/plugin install ralph-loop@claude-plugins-official설치 후에는 작고 검증 가능한 작업부터 실행한다.
/ralph-loop "Todo REST API를 구현한다.
완료 조건:
- CRUD 엔드포인트가 동작한다
- 입력 검증 테스트가 통과한다
- 전체 테스트가 통과한다
모든 조건을 실제로 확인한 뒤 <promise>COMPLETE</promise>를 출력한다." --completion-promise "COMPLETE" --max-iterations 20진행을 중단해야 할 때는 /cancel-ralph를 사용한다. Windows에서는 플러그인의 Bash hook이 Git Bash 경로 문제를 일으킬 수 있다. 공식 README는 Git for Windows의 Git/bin/bash.exe를 명시하는 우회 방법을 안내한다.
플러그인 없이 쓰는 내장 명령: /goal과 /loop
Claude Code는 2026년 5월 v2.1.139/140부터 완료 조건 기반 반복을 플러그인 없이 수행하는 /goal 명령을 기본 제공한다. 랄프 루프를 검색해 들어온 사용자가 실제로 원하는 기능이 이쪽에 있는 경우가 많으므로, 설치 전에 내장 기능으로 해결되는지 먼저 확인한다.
/goal 다음에 완료 조건을 붙이면 각 턴이 끝날 때마다 작은 판별 모델(기본 Haiku)이 조건 충족 여부를 평가한다. 아직 아님이면 다음 턴을 자동으로 시작하고, 충족 또는 불가능 판정이 나오면 루프가 끝난다. 조건은 최대 4,000자까지 쓸 수 있고 “or stop after 20 turns” 같은 상한 문구를 넣어 실행 범위를 제한할 수 있다.
/goal all tests in test/auth pass and the lint step is clean상태 확인은 인자 없는 /goal, 중단은 /goal clear다. 잔액 소진이나 컨텍스트 초과처럼 사용자가 직접 고쳐야 하는 오류가 나면 목표가 자동으로 해제되고, 일시적 오류는 최대 3회 재시도 뒤 일시정지된다. 사람 개입 없이 계속 돌리려면 auto mode와 함께 쓴다. 한편 /loop는 완료 조건이 아니라 시간 간격으로 같은 작업을 반복하는 내장 스킬이다. /loop 5m check the deploy처럼 쓰고, 간격을 생략하면 Claude가 스스로 다음 간격을 정한다.
| 구분 | 원형 Bash 루프 | ralph-loop 플러그인 | /goal (내장) | /loop (내장) |
|---|---|---|---|---|
| 다음 턴 시작 | 셸이 프로세스를 다시 실행 | 세션 종료를 Stop hook이 차단 | 이전 턴 종료 직후 자동 | 설정한 시간 간격마다 |
| 종료 조건 | 직접 구현 | 완료 문구 문자열 일치 또는 반복 한도 | 조건 충족·불가능 판정, 복구 불가 오류 | 직접 중단 또는 완료 판단 |
| 검증 주체 | 없음 | 정확한 문자열 일치 | 별도 판별 모델이 매 턴 평가 | 없음(각 실행이 독립) |
| 준비물 | 셸 스크립트 | 플러그인 설치 | 없음(기본 제공) | 없음(기본 제공) |
선택 기준은 단순하다. 같은 프롬프트를 문자열 그대로 되돌려 주는 원형 랄프 방식이 필요하면 ralph-loop 플러그인, “테스트가 모두 통과하면 멈춰라”처럼 조건 판정이 필요하면 /goal, 배포 상황 확인처럼 주기적 재확인이 필요하면 /loop가 각각 맞다. 커뮤니티 글 일부는 /goal를 Codex 기능으로 소개하지만, 공식 문서 기준 Claude Code의 내장 명령이다.
잘 되는 프롬프트의 5가지 조건
- 범위를 작게 고정한다. 전체 서비스 대신 인증, API 한 묶음, 테스트 보강처럼 완료 가능한 단위로 자른다.
- 완료 조건을 명령형으로 적는다. “좋게 만든다” 대신 테스트 통과, 린트 오류 0개, 문서 파일 생성처럼 판정 가능한 결과를 쓴다.
- 매 반복에서 검증 명령을 실행하게 한다. 실패 로그를 다음 수정의 입력으로 사용해야 반복이 개선으로 이어진다.
- 진행 상황을 파일에 남긴다. 계획, 완료 항목, 막힌 이유를 저장소 안의 문서와 Git 커밋으로 남긴다.
- 막혔을 때의 탈출 조건을 둔다. 일정 횟수 뒤에는 억지로 완료를 선언하지 말고 시도한 방법과 차단 요인을 기록하게 한다.
완료 문구만 믿으면 안 되는 이유
<promise>COMPLETE</promise> 같은 문구는 루프를 멈추는 신호일 뿐 품질 보증서가 아니다. 에이전트가 작업을 오해한 채 문구를 출력할 수 있고, 테스트 자체가 잘못 작성됐을 수도 있다. 종료 조건은 다음처럼 여러 층으로 둔다.
| 검증 층 | 예시 | 실패 시 동작 |
|---|---|---|
| 정적 검사 | format, lint, type check | 오류 위치를 읽고 수정 |
| 자동 테스트 | unit·integration·회귀 테스트 | 실패 원인을 좁혀 재실행 |
| 변경 범위 | 허용 파일·금지 디렉터리 | 범위를 벗어난 변경 되돌리기 |
| 자원 한도 | 최대 반복·시간·토큰 예산 | 중단 후 차단 요인 기록 |
| 사람 검토 | diff·보안·배포 승인 | 승인 전 병합·배포 금지 |
어떤 작업에 맞고, 무엇은 피해야 하나?
| 적합한 작업 | 피해야 할 작업 |
|---|---|
| 명세가 고정된 기능 구현 | 요구사항이 계속 바뀌는 기획 |
| 테스트 추가와 회귀 오류 수정 | 주관적 UX·브랜드 판단 |
| 반복 가능한 리팩터링 | 운영 장애에 대한 무제한 자동 변경 |
| 문서·타입·린트 정리 | 비밀값·결제·삭제 권한이 필요한 작업 |
공식 플러그인 README도 명확한 성공 기준과 자동 검증이 있는 작업을 권하고, 사람의 판단이 필요한 작업이나 운영 환경 디버깅에는 적합하지 않다고 설명한다.
밤새 실행하기 전 안전 체크리스트
--max-iterations를 설정하고 비용·시간 상한도 별도로 둔다.- 프로덕션 자격증명, 배포 키, 개인 데이터가 작업 환경에 노출되지 않게 한다.
- 삭제·배포·결제·외부 전송 명령은 사람 승인 없이는 실행할 수 없게 한다.
- 별도 브랜치나 격리된 worktree에서 실행하고 시작 시점의 커밋을 남긴다.
- 테스트와 린트가 실패하면 완료 문구를 출력하지 않도록 프롬프트에 명시한다.
- 완료 뒤에는 사람이 diff, 의존성 변경, 보안 영향, 라이선스를 검토한다.
긴 실행의 비용은 모델, 컨텍스트 길이, 캐시 정책, 반복 횟수에 따라 크게 달라진다. 고정된 “시간당 비용”을 가정하지 말고 실제 토큰과 도구 호출을 기록해야 한다. 자세한 측정 항목은 AI 에이전트 비용 추적 가이드와 OpenTelemetry 추적 실무 글에서 확인할 수 있다.
랄프 루프와 일반 코딩 에이전트 중 무엇을 고를까?
짧은 수정이나 한 번의 명확한 질문은 일반 대화형 실행이 낫다. 실패를 보고 여러 번 고쳐야 하며 테스트로 완료를 판정할 수 있을 때 랄프 루프가 유용하다. 도구 선택 자체가 고민이라면 AI 코딩 에이전트 선택 기준 7가지를 함께 보면 된다.
자주 묻는 질문
랄프 위검 루프는 완전 자율 개발인가?
아니다. 반복 실행은 자동화할 수 있지만 명세, 권한, 테스트, 비용 한도, 최종 검토는 사람이 설계해야 한다. 특히 배포와 데이터 변경은 별도 승인을 두는 편이 안전하다.
완료 문구와 최대 반복 횟수 중 무엇이 더 중요한가?
둘 다 필요하지만 안전장치로는 최대 반복 횟수가 더 중요하다. 완료 문구는 정확히 일치하면 종료되므로 잘못된 조기 완료를 막지 못한다. 테스트 통과와 변경 범위 검사도 함께 둬야 한다.
Claude Code 외의 코딩 에이전트에서도 쓸 수 있나?
가능하다. 랄프는 특정 제품이 아니라 반복 패턴이다. 다만 각 도구의 비대화식 실행, 권한 모델, 세션 상태, 종료 코드가 다르므로 같은 셸 한 줄을 그대로 복사하기보다 해당 도구에 맞는 중단·검증 장치를 구현해야 한다.
랄프 루프와 /goal은 무엇이 다른가?
랄프 루프는 같은 프롬프트를 그대로 다시 넣어 반복하는 방식이고, /goal는 완료 조건을 별도 모델이 매 턴 판정해 조건이 충족될 때까지 다음 턴을 이어가는 방식이다. 반복 내용을 바꾸지 않는 단순 재시도는 랄프 루프가 맞고, 테스트 통과 같은 판정 가능한 종료 조건이 있다면 /goal가 더 안전하다.
참고 자료
- Geoffrey Huntley, Ralph Wiggum as a “software engineer”
- Anthropic Claude Plugins Public: ralph-loop
- Anthropic Claude Code Plugins Directory
- Claude Code 공식 플러그인 문서
- Claude Code 공식 문서, Keep Claude working toward a goal(/goal)
- Claude Code 공식 문서, Run a prompt repeatedly with /loop
공식 문서와 저장소를 2026년 9월 20일 다시 확인해 내장 명령 /goal·/loop 정보를 추가하고, 설치 명령과 종료 옵션을 재검증했다. ralph-loop 플러그인 저장소는 2026년 3월 28일 이후 변경이 없다.
