snarktank/ralph 실전 가이드

서론

이전 글에서 Ralph의 핵심 원리인 무한 루프 + 매번 새로운 컨텍스트 + 파일을 진실의 원천으로 삼는 것을 살펴보았습니다. 세 가지 기둥은 간단해 보이지만, 이해에서 실제 구동까지는 적지 않은 세부 사항이 있습니다.

이번 글에서는 직접 실습해 보겠습니다. snarktank/ralph는 Ralph 방법론의 외부 루프 구현으로, 매번 반복할 때마다 완전히 새로운 Claude 프로세스를 시작하여 Context Rot 문제를 근본적으로 해결합니다. 현재 커뮤니티에서 가장 완성도 높은 Ralph 구현 중 하나(10k+ stars)이며, Claude Code와 Amp 양 플랫폼을 지원하고 PRD 생성, JSON 변환, 자동 실행의 전체 도구 체인을 제공합니다.

또 다른 구현 방식은 frankbria/ralph-claude-code로, 완전한 엔지니어링 도구 체인(모니터링 대시보드, 서킷 브레이커, 속도 제한)을 제공하며 제어 가능성과 안전 메커니즘에 중점을 두고 있습니다. 둘의 비교는 해당 글을 참고하시기 바랍니다.

사전 요구 사항

시작하기 전에 다음 환경 조건이 충족되었는지 확인하십시오:

# 의존성 확인
claude --version   # Claude Code CLI
jq --version       # JSON 처리
git --version      # Git

설치 및 구성

가장 간단한 방법은 Claude Code 대화에서 GitHub 링크를 직접 붙여넣는 것입니다:

帮我安装这个 skill：https://github.com/snarktank/ralph

Claude Code가 자동으로 저장소를 클론하고 skill 파일을 올바른 위치에 복사합니다. 설치가 완료되면 /prd와 /ralph 명령을 사용할 수 있습니다.

snarktank/ralph는 Marketplace 설치, 수동 skill 파일 복사, 프로젝트 수준 설치 등 다양한 방법도 지원합니다. 자세한 내용은 GitHub 저장소 설명을 참고하십시오.

핵심 파일 구조

Ralph의 기억은 완전히 파일 시스템에 의존합니다. 각 파일의 역할을 이해하는 것이 Ralph를 잘 활용하기 위한 전제 조건입니다.

ralph.sh — 루프 엔진

이것이 Ralph의 핵심입니다. 새로운 AI 인스턴스를 반복적으로 시작하는 bash 스크립트입니다.

# 기본 사용법
./scripts/ralph/ralph.sh [max_iterations]        # 기본적으로 Amp 사용
./scripts/ralph/ralph.sh --tool claude [iterations]  # Claude Code 사용

매번 반복할 때마다 ralph.sh는 다음과 같은 작업을 수행합니다:

1. 기능 브랜치 생성 (prd.json의 branchName 기반)
2. 가장 높은 우선순위의 미완료 story 선택 (passes: false)
3. 해당 story를 구현하기 위해 완전히 새로운 AI 인스턴스 시작
4. 품질 검사 실행 (타입 체크, 테스트)
5. 검사 통과 → git commit; 실패 → 다음 반복으로 넘김
6. prd.json 업데이트, story를 passes: true로 표시
7. progress.txt에 이번에 배운 경험 추가
8. 모든 story가 완료되거나 반복 상한에 도달할 때까지 반복

기본 반복 상한은 10회입니다. 프로젝트 복잡도에 따라 조정하십시오:

# 간단한 프로젝트
./scripts/ralph/ralph.sh --tool claude 10

# 복잡한 프로젝트
./scripts/ralph/ralph.sh --tool claude 50

prd.json — 작업 정의

이것은 Ralph의 "두뇌"입니다. 모든 작업이 여기에 정의됩니다. 형식은 플랫한 JSON 파일입니다:

{
  "projectName": "블로그 i18n 번역",
  "branchName": "ralph/i18n-translation",
  "userStories": [
    {
      "id": "US-001",
      "title": "홈페이지 메타데이터 번역",
      "description": "content/docs/meta.en.json을 생성하고 모든 네비게이션 항목의 영어 번역을 포함",
      "acceptanceCriteria": [
        "meta.en.json 파일이 존재하고 JSON 형식이 올바름",
        "모든 네비게이션 제목이 영어로 번역됨",
        "pnpm types:check 통과"
      ],
      "priority": 1,
      "passes": false,
      "dependsOn": [],
      "notes": "기존 meta.json의 구조를 참고"
    },
    {
      "id": "US-002",
      "title": "블로그 게시글 hello-world 번역",
      "description": "content/blog/hello-world.en.mdx를 생성하고 중국어에서 영어로 번역",
      "acceptanceCriteria": [
        "hello-world.en.mdx 파일이 존재",
        "모든 QuoteCard 컴포넌트에 defaultLang='en' 설정",
        "내부 링크에 /en/ 접두사 사용",
        "코드 블록은 번역하지 않음",
        "pnpm types:check 통과"
      ],
      "priority": 2,
      "passes": false,
      "dependsOn": ["US-001"],
      "notes": "MDX 컴포넌트의 props 형식을 유지할 것"
    }
  ]
}

필드 설명:

progress.txt — 경험 로그

이것은 Ralph의 "장기 기억"입니다. 매번 반복이 끝난 후 AI가 이번에 배운 내용을 여기에 추가합니다:

=== Iteration 1 (US-001) ===
- Discovered: typecheck command is `pnpm types:check`, not `pnpm typecheck`
- Discovered: meta.en.json needs to mirror exact structure of meta.json
- Pattern: fumadocs i18n uses `.en.` suffix convention

=== Iteration 2 (US-002) ===
- Discovered: QuoteCard requires both `quote` and `quoteZh` props
- Gotcha: internal links must use /en/ prefix for English pages
- Pattern: code blocks should never be translated

다음 반복의 새로운 Claude 인스턴스가 이 파일을 읽어 이전의 모든 경험을 즉시 획득합니다. 이것이 Ralph가 반복할수록 점점 원활하게 실행되는 이유입니다 — 지식은 반복 간에 축적되지만 컨텍스트는 깨끗하게 유지됩니다.

AGENTS.md — 영구 지식 베이스

progress.txt 외에도 Ralph는 프로젝트의 AGENTS.md 파일(또는 CLAUDE.md)도 업데이트합니다. Claude Code와 Amp 모두 시작 시 이 파일들을 자동으로 읽습니다.

progress.txt와 달리, AGENTS.md에는 안정적이고 프로젝트 간에 범용적인 지식이 기록됩니다:

# AGENTS.md

## Codebase Conventions
- Use fumadocs for documentation framework
- MDX files use custom components: QuoteCard, BlogImage, GlossaryCard
- i18n files use `.en.mdx` suffix

## Gotchas
- Always run `pnpm types:check` after modifying MDX files
- QuoteCard: set `defaultLang='en'` in English translations

PRD 작성

PRD(Product Requirements Document)의 품질이 Ralph의 실행 효과를 직접적으로 결정합니다. 잘 작성하면 Ralph가 순조롭게 진행되고, 잘못 작성하면 같은 story에서 반복적으로 실패하게 됩니다.

Skill을 사용한 PRD 생성

snarktank/ralph의 skill을 설치했다면 대화형 방식으로 PRD를 생성할 수 있습니다:

# Claude Code 또는 Amp에서
/prd 我想为博客系统添加 i18n 支持，需要将所有中文内容翻译成英文

AI가 일련의 명확화 질문(관련 파일, 기술 스택 제약 조건, 품질 기준 등)을 한 다음 구조화된 PRD 문서를 생성합니다.

생성 후 /ralph 명령으로 PRD를 prd.json 형식으로 변환합니다:

/ralph    # PRD를 prd.json으로 변환

수동 PRD 작성

prd.json을 직접 작성할 수도 있습니다. 다음은 핵심 설계 원칙입니다.

원칙 1: Story 단위를 적절하게

각 story는 한 번의 반복으로 완료할 수 있을 만큼 작아야 하고, 독립적인 납품 가치가 있을 만큼 커야 합니다.

// ❌ 너무 큼: 한 번의 반복으로 완료 불가
{
  "id": "US-001",
  "title": "완전한 사용자 인증 시스템 구축",
  "description": "회원가입, 로그인, 비밀번호 찾기, OAuth, 권한 관리 구현..."
}

// ❌ 너무 작음: 독립적인 가치 없음
{
  "id": "US-001",
  "title": "User 테이블의 email 필드 생성",
  "description": "User 모델에 email 필드 추가"
}

// ✅ 적절함: 한 번에 완료 가능, 독립적 가치 있음
{
  "id": "US-001",
  "title": "이메일 비밀번호 로그인 구현",
  "description": "로그인 API와 로그인 페이지 생성, 이메일 비밀번호 인증 지원",
  "acceptanceCriteria": [
    "POST /api/auth/login이 email + password를 수신",
    "JWT token 반환",
    "로그인 페이지 폼 제출 가능",
    "모든 테스트 통과"
  ]
}

경험 법칙: 하나의 story는 13개의 파일 수정을 포함하고, 35개의 인수 기준을 갖습니다.

원칙 2: 인수 기준은 자동 검증 가능해야 함

Ralph는 story의 완료 여부를 판단해야 하므로 인수 기준은 객관적으로 판정할 수 있어야 합니다:

// ❌ 모호한 기준
"acceptanceCriteria": [
  "코드 품질이 좋음",
  "성능이 좋음",
  "사용자 경험이 원활함"
]

// ✅ 검증 가능한 기준
"acceptanceCriteria": [
  "pnpm types:check 통과",
  "pnpm test 통과",
  "API 응답 시간 < 200ms",
  "파일 src/auth/login.ts가 존재하고 loginHandler 함수를 export함"
]

원칙 3: dependsOn으로 순서 제어

story 간에 의존 관계가 있는 경우 dependsOn 필드로 Ralph가 올바른 순서로 실행하도록 보장합니다:

{
  "userStories": [
    {
      "id": "US-001",
      "title": "데이터베이스 스키마 생성",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "사용자 등록 API 구현",
      "dependsOn": ["US-001"]
    },
    {
      "id": "US-003",
      "title": "로그인 페이지 구현",
      "dependsOn": ["US-002"]
    }
  ]
}

원칙 4: notes에 컨텍스트 제공

notes 필드는 AI에게 제공하는 추가 힌트입니다. 여러분은 알고 있지만 AI가 모를 수 있는 정보를 여기에 작성하십시오:

{
  "notes": "프로젝트는 fumadocs 프레임워크를 사용합니다. i18n 파일 명명 규칙은 .en.mdx 접미사입니다. content/docs/notes/speckit/concept.en.mdx의 번역 스타일을 참고하십시오."
}

Ralph Loop 실행

PRD가 준비되면 루프를 시작합니다.

실행 시작

# Claude Code 사용, 기본 10회 반복
./scripts/ralph/ralph.sh --tool claude

# 반복 횟수 지정
./scripts/ralph/ralph.sh --tool claude 30

# Amp 사용 (기본값)
./scripts/ralph/ralph.sh 20

실행 과정

시작하면 다음과 같은 출력을 볼 수 있습니다:

Starting Ralph - Tool: claude - Max iterations: 35

===============================================================
  Ralph Iteration 1 of 35 (claude)
===============================================================
## US-001 Complete

**Summary of what was done:**
1. Created meta.en.json with all navigation items translated
2. Ran pnpm types:check — PASSED
3. Committed: feat: [US-001] - Translate homepage metadata

There are still **15 user stories with `passes: false`** remaining.
The next story is **US-002: 翻译博客文章 hello-world**.
Iteration 1 complete. Continuing...

===============================================================
  Ralph Iteration 2 of 35 (claude)
===============================================================

매번 반복은 완전히 새로운 Claude 인스턴스입니다. prd.json을 읽어 현재 무엇을 해야 하는지 파악하고, progress.txt를 읽어 이전에 무엇을 배웠는지 파악합니다.

완료 신호

모든 story가 passes: true로 표시되면 Ralph는 완료 신호를 출력하고 종료합니다:

All stories completed!
<promise>COMPLETE</promise>

모니터링 및 디버깅

Ralph 실행 중에 다음 명령으로 진행 상황을 확인할 수 있습니다:

# 각 story의 완료 상태 확인 (아이콘 포함, 더 직관적)
cat tasks/prd.json | python3 -c "
import json,sys
for s in json.load(sys.stdin)['userStories']:
    print(f'{\"✅\" if s[\"passes\"] else \"⬜\"} {s[\"id\"]}: {s[\"title\"]}')"

# 또는 jq로 확인
cat tasks/prd.json | jq '.userStories[] | {id, title, passes}'

# 경험 로그 확인
cat progress.txt

# 최근 git 커밋 확인
git log --oneline -10

# Ralph 출력 실시간 확인
tail -f progress.txt

# 완료 후 메인 브랜치 대비 전체 변경 사항 확인
git diff main...ralph/your-branch-name --stat

중단 및 재개

Ralph 실행 시간이 길어질 수 있지만, 중간에 중단하는 것은 완전히 안전합니다:

• 중단: Ctrl+C로 직접 중단할 수 있습니다. 완료된 story(passes: true)는 손실되지 않으며, 이미 commit되고 prd.json에 기록되어 있습니다
• 재개: 동일한 명령을 다시 실행하면 Ralph가 첫 번째 passes: false story부터 자동으로 계속합니다

# 중단 후 재개, 동일한 명령을 다시 실행하기만 하면 됨
./scripts/ralph/ralph.sh --tool claude 35

특정 story가 반복적으로 실패하여 차단되는 경우, 수동으로 건너뛸 수 있습니다. prd.json을 편집하여 해당 story의 passes 필드를 true로 변경한 다음 다시 실행하면 Ralph가 이를 건너뛰고 후속 story를 계속 처리합니다.

자동 아카이브

새로운 branchName으로 다른 기능을 시작하면, Ralph가 이전 실행의 파일을 archive/YYYY-MM-DD-feature-name/ 디렉터리에 자동으로 아카이브하여 작업 디렉터리를 깔끔하게 유지합니다.

피드백 루프와 품질 게이트

Ralph의 "자기 교정" 능력은 전적으로 피드백 루프의 품질에 달려 있습니다. 피드백 루프가 없는 Ralph는 맹목적으로 루프하는 스크립트에 불과합니다 — 계속 코드를 생성하지만 코드가 올바른지 판단할 수 없습니다.

품질 검사 구성

CLAUDE.md(또는 prompt.md)에서 품질 검사 명령을 정의합니다:

## Quality Commands

After implementing each story, run these checks IN ORDER:

1. `pnpm types:check` — TypeScript type checking
2. `pnpm test` — Unit tests
3. `pnpm build` — Full build verification

If any check fails:
- DO NOT commit
- Fix the issue
- Re-run all checks
- Only commit when all checks pass

품질 게이트의 계층

프론트엔드 story의 경우, Ralph는 인수 기준에 "Verify in browser using dev-browser skill"을 추가할 것을 권장합니다 — AI가 실제로 브라우저를 열어 페이지 렌더링이 올바른지 확인하도록 합니다.

품질 검사 실패 시

특정 story의 품질 검사가 반복적으로 실패해도 Ralph는 같은 story를 무한히 재시도하지 않습니다. 반복 상한에 도달하면 멈추고 현재 상태를 남깁니다. 이 경우 다음과 같이 대처할 수 있습니다:

1. progress.txt를 확인하여 AI가 어디에서 막혔는지 확인
2. 수동으로 문제를 수정한 후 다시 실행
3. story의 단위 조정 (너무 클 수 있음)
4. notes에 더 많은 컨텍스트 보충

Prompt 커스터마이징

Ralph의 prompt 템플릿(CLAUDE.md 또는 prompt.md)은 AI 동작을 제어하는 주요 수단입니다. 설치 후 자신의 프로젝트에 맞게 커스터마이징해야 합니다. 주요 커스터마이징 방향:

코드 스타일 제약

## Code Conventions
- Use TypeScript strict mode
- Prefer named exports over default exports
- Use fumadocs components for MDX content
- Follow existing file naming patterns (kebab-case)

흔한 함정

## Known Gotchas
- MDX files: always import components at the top
- i18n: English files use `.en.mdx` suffix
- Links: English pages must use `/en/` prefix
- QuoteCard: set `defaultLang` to match the file language

막혔을 때의 처리 방법

## When Stuck
If you cannot complete a story after 3 attempts within the same iteration:
1. Document what's blocking in progress.txt
2. Move to the next story if possible
3. Do NOT modify files unrelated to the current story

실전 사례: Ralph로 블로그 i18n 번역 완료하기

Ralph가 실제 프로젝트에서 어떻게 작동하는지 보여드리기 위해, 여기서 실제 사례를 공유합니다: Ralph 스타일의 자율 agent를 사용하여 전체 블로그를 중국어에서 영어로 번역한 사례입니다.

프로젝트 설정

프로젝트에서는 22개 이상의 콘텐츠 파일(블로그 게시글, 문서, 네비게이션 메타데이터)을 중국어에서 영어로 번역해야 했으며, 목표는 fumadocs 기반의 Next.js 블로그 i18n 지원이었습니다. 작업은 prd.json 파일에 정의되어 있으며, 16개의 user story가 포함되고 각각 명확한 인수 기준이 있었습니다:

scripts/ralph/
├── prd.json          # 16개의 user story, 인수 기준 포함
└── progress.txt      # 경험 로그, 각 story 완료 후 업데이트

각 user story는 일관된 패턴을 따릅니다:

• 명확한 산출물: "Create content/blog/xxx.en.mdx"
• 검증 가능한 기준: "Typecheck passes", "Internal links use /en/ prefix"
• 기술적 제약: "Keep code blocks untranslated", "Set defaultLang='en' on QuoteCard"

실행 패턴

Agent는 Ralph 방법론의 핵심 원칙을 따랐습니다:

1. 파일이 진실의 원천: prd.json이 각 story의 상태(passes: true/false)를 추적합니다. progress.txt가 반복 간에 경험을 축적합니다 — 예를 들어 "Typecheck 명령은 pnpm types:check이며 pnpm typecheck가 아닙니다"

2. 자동화된 품질 게이트: 매번 번역 완료 후 pnpm types:check를 실행하여 MDX 파일이 올바르게 컴파일되는지 검증합니다. typecheck가 실패하면 먼저 문제를 수정한 후 커밋합니다.

3. 점진적 전진: 각 story를 독립적으로 커밋하고 설명적인 커밋 메시지를 사용합니다(feat: [US-003] - Translate blog/claude-code-quality-control.mdx). 필요 시 롤백이 용이합니다.

4. 병렬 실행: 긴 글의 경우 여러 subagent가 동시에 번역합니다 — 예를 들어 US-010(claude-skills concept + practice), US-011(speckit concept + practice), US-012(claude-architecture + claude-subagent)가 동시에 병렬 실행됩니다.

핵심 경험

성과

16개의 user story가 단일 세션에서 모두 완료되었습니다: 8개의 meta.en.json 네비게이션 파일 생성, 3개의 블로그 게시글 번역, 12개의 문서 페이지 번역, 전체 사이트 빌드 검증 통과. 인수 기준이 명확하고 피드백 루프(typecheck)가 문제를 즉시 발견할 수 있었기 때문에 각 번역은 일관된 품질을 유지했습니다.

이 프로젝트는 Ralph의 **전체 구현 모드(Full Implementation Mode)**를 보여줍니다 — 명확한 작업 정의, 명확한 성공 기준, 자동화된 검증, 그리고 파일 시스템을 통한 점진적 납품입니다.

모범 사례 및 자주 묻는 질문

비용 관리

Ralph의 자동 실행은 API 비용이 지속적으로 발생한다는 것을 의미합니다. 몇 가지 제어 수단이 있습니다:

• 항상 max_iterations를 설정하십시오: 이것이 가장 기본적인 안전망입니다
• Story 단위를 합리적으로 유지: 너무 큰 story는 여러 번의 반복을 소비하고, 너무 잘게 나눈 story는 시작 오버헤드를 증가시킵니다
• 먼저 소규모로 테스트: 새 프로젝트는 먼저 3~5회 반복으로 시험 실행하여 prompt와 품질 게이트가 정상 작동하는지 확인한 후 본격적으로 실행하십시오

흔한 함정

함정 1: Story가 너무 큼

증상: 하나의 story가 반복적으로 실패하고 반복 횟수가 빠르게 소진됩니다.

해결: 2~3개의 더 작은 story로 분할합니다. "완전한 인증 시스템 구축"을 "로그인 API 구현" + "로그인 페이지 생성" + "JWT 미들웨어 추가"로 분할합니다.

함정 2: 피드백 루프 없음

증상: Ralph가 story 완료를 선언하지만 실제 코드에 문제가 있습니다.

해결: 인수 기준에 실행 가능한 검사 명령을 포함합니다. "코드가 작성됨"은 인수 기준이 아니며, "pnpm test가 모두 통과"가 인수 기준입니다.

함정 3: progress.txt가 활용되지 않음

증상: 같은 오류가 다른 반복에서 반복적으로 발생합니다.

해결: prompt 템플릿에 "progress.txt를 읽고 그 안의 경험을 따르라"는 명확한 지시가 있는지 확인합니다. AI가 자동으로 학습 내용을 추가하지 않으면 prompt에 "After each story, append learnings to progress.txt"를 추가합니다.

함정 4: 의존 관계 순서 오류

증상: 특정 story가 의존하는 코드가 아직 존재하지 않아 구현이 실패합니다.

해결: dependsOn 필드를 올바르게 설정하여 인프라 story가 먼저 오도록 합니다.

자주 묻는 질문

Q: 실행 중에 prd.json을 수동으로 수정하여 개입할 수 있습니까?

가능합니다. Ralph는 매 반복 시작 시 prd.json을 다시 읽습니다. 반복 사이에 story 설명을 수정하거나, 새로운 story를 추가하거나, 특정 story를 수동으로 passes: true로 표시(건너뛰기)할 수 있습니다.

Q: Ralph가 하나의 story에서 반복적으로 실패하면 어떻게 해야 합니까?

1. progress.txt에서 실패 원인을 확인합니다
2. notes에 추가 컨텍스트를 보충합니다
3. story를 분할합니다 (단위가 너무 클 수 있음)
4. 차단 문제를 수동으로 수정한 후 다시 실행합니다

Q: Ralph 실행 중에 다른 일을 해도 괜찮습니까?

괜찮습니다. Ralph는 "Human on the Loop"으로 설계되었습니다 — 계속 지켜볼 필요가 없습니다. AFK 모드에서 퇴근 전에 시작하고 다음 날 결과를 확인하면 됩니다. 실행 중에는 Ralph가 작업 중인 파일을 수정하지 않도록 주의하십시오.

Q: 비용은 어떻게 관리합니까?

세 가지 방법이 있습니다: 합리적인 max_iterations 설정, 적절한 story 단위 유지(불필요한 반복 감소), 그리고 먼저 소규모로 시험 실행하여 프로세스가 올바른지 확인하는 것입니다. 일반적으로 1020개의 story가 있는 프로젝트는 $50100의 API 비용 범위에 해당합니다.

요약

Ralph의 사용 흐름은 다섯 단계로 요약할 수 있습니다:

설치 → PRD 작성 → 품질 게이트 구성 → 루프 실행 → 성과 확인

핵심 사고방식은 항상 변하지 않습니다: 파일을 진실의 원천으로 삼고, 매번 반복을 완전히 새로운 시작으로 만들고, 품질 게이트가 대신 검증하도록 합니다.

이제 여러분의 프로젝트로 돌아가 prd.json을 준비하고, ./scripts/ralph/ralph.sh --tool claude를 실행한 다음, 커피 한 잔 마시러 가십시오.

추가 읽을거리

• 《Ralph Wiggum 심층 분석》 — Ralph의 핵심 원리 복습
• 《frankbria/ralph-claude-code 실전 가이드》 — 엔지니어링화된 Ralph 구현: 모니터링, 서킷 브레이커 및 안전 메커니즘
• 《GSD 심층 분석》 — Ralph 위에 구축된 완전한 컨텍스트 엔지니어링 시스템
• 《Claude Skills란 무엇인가》 — Ralph의 PRD skill은 하나의 Claude Skill입니다
• 《Speckit 실전 가이드》 — 또 다른 구조화된 AI 프로그래밍 워크플로