frankbria/ralph-claude-code

해결하는 문제

Ralph는 단일 Claude Code 호출을 완전한 무인 개발 주기로 전환하는 문제를 해결합니다. 수동으로 Claude를 반복적으로 프롬프트하는 대신 Ralph는 프로젝트 지침을 읽고, 코드 변경을 실행하고, 진행 상황을 추적하고, 프로젝트가 진정으로 완료될 때까지 반복하는 루프에서 Claude Code를 실행합니다. 또한 종료 신호를 잘못 읽어 영원히 실행되거나 시간당 또는 5시간 API 한도를 소진하는 것과 같은 루프의 두 가지 일반적인 실패 모드를 방지합니다.

작동 방식

Ralph는 주기를 실행합니다: .ralph/PROMPT.md에서 프로젝트 지침을 로드하고, 현재 컨텍스트로 Claude Code를 실행한 다음 작업 목록과 로그를 업데이트합니다. 완료는 이중 조건 게이트를 사용하여 확인합니다: 완료 표시기의 휴리스틱 수(자연어 패턴에서 최소 2개)와 Claude 출력의 명시적 EXIT_SIGNAL: true가 모두 있어야 합니다. 둘 중 하나가 없으면 루프가 계속됩니다. Ralph는 또한 연속된 완료 신호 후 강제 종료하는 회로 차단기, 시간당 상한(기본 100회 호출)의 속도 제한, 3계층 감지 기능이 있는 5시간 API 한도 감지기, 컨텍스트 보존을 위한 --resume을 사용한 세션 관리를 사용합니다. --live로 실시간 출력을 스트리밍하고, Docker 또는 E2B 샌드박스에서 실행하며, git 상태를 자동 백업할 수 있습니다.

대상 사용자

Ralph는 Claude Code를 사용하고 더 길고 다단계 코딩 작업을 자율 에이전트 루프에 위임하려는 개발자를 위한 것입니다. 제품 요구 사항 문서(PRD)나 GitHub 이슈를 최소한의 수동 프롬프트로 작동하는 코드베이스로 전환하는 데 특히 유용합니다. 또한 잘 정의된 작업 목록에서 무인 진행이 필요한 팀에도 적합합니다.

주요 기능

• 이중 조건 종료 감지(완료 표시기 + 명시적 EXIT_SIGNAL)로 조기 종료 또는 무한 루프 방지.
• 시간별 재설정 속도 제한과 회로 차단기로 API 과다 사용 및 폭주 루프 방지.
• --resume을 사용한 세션 연속성(세션 하이재킹 없음) 및 구성 가능한 세션 만료(기본 24시간).
• 타임아웃 가드, JSON 파싱, 텍스트 폴백을 포함한 5시간 API 한도의 3계층 감지.
• 프로젝트 유형을 자동 감지하고 beads, GitHub Issues 또는 PRD에서 작업을 가져오는 대화형 ralph-enable 마법사.
• ralph-import는 markdown, 텍스트, JSON, DOCX 및 PDF 요구 사항 문서를 구조화된 Ralph 프로젝트로 변환합니다.
• 리소스 제한 및 비용 추적이 포함된 Docker 및 E2B 클라우드 샌드박스 실행.
• 선택적 실시간 스트리밍, 데스크톱 알림, 드라이런 모드 및 롤백이 가능한 자동 git 백업 브랜치.