랄프루프 실전 구현 가이드 — Bash 한 줄에서 Cross-Model Review까지

이전 편에서 RLHF부터 컨텍스트 붕괴까지, AI 에이전트 루프가 겪어온 진화와 한계를 살펴봤습니다. 이번 편에서는 랄프루프가 이 문제를 어떻게 해결하는지 구체적인 구현 수준에서 파고듭니다.

코드 예시, 파일 구조, 아키텍처 다이어그램, 그리고 코딩을 넘어 프롬프트 정제에까지 적용한 실전 사례를 다룹니다.

---

최소 구현: while true + task.md

랄프루프의 핵심은 놀랍도록 단순합니다.

#!/bin/bash
while true; do
  cat task.md | claude -p
done

이 3줄이 전부입니다. 하지만 이 단순함 뒤에는 치밀한 설계 철학이 있습니다.

각 줄이 하는 일

코드	역할
while true	무한 반복. 에이전트가 종료되면 즉시 재시작
cat task.md	매 반복마다 원본 태스크를 stdin으로 전달
claude -p	비대화형 모드. 프롬프트 실행 후 자동 종료

매 반복이 시작될 때마다 이전 세션의 대화 기록은 완전히 소멸합니다. 컴퓨터의 메모리 할당(malloc)처럼, LLM이 작업에 필요한 정보만 파일에서 재구성하여 주입받습니다. 이전 시도의 잘못된 추론, 깨진 코드 패턴, 불필요한 에러 로그는 세션 종료와 함께 휘발되고, 오직 코드베이스의 실질적 진전만 남습니다.

Stop Hook: 에이전트의 탈출을 방지하다

기본적인 while 루프에는 한 가지 문제가 있습니다. LLM이 “작업 완료”를 선언하고 종료하면 루프가 같은 작업을 다시 시작합니다. 이미 끝난 작업을 반복하는 낭비가 발생합니다.

Stop Hook은 에이전트의 종료 시도를 가로채서 원래 태스크를 재주입하는 메커니즘입니다.

# Claude Code의 stop hook 예시 (.claude/hooks/stop.sh)
#!/bin/bash
# 에이전트가 종료하려 할 때 실행됨
if ! grep -q "ALL_TASKS_COMPLETE" ralph/progress.md; then
  echo "아직 미완료 태스크가 있습니다. task.md를 다시 확인하세요."
  exit 1  # 종료 차단 → 에이전트 계속 실행
fi

이로써 에이전트는 모든 태스크를 실제로 완료하기 전에는 종료할 수 없게 됩니다. 성공 편향(Success Bias) 문제를 구조적으로 차단하는 장치입니다.

---

파일 시스템 = 에이전트의 장기 기억

대화 기록을 매번 폐기하면 에이전트는 자신이 어느 단계에 있는지 망각합니다. 랄프루프는 이 문제를 로컬 파일 시스템으로 해결합니다. 파일 자체가 모델의 기억을 대체합니다.

상태 파일 구조

project/
├── task.md              ← 원본 PRD. 불변의 진실 원천 (Source of Truth)
├── .ralph/
│   ├── iteration.txt    ← 현재 루프 카운트
│   ├── work-summary.txt ← Worker가 이번 루프에서 수행한 내역
│   ├── feedback.txt     ← Reviewer의 오류/수정 지시
│   └── progress.md      ← 체크리스트 형태의 진행 상황
├── src/                 ← 실제 코드 (Git으로 관리)
└── tests/               ← 테스트 코드 (성공/실패 판단 기준)

파일	생성자	읽는 주체	역할
task.md	인간	매 루프의 Worker	불변의 태스크 명세. 매 루프의 시작점
iteration.txt	시스템	Worker	현재 몇 번째 루프인지 추적
work-summary.txt	Worker	Reviewer	이번 루프에서 뭘 했는지 요약
feedback.txt	Reviewer	다음 루프의 Worker	이전 실패 원인 + 수정 방향
progress.md	Worker	Worker + Stop Hook	체크리스트. 미완료 항목 추적

핵심 원칙: LLM의 컨텍스트 윈도우는 휘발성 작업 메모리(Working Memory)이고, 파일 시스템이 영속적 장기 기억(Long-term Memory)입니다.

---

Cross-Model Review 아키텍처

단순히 코드를 무한정 생성하면 시스템을 망가뜨릴 수 있습니다. 최신 랄프루프 구현체는 Worker와 Reviewer를 물리적으로 완전 분리하는 교차 모델 검토 아키텍처를 도입했습니다.

sequenceDiagram
    participant Loop as Bash Loop
    participant W as Worker (Claude Sonnet)
    participant R as Reviewer (GPT-4o)
    participant FS as File System

    Loop->>FS: cat task.md
    FS->>W: task.md + feedback.txt
    W->>FS: 코드 수정 + work-summary.txt
    W->>Loop: 종료
    Loop->>FS: cat work-summary.txt
    FS->>R: work-summary.txt + 변경된 코드
    R->>R: 테스트 실행 + 코드 리뷰

    alt 통과
        R->>FS: feedback.txt = "SHIP"
        R->>Loop: 종료
        Loop->>Loop: 루프 탈출 ✅
    else 실패
        R->>FS: feedback.txt = "REVISE: 구체적 지적"
        R->>Loop: 종료
        Loop->>Loop: 다음 반복 시작
    end

Worker 레시피 (ralph-work.yaml)

Worker 모델(예: Claude Sonnet)은 다음을 수행합니다.

1. task.md에서 전체 목표 확인
2. feedback.txt에서 이전 Reviewer의 지적 사항 확인
3. progress.md에서 미완료 체크리스트 항목 식별
4. 코드 수정 실행
5. work-summary.txt에 변경 내역 작성
6. 세션 종료

Reviewer 레시피 (ralph-review.yaml)

전혀 다른 모델(예: GPT-4o)이 깨끗한 컨텍스트에서 기동됩니다.

1. Worker의 변경 사항을 git diff로 확인
2. 테스트 스위트 실행
3. 코드 품질 검토

모든 요구사항 충족 시 → feedback.txt에 SHIP 작성 → 루프 탈출. 결함 발견 시 → feedback.txt에 REVISE + 구체적 피드백 작성 → 다음 Worker 루프 호출.

왜 다른 모델을 쓰는가?

동일 모델이 생성하고 검토하면 자기 확증 편향(Self-confirmation bias)이 발생합니다. Claude가 작성한 코드를 Claude가 “잘 했다”고 평가할 확률이 높습니다. 서로 다른 모델이 교차 검토함으로써 이 편향을 구조적으로 차단합니다.

---

실전 예시 1: CLI 도구 마이그레이션 (코딩)

가장 전형적인 랄프루프 사용 사례입니다.

시나리오

TypeScript 기반 CLI 도구를 Python으로 완전 마이그레이션해야 합니다. 파일 42개, 함수 180개.

task.md

# Task: TypeScript → Python Migration

## Goal
Migrate the CLI tool from TypeScript to Python 3.12.
All existing tests must pass in the Python version.

## Checklist
- [ ] src/cli.ts → src/cli.py
- [ ] src/parser.ts → src/parser.py
- [ ] src/formatter.ts → src/formatter.py
- [ ] ... (42 files total)
- [ ] All unit tests pass
- [ ] All integration tests pass
- [ ] Type hints complete (mypy strict)

실행 과정

Iteration 1: cli.py, parser.py 마이그레이션. 테스트 12/42 통과.
Iteration 2: formatter.py 마이그레이션. feedback: "datetime 처리 불일치". 수정 후 테스트 20/42.
Iteration 3: 나머지 모듈 마이그레이션. 테스트 35/42.
Iteration 4: 실패 테스트 7개 디버깅. 테스트 40/42.
Iteration 5: edge case 2개 수정. 테스트 42/42. SHIP.

5번의 반복, 각각 fresh context. 만약 단일 세션에서 시도했다면 Iteration 3 쯤에서 컨텍스트 붕괴가 시작되었을 것입니다.

---

실전 예시 2: 프롬프트 품질 반복 개선 (비코딩)

랄프루프는 코딩 전용이 아닙니다. 프롬프트, 설정, 워크플로우의 반복 정제에도 그대로 적용됩니다.

시나리오

Slack 봇의 일일 뉴스 큐레이션 품질이 불만족스럽습니다. 인사이트가 얕고, 소스가 편향되어 있으며, 관련 없는 뉴스가 혼입됩니다.

파일 구조

project/ralph/
├── PROMPT.md            ← Worker 작업 지시
├── quality-spec.md      ← 품질 기준 (= task.md)
├── sample-input.md      ← 테스트용 뉴스 데이터
├── iteration.txt        ← 루프 카운트
├── feedback.md          ← Reviewer 피드백
├── evaluation.md        ← (Worker 생성) 점수 결과
└── simulated-output.md  ← (Worker 생성) 시뮬레이션

매 반복의 Worker 작업

1. feedback.md에서 이전 Reviewer 피드백 확인
2. 현재 큐레이션 프롬프트 읽기 (src/crons/daily-signal.ts)
3. sample-input.md의 뉴스 데이터로 출력 시뮬레이션
4. quality-spec.md 기준으로 0-10점 자체 평가
5. 8점 미만이면 프롬프트의 가장 약한 부분 1-2가지만 수정
6. 변경 내용을 feedback.md에 기록

quality-spec.md 예시 (발췌)

## 점수 기준 (0-10)

| 항목 | 가중치 | 기준 |
|---|---|---|
| 관련성 | 30% | 15개 중 AI 전략/방법론 관련 비율 |
| 인사이트 깊이 | 25% | "왜 중요한가" 답변 수준 |
| 소스 다양성 | 15% | 한국 커뮤니티 + AI 블로그 포함 여부 |
| 노이즈 제거 | 15% | 무관 뉴스 혼입 건수 |
| 헤드라인 구체성 | 15% | 수치/이름 + 분석적 관점 |

SHIP 기준: 총점 8.0 이상

실행 과정

Iteration 1: 인사이트 프롬프트에 "왜 중요한가" 지시 추가. 점수 5.2 → 6.1
Iteration 2: 카테고리를 5개→5개로 재설계 (method 신설). 점수 6.1 → 7.0
Iteration 3: Must-Read 3개 분리 + 2문장 인사이트 요구. 점수 7.0 → 7.8
Iteration 4: 노이즈 제거 EXCLUDE 규칙 강화. 점수 7.8 → 8.3. SHIP.

코드 한 줄 안 건드리고, 프롬프트만 4번 반복 수정해서 품질 기준을 달성했습니다.

---

실전 예시 3: 테스트 커버리지 자동 확장

시나리오

기존 코드베이스의 테스트 커버리지가 40%입니다. 80% 이상으로 올려야 합니다.

task.md

# Task: Test Coverage 40% → 80%

## Goal
Add unit tests to reach 80% line coverage.
Do not modify existing source code — tests only.

## Rules
- One test file per source file
- Use existing test patterns in tests/ directory
- Run: npm test -- --coverage after each change

## Progress tracking
Update this checklist after each file:
- [ ] src/auth.ts (0% → ?)
- [ ] src/api.ts (30% → ?)
- [ ] src/utils.ts (60% → ?)
- ... (20 files)

이 작업은 랄프루프에 이상적입니다. 각 반복은 독립적이고(파일별 테스트 작성), 성공 기준이 명확하며(커버리지 수치), 실패해도 다음 반복에서 이어갈 수 있습니다.

---

오픈소스 생태계

랄프루프 컨셉은 빠르게 생태계로 확산되었습니다.

프로젝트	설명	특징
snarktank/ralph	커뮤니티 메인 구현체 (10K+ stars)	Bash 기반, 다양한 AI CLI 지원
vercel-labs/ralph-loop-agent	Vercel Labs AI SDK 통합	npm 패키지 배포
PageAI-Pro/ralph-loop	Docker 샌드박스 프로덕션 구현	격리 환경에서 안전 실행
ClaytonFarr/ralph-playbook	방법론 가이드	Worker-Reviewer 레시피 표준화
mikeyobrien/ralph-orchestrator	Rust 기반 오케스트레이터	7개 AI 백엔드 지원
Anthropic ralph-wiggum	Claude Code 공식 플러그인	Boris Cherny(리드 엔지니어) 엔도스

변형 패턴도 활발합니다.

• RALPHA: Cursor용 Recursive Author Loop
• Ralph Mode: Deep Agents 내장 모드
• LangChain, 다중 AI CLI 통합 어댑터

---

한국 생태계의 폭발적 수용

개발자 슬랭

그 작업 그냥 랄프 돌려놔 = “AI한테 밤새 시켜놔”

주요 한국어 커버리지

WikiDocs(박재홍 실리콘밸리 블로그), AI타임스, PyTorch Korea, Inflearn(영상 튜토리얼), Dale Seo 엔지니어링 블로그, GeekNews(news.hada.io), TILNOTE.

알리바바 클라우드도 “From ReAct to Ralph Loop: A Continuous Iteration Paradigm for AI Agents”라는 기술 딥다이브를 발표하며 엔터프라이즈 수준의 관심을 보였습니다.

랄프톤(Ralphathon) — 2026.03

한국에서 세계 최초로 랄프루프 기반 해커톤이 열렸습니다.

• 주최: 팀어텐션 + 카카오벤처스, OpenAI 후원
• 포맷: 인간은 스펙만 설계. AI가 밤새 코딩
• 1등 팀 성과: AI가 100,000 LOC 작성 (70%가 테스트 코드). 인간 키보드 입력 0

70%가 테스트 코드라는 점이 주목할 만합니다. 랄프루프의 Worker-Reviewer 구조에서 테스트가 “성공 기준”의 역할을 하기 때문에, 에이전트가 자연스럽게 테스트를 두텁게 작성한 결과입니다.

---

랄프루프 실행을 위한 체크리스트

랄프루프를 실제로 세팅할 때 확인해야 할 것들입니다.

필수 조건

• 명확한 task.md: 에이전트가 매 루프에서 “뭘 해야 하는지” 즉시 파악 가능해야 함
• 기계적 성공 기준: 테스트 통과, 커버리지 수치, 빌드 성공 등 자동 판단 가능한 기준
• Git 초기화: 매 루프의 변경사항이 커밋으로 추적되어야 함

권장 사항

• Stop Hook 설정: 에이전트의 조기 종료 방지
• Cross-Model Review: Worker와 Reviewer를 다른 모델로 분리
• iteration 상한선: 무한 루프 방지 (5-10회)
• CLAUDE.md / .cursorrules: 프로젝트 컨벤션을 파일로 명시

주의 사항

• 테스트 코드 없이 돌리면 → 무한 삽질기 (성공 판단 불가)
• task.md가 모호하면 → 매 루프마다 다른 방향으로 발산
• 소스 코드만 변경하고 테스트를 안 돌리면 → Worker의 자기 만족 선언

graph TD
    A{"테스트 코드 있음?"} -->|예| B{"task.md 명확?"}
    A -->|아니오| X["❌ 먼저 테스트 작성"]
    B -->|예| C{"성공 기준 자동 판단?"}
    B -->|아니오| Y["❌ task.md 구체화 필요"]
    C -->|예| D["✅ 랄프루프 실행 가능"]
    C -->|아니오| Z["⚠️ 수동 리뷰 필요 (반자동 루프)"]

---

핵심 정리

랄프루프의 기술적 본질을 한 문장으로 요약하면:

컨텍스트 윈도우를 휘발성 작업 메모리로, 파일 시스템을 영속적 장기 기억으로, Git을 감사 추적으로 사용하는 무한 반복 아키텍처.

이 단순한 구조가 컨텍스트 붕괴 문제를 근본적으로 해결하며, 코딩뿐 아니라 프롬프트 정제, 설정 튜닝, 문서 품질 개선 등 모든 반복 정제 작업에 동일하게 적용됩니다.

다음 편에서는 랄프루프를 넘어, 에이전트가 스스로 가중치를 업데이트하는 자율 진화 시스템(Self-Evolving Agents) 과 AI 개발자의 역할 변화를 다룹니다.

---

이전 편: AI 에이전트 루프의 진화 — RLHF에서 랄프루프까지

다음 편: 랄프루프 너머 — 자율 진화 에이전트와 AI 개발자의 역할 변화