GitHub - snarktank/ralph: Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete.

Ralph는 PRD(Product Requirements Document)에 명시된 모든 항목이 완료될 때까지 반복적으로 실행되는 자율 AI Agent loop입니다. 각 반복은 깨끗한 context를 가진 새로운 Amp instance를 생성합니다. 반복 간의 memory는 Git history, progress.txt 파일, 그리고 prd.json 파일을 통해 유지됩니다. 이 시스템은 Geoffrey Huntley의 Ralph 패턴을 기반으로 합니다.

핵심 방법론 (Core Methodology)

Ralph의 작업 흐름은 다음과 같은 단계로 구성됩니다:

1. PRD 생성 (PRD Generation):

prd skill을 사용하여 상세한 요구사항 문서를 생성합니다. 이 문서는 tasks/prd-[feature-name].md 형식으로 저장됩니다. 이 단계에서 사용자는 feature에 대한 설명을 제공하고, skill은 clarifying questions에 답변함으로써 문서를 구체화합니다.

1. PRD를 Ralph 형식으로 변환 (PRD Conversion to Ralph Format):

생성된 Markdown 형식의 PRD를 ralph skill을 사용하여 JSON 형식인 prd.json으로 변환합니다. prd.json은 자율적인 실행을 위해 사용자 story들을 구조화합니다. 각 story는 id, title, description, acceptanceCriteria, priority, passes 등의 속성을 가집니다.

1. Ralph 실행 (Execution of Ralph):

./scripts/ralph/ralph.sh [max_iterations] 명령어를 통해 Ralph loop를 시작합니다. max_iterations는 기본값이 10입니다. Ralph의 각 iteration은 다음의 정교한 단계를 따릅니다.

• Feature Branch 생성 (Feature Branch Creation): prd.json에 정의된 branchName을 기반으로 새로운 feature branch를 생성합니다. 이는 각 작업의 격리성과 버전 관리를 보장합니다.
• Story 선택 (Story Selection): prd.json 내의 사용자 story들 중에서 passes: false로 설정되어 있고 가장 높은 priority를 가진 story를 선택합니다. 이는 시스템이 미완료된 작업 중 가장 중요한 것부터 처리하도록 합니다.
• Story 구현 (Story Implementation): 선택된 단일 story를 Amp instance가 구현합니다. 여기서 Amp는 prompt.md 파일에 정의된 지침을 따르며, 이는 프로젝트 특정의 품질 검사 명령, 코드베이스 규칙, 일반적인 문제점 등을 포함하여 맞춤 설정될 수 있습니다.
• 품질 검사 (Quality Checks): 구현 후, typecheck 및 테스트와 같은 품질 검사를 실행합니다. 이 단계는 코드의 정확성과 기능을 검증하는 데 필수적입니다.
• Commit 및 상태 업데이트 (Commit and Status Update): 품질 검사를 통과하면, 변경 사항을 Git에 commit하고, 해당 story의 passes 상태를 prd.json에서 true로 업데이트합니다.
• 학습 내용 기록 (Recording Learnings): 현재 iteration에서 얻은 학습 내용이나 발견된 패턴, 주의사항 등을 progress.txt 파일에 추가합니다. 이 파일은 다음 iteration을 위한 memory 역할을 하며, AGENTS.md 파일에 자동적으로 반영되어 향후 개발에 도움이 됩니다.
• 반복 종료 조건 (Loop Termination Condition): 모든 story가 passes: true 상태가 되거나, max_iterations에 도달하면 loop는 종료됩니다. 모든 story가 완료되면, Ralph는 $<promise>COMPLETE</promise>$ 메시지를 출력합니다.

핵심 개념 (Critical Concepts)

• Iteration = Fresh Context: 각 iteration마다 새로운 Amp instance가 생성되어 깨끗한 context에서 작업합니다. 이는 이전 iteration의 오류나 잔여물로부터 독립적인 실행 환경을 보장합니다. Memory는 Git history, progress.txt, prd.json을 통해서만 유지됩니다.
• 작은 Task (Small Tasks): 각 PRD 항목은 단일 context window 내에서 완료될 수 있을 만큼 충분히 작아야 합니다. 이는 LLM이 context 부족으로 인해 불완전하거나 품질이 낮은 코드를 생성하는 것을 방지합니다.
• AGENTS.md 업데이트 (AGENTS.md Updates): 각 iteration 후, Ralph는 학습 내용을 관련 AGENTS.md 파일에 업데이트합니다. Amp는 이 파일을 자동으로 읽어 다음 iteration에 유용한 정보로 활용하며, 인간 개발자에게도 코드베이스의 패턴, 문제점, 규칙 등을 전달합니다.
• Feedback Loops: Ralph의 효과적인 작동을 위해 강력한 feedback loop가 필수적입니다. Typecheck, 테스트, CI(Continuous Integration) 시스템은 반드시 green 상태를 유지하여 코드의 품질을 지속적으로 검증해야 합니다. UI 관련 story의 경우, dev-browser skill을 사용하여 브라우저에서 실제 변경 사항을 확인할 수 있도록 합니다.
• Amp Auto-Handoff: amp.experimental.autoHandoff 설정을 통해 context가 가득 찼을 때 자동 handoff를 가능하게 하여, 단일 context window를 초과하는 큰 story도 처리할 수 있도록 합니다.

파일 구성 (File Structure)

• ralph.sh: Amp instance를 실행하는 bash loop 스크립트.
• prompt.md: 각 Amp instance에 주어지는 지침 파일.
• prd.json: 사용자 story와 passes 상태를 포함하는 task 목록.
• progress.txt: Append-only 방식으로 학습 내용을 기록하는 파일.
• skills/prd/: PRD 생성 기능을 담당하는 skill.
• skills/ralph/: PRD를 JSON으로 변환하는 skill.