frankbria/ralph-claude-code 실전 가이드

서론

이전 글에서는 Ralph의 방법론을 소개했고, snarktank/ralph에서는 극도로 간결한 외부 루프 구현을 살펴보았습니다. 이제 또 다른 방향을 살펴보겠습니다: frankbria/ralph-claude-code.

snarktank/ralph의 철학이 "최소한의 코드로 최대한의 일을 하는 것"이라면, frankbria의 철학은 "모든 것을 엔지니어링하는 것"입니다 — 대화형 설정 마법사, 실시간 모니터링 대시보드, Circuit Breaker, 속도 제한, 세션 만료 관리. 간결함을 추구하지 않고 제어 가능성을 추구합니다.

두 구현 사이에 우열은 없으며, 서로 다른 사용 시나리오에 적합합니다. 이 글에서는 frankbria의 전체 도구 체인을 안내합니다.

설치 및 설정

전역 설치

# 리포지토리 클론
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code

# 전역 설치
./install.sh

설치가 완료되면 다음과 같은 전역 명령어를 사용할 수 있습니다:

프로젝트 초기화

기존 프로젝트에는 대화형 마법사를 사용합니다:

cd your-project
ralph-enable

마법사가 프로젝트 유형(Node.js, Python, Go 등)과 프레임워크(Next.js, FastAPI 등)를 자동으로 감지한 후 해당하는 설정 파일을 생성합니다.

완전히 새로운 프로젝트의 경우:

ralph-setup my-new-project

이 명령어는 프로젝트 디렉토리를 생성하고, Git을 초기화하며, .ralph/ 설정 디렉토리를 생성합니다.

기존 요구사항 가져오기

이미 PRD 문서나 요구사항 명세서가 있는 경우:

ralph-import path/to/your-prd.md

Ralph이 문서를 파싱하여 작업 목록을 추출하고 구조화된 fix_plan.md를 생성합니다.

.ralph/ 디렉토리 구조

frankbria의 메모리와 설정은 .ralph/ 디렉토리에 집중되어 있습니다:

.ralph/
├── PROMPT.md          # 프로젝트 목표와 컨텍스트
├── fix_plan.md        # 작업 목록 (prd.json과 유사한 역할)
├── AGENT.md           # 빌드/테스트 명령어 (자동 관리)
├── specs/             # 상세 요구사항 문서
│   ├── feature-a.md
│   └── feature-b.md
└── sessions/          # 세션 지속성 데이터
    ├── current.json
    └── history/

snarktank/ralph과의 비교:

AGENT.md는 자동으로 관리됩니다 — Ralph이 실행 과정에서 발견한 프로젝트 규칙에 따라 이 파일을 자동으로 업데이트하며, snarktank/ralph의 progress.txt와 유사하지만 더 구조화되어 있습니다.

핵심 명령어

기본 실행

# Ralph 루프 시작
ralph

# 실시간 모니터링 포함
ralph --monitor

# tmux에서 시작 (장시간 실행 시 권장)
ralph --live

모니터링 대시보드

# 독립적으로 모니터링 시작
ralph-monitor

ralph-monitor는 tmux 대시보드를 열어 다음을 실시간으로 표시합니다:

• 현재 실행 중인 작업
• 완료/미완료 작업 수
• API 호출 횟수 및 비용 추정
• Circuit Breaker 상태
• 최근 오류 로그

주요 파라미터

# API 호출 50회 제한, 2시간 타임아웃
ralph --calls 50 --timeout 120

# 마지막 중단 지점부터 계속
ralph --resume

안전 메커니즘

frankbria의 가장 큰 차별화 특성은 다계층 안전 메커니즘입니다.

Circuit Breaker

Circuit Breaker는 "진행 없음"을 감지하면 자동으로 루프를 중단하여 무의미한 API 소모를 방지합니다:

연속 진행 없음 감지: 연속 N번의 반복에서 새로운 작업이 완료되지 않으면 Circuit Breaker가 작동합니다.

동일 오류 감지: 동일한 오류 메시지가 연속으로 발생하면 AI가 무한 루프에 빠진 것이므로 Circuit Breaker가 작동합니다.

속도 제한

기본적으로 100 calls/hour로 제한하여 예상치 못한 API 요금 폭증을 방지합니다. 파라미터를 통해 조정할 수 있습니다:

ralph --calls 200  # 200 calls로 상향

5시간 API 한도 3단계 감지

Anthropic API에는 5시간 슬라이딩 윈도우 사용 한도가 있습니다. frankbria에는 3단계 감지가 내장되어 있습니다:

1. 사전 감지: 각 API 호출 전에 잔여 한도를 추정합니다
2. 응답 감지: API 응답의 rate limit headers를 파싱합니다
3. 후퇴 전략: 한도에 가까워지면 자동으로 호출 빈도를 낮춥니다

세션 만료 관리

기본 세션 유효 기간은 24시간입니다. 초과 시 세션 데이터를 자동으로 정리하여 만료된 컨텍스트가 후속 실행에 영향을 미치는 것을 방지합니다.

지능형 종료 감지

frankbria는 단순히 모든 작업이 완료된 후 종료하지 않습니다. 이중 조건 종료 게이트를 사용합니다:

종료 조건 = completion_indicators >= 2 AND EXIT_SIGNAL: true

completion_indicators는 AI 출력에서 감지된 완료 신호 수이며, 다음을 포함합니다:

• "모든 작업이 완료되었습니다"
• "더 이상 할 일이 없습니다"
• 테스트 전부 통과
• fix_plan.md의 모든 항목이 done으로 표시됨

EXIT_SIGNAL은 AI가 출력에서 명시적으로 선언한 종료 의도입니다.

왜 두 가지 조건이 필요할까요? 조기 종료를 방지하기 위해서입니다. 단일 신호는 오판일 수 있습니다 — 예를 들어 AI가 "작업 완료"라고 말했지만 실제로는 현재 story만 완료한 경우입니다. 이중 조건을 통해 여러 독립적인 신호가 모두 완료를 확인한 경우에만 실제로 종료합니다.

snarktank/ralph과의 비교

핵심 차이: 엔지니어링 수준

둘 다 외부 bash 루프가 새로운 Claude 프로세스를 시작합니다. 핵심 차이는 세션 관리 방식에 있지 않으며(frankbria는 --no-continue로 새 세션 모드로 전환 가능), 엔지니어링 수준에 있습니다:

• snarktank: 극도로 간결한 스크립트, 수백 줄의 bash, 루프 자체에 집중
• frankbria: 완전한 엔지니어링 도구 체인 — 모니터링 대시보드, Circuit Breaker, 속도 제한, 세션 만료 관리

frankbria는 기본적으로 --continue 세션 재사용을 활성화하며, 짧은 작업에 적합합니다. 긴 작업의 경우 --no-continue로 전환하여 새 세션 모드를 사용하면 snarktank와 동일한 Context Rot 방지 효과를 얻을 수 있으며, 동시에 frankbria의 엔지니어링 장점도 유지할 수 있습니다.

세션 재사용 비활성화 방법

frankbria는 --continue를 비활성화하는 세 가지 방법을 제공합니다:

# 방법 1: 명령줄 파라미터
ralph --no-continue

# 방법 2: 환경 변수
export CLAUDE_USE_CONTINUE=false

# 방법 3: .ralphrc 설정
SESSION_CONTINUITY=false

비활성화하면 frankbria의 동작은 snarktank와 동일해지지만(매번 새 세션), 모든 엔지니어링 도구(모니터링, Circuit Breaker, 속도 제한 등)는 유지됩니다.

Context Rot의 현실적 트레이드오프

세션 재사용 방식의 선택은 본질적으로 Context Rot와 시작 오버헤드 사이의 트레이드오프입니다:

짧은 작업 (< 50k tokens): 세션 재사용이 더 유리합니다. 컨텍스트가 아직 열화되지 않았고, 처음 몇 번의 반복에서 쌓인 기억을 이후에 활용할 수 있습니다. 매번 새 세션을 생성하는 시작 오버헤드가 오히려 낭비입니다.

긴 작업 (100k+ tokens): 새 세션이 더 안정적입니다. 100k tokens를 초과하면 Context Rot가 눈에 띄게 악화되어, 축적된 컨텍스트가 자산에서 부채로 변합니다. 새 세션은 시작 오버헤드가 있지만, 매번 최적의 상태를 유지합니다.

실전 권장 사항:

frankbria 사용자는 작업 규모에 따라 유연하게 선택할 수 있습니다: 짧은 작업에는 기본 --continue 모드를, 긴 작업에는 --no-continue 모드로 전환합니다. snarktank와 비교하여, frankbria의 장점은 어떤 모드에서든 완전한 엔지니어링 도구 체인을 유지한다는 것입니다.

요약

frankbria/ralph-claude-code는 Ralph 방법론의 엔지니어링된 구현 방향을 대표합니다. snarktank의 간결함을 일부 희생하는 대신, 더 완벽한 모니터링, 안전 및 설정 기능을 제공합니다.

어떤 구현을 선택할지는 구체적인 요구사항에 따라 달라집니다 — "더 올바른" 답은 없고, "더 적합한" 선택만 있을 뿐입니다.

추가 읽을거리:

• Ralph Wiggum 심층 분석 — 핵심 원리와 방법론
• snarktank/ralph 실전 가이드 — 극도로 간결한 외부 루프 구현
• GSD 심층 분석 — Ralph을 기반으로 구축한 완전한 컨텍스트 엔지니어링 시스템
• Claude 시스템 아키텍처 전체 분석 — Hooks, Subagent 등 구성 요소의 전체 아키텍처 이해