랄프 위검 루프(Ralph Wiggum Loop)는 같은 작업 프롬프트를 AI 코딩 에이전트에 반복 투입하고, 파일·테스트 결과를 다음 반복의 피드백으로 쓰는 개발 방식이다. 핵심은 밤새 무한 실행하는 데 있지 않다. 명확한 완료 조건, 자동 검증, 반복 한도, 제한된 권한을 함께 설계해야 실무에 쓸 수 있다.

랄프 위검 루프란?

Geoffrey Huntley가 공개한 원형은 놀랄 만큼 단순하다. 프롬프트 파일을 코딩 에이전트에 넣는 과정을 셸의 while 루프로 반복한다. 한 번의 실행이 끝나도 수정된 코드, 작업 메모, Git 기록은 저장소에 남는다. 다음 실행은 이 결과를 읽고 남은 일을 계속한다.

while :; do
  cat PROMPT.md | claude-code
done

이름은 심슨 가족의 캐릭터 랄프 위검에서 왔다. 첫 시도에 완벽한 답을 기대하기보다 실패 결과를 다시 입력해 끈질기게 개선한다는 비유다. 다만 “사람 없이 알아서 완성하는 개발자”라기보다 검증 가능한 작업을 반복 실행하는 자동화 패턴으로 이해하는 편이 정확하다.

원형 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를 명시하는 우회 방법을 안내한다.

잘 되는 프롬프트의 5가지 조건

1. 범위를 작게 고정한다. 전체 서비스 대신 인증, API 한 묶음, 테스트 보강처럼 완료 가능한 단위로 자른다.
2. 완료 조건을 명령형으로 적는다. “좋게 만든다” 대신 테스트 통과, 린트 오류 0개, 문서 파일 생성처럼 판정 가능한 결과를 쓴다.
3. 매 반복에서 검증 명령을 실행하게 한다. 실패 로그를 다음 수정의 입력으로 사용해야 반복이 개선으로 이어진다.
4. 진행 상황을 파일에 남긴다. 계획, 완료 항목, 막힌 이유를 저장소 안의 문서와 Git 커밋으로 남긴다.
5. 막혔을 때의 탈출 조건을 둔다. 일정 횟수 뒤에는 억지로 완료를 선언하지 말고 시도한 방법과 차단 요인을 기록하게 한다.

완료 문구만 믿으면 안 되는 이유

<promise>COMPLETE</promise> 같은 문구는 루프를 멈추는 신호일 뿐 품질 보증서가 아니다. 에이전트가 작업을 오해한 채 문구를 출력할 수 있고, 테스트 자체가 잘못 작성됐을 수도 있다. 종료 조건은 다음처럼 여러 층으로 둔다.

검증 층	예시	실패 시 동작
정적 검사	format, lint, type check	오류 위치를 읽고 수정
자동 테스트	unit·integration·회귀 테스트	실패 원인을 좁혀 재실행
변경 범위	허용 파일·금지 디렉터리	범위를 벗어난 변경 되돌리기
자원 한도	최대 반복·시간·토큰 예산	중단 후 차단 요인 기록
사람 검토	diff·보안·배포 승인	승인 전 병합·배포 금지

어떤 작업에 맞고, 무엇은 피해야 하나?

적합한 작업	피해야 할 작업
명세가 고정된 기능 구현	요구사항이 계속 바뀌는 기획
테스트 추가와 회귀 오류 수정	주관적 UX·브랜드 판단
반복 가능한 리팩터링	운영 장애에 대한 무제한 자동 변경
문서·타입·린트 정리	비밀값·결제·삭제 권한이 필요한 작업

공식 플러그인 README도 명확한 성공 기준과 자동 검증이 있는 작업을 권하고, 사람의 판단이 필요한 작업이나 운영 환경 디버깅에는 적합하지 않다고 설명한다.

밤새 실행하기 전 안전 체크리스트

• --max-iterations를 설정하고 비용·시간 상한도 별도로 둔다.
• 프로덕션 자격증명, 배포 키, 개인 데이터가 작업 환경에 노출되지 않게 한다.
• 삭제·배포·결제·외부 전송 명령은 사람 승인 없이는 실행할 수 없게 한다.
• 별도 브랜치나 격리된 worktree에서 실행하고 시작 시점의 커밋을 남긴다.
• 테스트와 린트가 실패하면 완료 문구를 출력하지 않도록 프롬프트에 명시한다.
• 완료 뒤에는 사람이 diff, 의존성 변경, 보안 영향, 라이선스를 검토한다.

긴 실행의 비용은 모델, 컨텍스트 길이, 캐시 정책, 반복 횟수에 따라 크게 달라진다. 고정된 “시간당 비용”을 가정하지 말고 실제 토큰과 도구 호출을 기록해야 한다. 자세한 측정 항목은 AI 에이전트 비용 추적 가이드와 OpenTelemetry 추적 실무 글에서 확인할 수 있다.

랄프 루프와 일반 코딩 에이전트 중 무엇을 고를까?

짧은 수정이나 한 번의 명확한 질문은 일반 대화형 실행이 낫다. 실패를 보고 여러 번 고쳐야 하며 테스트로 완료를 판정할 수 있을 때 랄프 루프가 유용하다. 도구 선택 자체가 고민이라면 AI 코딩 에이전트 선택 기준 7가지를 함께 보면 된다.

자주 묻는 질문

랄프 위검 루프는 완전 자율 개발인가?

아니다. 반복 실행은 자동화할 수 있지만 명세, 권한, 테스트, 비용 한도, 최종 검토는 사람이 설계해야 한다. 특히 배포와 데이터 변경은 별도 승인을 두는 편이 안전하다.

완료 문구와 최대 반복 횟수 중 무엇이 더 중요한가?

둘 다 필요하지만 안전장치로는 최대 반복 횟수가 더 중요하다. 완료 문구는 정확히 일치하면 종료되므로 잘못된 조기 완료를 막지 못한다. 테스트 통과와 변경 범위 검사도 함께 둬야 한다.

Claude Code 외의 코딩 에이전트에서도 쓸 수 있나?

가능하다. 랄프는 특정 제품이 아니라 반복 패턴이다. 다만 각 도구의 비대화식 실행, 권한 모델, 세션 상태, 종료 코드가 다르므로 같은 셸 한 줄을 그대로 복사하기보다 해당 도구에 맞는 중단·검증 장치를 구현해야 한다.

참고 자료

• Geoffrey Huntley, Ralph Wiggum as a “software engineer”
• Anthropic Claude Plugins Public: ralph-loop
• Anthropic Claude Code Plugins Directory
• Claude Code 공식 플러그인 문서

공식 문서와 저장소를 2026년 8월 28일 확인해 설치 명령, 플러그인 이름, 종료 옵션을 갱신했다.