랄프 루프(ralph-loop) 플러그인 리뷰: 클로드 코드가 할 일 5개를 끝날 때까지 반복, 그냥 “모두 해 줘”와 비교

클로드 코드에 긴 일을 맡기면 중간에 “여기까지 했습니다” 하고 멈추는 일이 있습니다. ralph-loop(랄프 루프)는 Anthropic 공식 플러그인입니다. 클로드가 답을 끝내려 할 때마다 같은 요청을 다시 넣어, 정해 둔 완료 문구가 나올 때까지 일을 이어 가게 합니다. 모임 회비 정산기를 만드는 일과, 그 정산기에 기능 5개를 더하는 일을 플러그인 없이, 그리고 켜고 나눠 시키고 숨은 검사로 채점했습니다. 플러그인은 무료이고, 반복한 만큼 Claude 사용량이 듭니다.

결과부터 보기: 같은 할 일 5개, 세 가지로 시켜 보기

정산기에 붙일 기능 5개를 TODO.md에 적어 두고 세 가지로 시켰습니다. 체크 표시가 켜지는 때는 실제로 커밋된 시각입니다.

직접 눌러 보기: 세 가지 실행 재생 화면(“처음부터 재생”을 누르면 커밋 시각대로 체크가 켜짐)

따라 해 보기: 요청문과 실습 재료

할 일 목록(TODO.md)이 있는 프로젝트 폴더에서 클로드 코드를 열고, 플러그인을 깐 뒤 아래 명령을 보내면 이번 실험과 같습니다. 클로드 코드가 처음이라면 클로드 코드 설치 방법을 먼저 보세요. 실습 재료(zip)에는 두 실험의 시작 폴더(요구사항·TODO.md·테스트), 요청문, 채점 기준과 숨은 검사 스크립트, 실행 결과 파일을 넣었습니다.

/ralph-loop:ralph-loop "TODO.md에서 아직 체크하지 않은 항목 중 맨 위의 것 하나만 처리해 줘. 테스트를 더해 모두 통과하면 그 항목을 체크하고 git 커밋해 줘. TODO.md의 모든 항목이 체크돼 있을 때만 <promise>DONE</promise>라고 출력해 줘." --completion-promise DONE --max-iterations 8

좋은 결과라면 TODO.md의 항목이 위에서부터 하나씩 체크되고, 항목마다 커밋이 하나씩 쌓이며, 마지막 항목을 끝낸 답에 <promise>DONE</promise>가 나옵니다.

이번에 쓴 할 일 목록입니다. 시작 코드는 실험 1(아래)에서 플러그인 없이 만든 정산기입니다.

# 정산기 할 일

위에서부터 차례로 처리합니다. 끝낸 항목은 `- [ ]`를 `- [x]`로 바꿉니다. 항목마다 tests 폴더에 테스트를 더하고, 모든 테스트가 통과해야 끝낸 것으로 칩니다. spec.md에 해당 내용도 덧붙입니다.

- [ ] 빈 줄과 `#`으로 시작하는 줄은 건너뛴다. 오류 메시지의 줄 번호는 파일의 실제 줄 번호를 그대로 쓴다.
- [ ] 회원 줄에 같은 이름이 두 번 나오면 `1번째 줄: 회원 이름이 겹칩니다 '민수'`를 표준 오류로 알리고 종료 코드 1로 끝낸다.
- [ ] `--json` 옵션을 주면 `{"balances": {"민수": 32666, ...}, "transfers": [{"from": "하나", "to": "민수", "amount": 16000}, ...]}` 형식의 JSON만 출력한다(한글은 그대로, 순서는 일반 출력과 같게).
- [ ] 금액 끝에 `$`가 붙으면 달러다(예: `25$`, `"1,200.50$"`). `--rate 1400`처럼 환율을 주면 원으로 바꿔(원 미만 반올림) 계산한다. 달러 금액이 있는데 환율이 없으면 `3번째 줄: 환율(--rate)이 필요합니다`를 알리고 종료 코드 1.
- [ ] `--min 1000` 옵션을 주면 그 금액 미만 송금은 목록에서 빼고, 맨 끝에 `1,000원 미만 송금 2건은 생략했습니다` 한 줄을 찍는다(뺀 송금이 없으면 이 줄도 없음).

1단계. 플러그인 깔기 (약 1분)

플러그인은 스킬·명령·훅을 묶어 클로드 코드에 넣는 꾸러미입니다(스킬은 클로드 스킬 글 참고). ralph-loop에는 루프를 시작하는 /ralph-loop, 멈추는 /cancel-ralph, 설명을 보여 주는 /help 명령과 Stop 훅 하나가 들어 있습니다. Stop 훅은 클로드가 답을 끝내려는 순간 실행되는 스크립트입니다.

쓰려는 프로젝트 폴더에서 터미널에 아래 명령을 실행합니다. --scope local은 이 폴더에서만 켜는 옵션입니다.

claude plugin install ralph-loop@claude-plugins-official --scope local

이렇게 나오면 성공 ✔ Successfully installed plugin: ralph-loop@claude-plugins-official (scope: local)(플러그인 설치 성공, 범위: 이 폴더). 폴더 안 .claude/settings.local.json에 이 플러그인이 켜짐으로 적힙니다.

• 훅 스크립트가 jq와 perl을 씁니다. 맥에는 둘 다 기본으로 들어 있었습니다. jq: command not found가 나오면 jq를 먼저 설치합니다. 맥에서 홈브루를 쓴다면 brew install jq입니다(컴퓨터 전체에 설치됨).
• 윈도우에서는 훅이 bash로 돌아서 Git for Windows가 필요합니다. 공식 README에 따르면 WSL의 bash가 잡히면 훅이 실패하니 hooks.json의 명령을 Git Bash 경로로 바꾸라고 안내합니다(문서 기준, 이번에 시험하지 않음).

필요 없어지면 같은 폴더에서 아래 명령으로 지웁니다.

claude plugin uninstall ralph-loop@claude-plugins-official --scope local

2단계. 루프 걸기: 완료 문구와 최대 횟수 (약 1분)

명령 형식은 /ralph-loop:ralph-loop "요청" --completion-promise 완료문구 --max-iterations 횟수입니다. 대화창에서는 짧게 /ralph-loop로 불러도 됩니다. 요청 안에 “다 끝났을 때만 <promise>완료문구</promise>라고 출력해”를 꼭 넣습니다.

• 완료 문구: 클로드의 마지막 답에 <promise>DONE</promise>가 들어 있으면 훅이 루프를 끝냅니다. 글자가 정확히 같아야 합니다.
• 최대 횟수: 이 횟수에 닿으면 완료 문구가 없어도 멈춥니다. 둘 다 안 주면 끝없이 돕니다. README도 최대 횟수를 늘 걸라고 권합니다.
• 중간에 멈추기: /cancel-ralph. 상태 파일 .claude/ralph-loop.local.md를 지워 다음 반복을 막습니다.

시작하면 설정 스크립트가 상태 파일을 만들고 “거짓으로 완료 문구를 말하지 말 것”이라는 영어 안내를 붙입니다. 클로드가 답을 끝내려 하면 훅이 같은 요청을 다시 넣고 회차를 하나 올립니다. 실험 2에서 랄프 루프로 처음 돌린 실행의 세션 기록에서 훅이 남긴 줄입니다.

실행 기록 · 작업 폴더 · 실험 2 랄프 루프 첫 번째 실행의 세션 기록에서 옮김

🔄 Ralph iteration 2 | To stop: output <promise>DONE</promise> (ONLY when statement is TRUE - do not lie to exit!)
🔄 Ralph iteration 3 | To stop: output <promise>DONE</promise> (ONLY when statement is TRUE - do not lie to exit!)
🔄 Ralph iteration 4 | To stop: output <promise>DONE</promise> (ONLY when statement is TRUE - do not lie to exit!)
🔄 Ralph iteration 5 | To stop: output <promise>DONE</promise> (ONLY when statement is TRUE - do not lie to exit!)
✅ Ralph loop: Detected <promise>DONE</promise>

뜻은 “랄프 반복 2회차. 멈추려면 <promise>DONE</promise>를 출력(사실일 때만, 빠져나가려고 거짓말하지 말 것)”이고, 마지막 줄은 “완료 문구를 찾았다”입니다. 한 번에 묻고 끝내는 방식(claude -p)으로 보냈는데도 반복이 그대로 돌았습니다.

실험 2. 할 일 5개: 하나만 요청 vs 랄프 루프 vs 모두 요청

채점 기준은 실행 전에 README의 프롬프트 작성 요령(단계별 목표, 테스트로 스스로 확인, 분명한 완료 기준)과 TODO.md 항목에서 뽑아 고정했고, 요청문에는 넣지 않았습니다. 다섯 기능을 각각 실제로 실행해 보는 숨은 검사 5개에 테스트 통과, TODO 체크, 기존 기능이 깨지지 않았는지를 더해 8개입니다.

플러그인 없이 “하나만” 보낸 요청문은 위의 랄프 루프 명령 안 문장과 같고, “모두” 요청문은 아래입니다.

TODO.md의 항목을 모두 처리해 줘. 항목마다 테스트를 더해 모두 통과하면 그 항목을 체크하고 git 커밋해 줘. TODO.md의 모든 항목이 체크돼 있을 때만 <promise>DONE</promise>라고 출력해 줘.

검사	① 없음 · 하나만 (1·2)	② 랄프 루프 · 하나만 (1·2)	③ 없음 · 모두
테스트 모두 통과	✅ ✅	✅ ✅	✅
빈 줄·# 줄 건너뛰기, 실제 줄 번호	✅ ✅	✅ ✅	✅
겹치는 회원 이름 오류	❌ ❌	✅ ✅	✅
--json 출력	❌ ❌	✅ ✅	✅
달러 금액과 --rate 환율	❌ ❌	✅ ✅	✅
--min 작은 송금 생략	❌ ❌	✅ ✅	✅
TODO.md 5개 모두 체크	❌ ❌	✅ ✅	✅
기존 기능 그대로(실험 1 검사 11개)	✅ ✅	✅ ✅	✅
합계(8개 중)	3 · 3	8 · 8	8
반복 · 커밋	1회 · 1개	5회 · 5개 (둘 다)	1회 · 5개
걸린 시간	1분 안쪽 (둘 다)	4분 반쯤 · 3분 반쯤	4분쯤
사용량(API 단가)	0.40 · 0.40달러	1.43 · 1.25달러	1.23달러

①은 요청대로 맨 위 항목 하나를 끝내고 커밋한 뒤 멈췄습니다. 완료 문구는 내지 않았습니다. ②는 회차마다 다음 항목 하나를 처리해, 다섯 번째 회차에서 마지막 항목을 끝낸 답에 완료 문구를 넣었습니다. 요청이 “하나만”이라 회차와 항목이 딱 맞았습니다.

③을 보면 이 실험에서 플러그인이 해 준 일이 분명해집니다. “모두 처리해 줘”라고만 해도 클로드는 항목마다 테스트를 더하고 커밋을 따로 나눠 5개를 끝냈습니다. 결과, 시간, 사용량이 ②와 거의 같았습니다. 랄프 루프는 클로드가 멈추는 지점에서 같은 요청을 다시 넣어 줄 뿐이라, 처음부터 멈추지 않는 일에는 더해 주는 것이 없습니다.

실험 1. 한 번에 끝나는 일에서는 차이 없음

먼저 빈 폴더에서 요구사항 문서(spec.md)대로 모임 회비 정산기를 새로 만드는 일을 시켰습니다. 요구사항에는 남는 원 배분, 송금 순서, 오류 메시지 형식처럼 놓치기 쉬운 조건을 넣었고, 보이는 테스트는 2개만 두고 나머지는 숨은 검사 11개로 채점했습니다. 요청문은 두 조건이 같습니다.

spec.md 요구사항대로 모임 회비 정산기 settle.py를 만들어 줘. tests 폴더의 테스트가 모두 통과해야 하고, README.md에 사용법을 써 줘. 요구사항을 하나도 빠짐없이 지켰는지 확인한 뒤, 모두 끝났을 때만 <promise>DONE</promise>라고 출력해 줘.

	플러그인 없음 (1·2)	랄프 루프 (1·2)
숨은 검사(11개 중)	11 · 11	11 · 11
반복	–	1회 · 1회
걸린 시간	1분 반 · 2분쯤	1분 반 · 2분쯤
사용량(API 단가)	0.50 · 0.56달러	0.54 · 0.53달러

네 번 모두 스스로 입력 파일을 만들어 요구사항을 하나씩 확인한 뒤 완료 문구를 냈습니다. 랄프 루프 쪽은 1회차 답에서 완료 문구를 찾은 훅이 바로 루프를 끝냈습니다. 랄프 루프 두 번째 실행은 마지막 답을 영어로 썼는데, 설정 스크립트가 붙이는 영어 안내문의 영향으로 보입니다. 한국어로 받고 싶다면 요청에 “답은 한국어로”를 넣으면 됩니다.

이런 사람에게 권합니다

• ✅ 할 일이 수십 개라 한 번 요청으로는 중간에 멈추는 일을 자리를 비운 동안 끝까지 돌리고 싶은 사람. 최대 횟수만 걸어 두면 완료 문구가 나오거나 횟수가 찰 때까지 알아서 이어 갑니다.
• ✅ “테스트가 모두 통과할 때까지”처럼 기계로 확인할 수 있는 완료 기준이 있는 일. README도 이런 일을 맞는 쓰임으로 꼽습니다.
• ❌ 이번 실험처럼 한 번 요청으로 끝나는 크기의 일. “모두 처리해 줘”로 충분했고, 결과는 같고 비용도 비슷했습니다.
• ❌ 디자인 고르기처럼 사람이 판단해야 하는 일. README도 맞지 않는 쓰임으로 꼽습니다.

한계와 주의할 점

• 할 일 5개짜리 파이썬 프로젝트 하나로, 조건마다 한두 번씩만 돌렸습니다. 클로드가 중간에 멈출 만큼 긴 일은 시험하지 않았습니다.
• 반복은 같은 대화 안에서 이어집니다. 원래 랄프 기법(Geoffrey Huntley)은 셸의 while 반복문으로 같은 요청 파일을 계속 넣는 방식이고, 이 플러그인은 그것을 Stop 훅으로 대화 하나 안에 옮겼습니다. 그래서 회차가 늘수록 대화가 길어집니다. 실험 2의 랄프 루프는 대화 하나에 55~57턴까지 갔습니다.
• 완료 문구는 클로드가 스스로 판단해 냅니다. 이번에는 아홉 번 모두 실제 상태와 맞았지만, 숨은 검사로 따로 확인하기 전에는 알 수 없습니다. 테스트처럼 기계로 확인할 기준을 요청에 넣어 두세요.
• 상태 파일은 프로젝트 폴더 안에 하나만 생깁니다. 같은 폴더에 다른 클로드 코드 창을 열어도, 훅이 세션 번호를 비교하므로 그 창은 반복에 묶이지 않습니다(훅 스크립트 기준).

대안

방법	다른 점	이럴 때 고르세요
ralph-loop(이 글)	같은 대화 안에서 완료 문구가 나올 때까지 같은 요청을 다시 넣음	길어서 중간에 멈추는 일을 끝까지 맡길 때
플러그인 없이 “모두 처리해 줘”	한 번 요청으로 끝까지. 이번 할 일 5개는 이것으로 충분	한 번에 끝날 크기의 일
셸 반복문 while + claude -p	원래 랄프 기법. 요청 파일을 셸에서 되풀이해 넣음(이번에 시험하지 않음)	몇 시간씩 도는 아주 긴 일
예약 작업	정해진 시각마다 새 대화로 같은 지시를 실행	매일·매시 되풀이하는 일
hookify 플러그인	훅으로 위험한 명령을 막음(반복과는 다른 쓰임)	루프를 오래 돌리기 전에 안전장치를 걸 때

자주 묻는 질문

랄프 위검(Ralph Wiggum)이 무슨 뜻인가요?

미국 만화 심슨 가족의 등장인물 이름입니다. README에 따르면 실패해도 계속 해 보는 모습에서 따온 이름이고, Geoffrey Huntley가 “랄프는 bash 반복문”이라고 소개한 기법을 플러그인으로 옮긴 것입니다.

루프를 중간에 멈추려면?

2단계의 /cancel-ralph를 씁니다. 터미널에서 .claude/ralph-loop.local.md 파일을 직접 지워도 다음 반복이 멈춥니다.

사용량이 얼마나 드나요?

반복한 만큼 듭니다. 이번 할 일 5개는 랄프 루프로 API 단가 1.25~1.43달러어치였고, 플러그인 없이 “모두” 요청한 것(1.23달러)과 비슷했습니다. 구독 요금제라면 그만큼 사용량 한도에서 빠집니다.

/ralph-loop를 쳤는데 명령을 못 찾는다고 나와요

플러그인을 깐 폴더에서 클로드 코드를 열었는지 확인하세요. --scope local로 깔면 그 폴더에서만 켜집니다. 짧은 이름이 안 되면 정식 이름 /ralph-loop:ralph-loop로 보냅니다.

출처

ralph-loop 플러그인 README·명령·훅 스크립트, anthropics/claude-plugins-official 저장소, Geoffrey Huntley, Ralph, 클로드 코드 훅 문서, 클로드 코드 플러그인 문서 (모두 2026-10-16 확인, 저장소 별 39,099개)