kjaylee/ralph-loop

Ralph Loop v2

Geoffrey Huntley의 AI 자율 개발 방법론 + Superpowers 비판적 흡수.

흡수한 것 (Superpowers에서)

• ✅ 2단계 리뷰: 스펙 준수 → 코드 품질 (기존: 리뷰 없이 마더가 직접 확인)
• ✅ 검증 우선: "완료" 선언 전 반드시 테스트 실행 증거 확인 (기존: 워커 자체 보고 신뢰)
• ✅ 체계적 디버깅: 3회 실패 시 아키텍처 재검토 (기존: 무한 재시도)
• ✅ YAGNI 강제: 스펙에 없으면 구현 금지 (기존: 암묵적)
• ✅ Red Flags 목록: 안티패턴 명시화

흡수하지 않은 것 (비판)

• ❌ 엄격한 TDD 강제: HTML5 게임/단일파일 도구에 과도. 우리 주 생산물은 단일 HTML 게임/도구 — TDD가 오히려 속도 저하. 복잡 프로젝트(Rust/Godot)에만 선택 적용.
• ❌ Git Worktrees: OpenClaw 환경에서 불필요. 서브에이전트가 이미 컨텍스트 격리.
• ❌ Code Review 서브에이전트 별도 spawn: 비용 과다. 마더가 직접 2단계 리뷰 수행.
• ❌ Brainstorming 200-300단어 청크: 우리는 Master 지시 → 즉시 실행. 소크라테스식 질문 불필요.
• ❌ Claude Code 플러그인 의존성: OpenClaw 네이티브로 작동.

핵심 원칙

1. 1태스크 1사이클 — 작게 쪼개서 스마트존 유지
2. 3-tier 에이전트 구조 — 메인 → 마더 → 워커
3. 파일이 메모리 — 상태는 디스크에 기록
4. 백프레셔 — 테스트/린트로 품질 게이트
5. 🆕 검증 우선 (Evidence Before Claims) — "완료"는 증거와 함께만
6. 🆕 3회 룰 — 같은 문제 3번 실패 → 아키텍처 재검토 (더 이상 패치 금지)
7. 🆕 YAGNI 강제 — 스펙에 없으면 구현 금지. "있으면 좋겠다" = 구현 안 함

에이전트 구조

┌─────────────────────────────────────────────┐
│  메인 에이전트 (Main)                        │
│  • 사용자와 대화                             │
│  • Ralph Loop 마더 spawn                    │
│  • 전체 조율 및 의사결정                      │
└──────────────────┬──────────────────────────┘
                   │ spawn (label: ralph-mother)
                   ▼
┌─────────────────────────────────────────────┐
│  마더 에이전트 (Mother)                      │
│  • specs/ 폴더 생성 및 관리                   │
│  • IMPLEMENTATION_PLAN.md 생성/업데이트       │
│  • 워커 서브에이전트 spawn                    │
│  • 🆕 2단계 리뷰 수행 (스펙 준수 → 품질)      │
│  • 진행 상황 메인에게 보고                    │
└──────────────────┬──────────────────────────┘
                   │ spawn (label: ralph-worker-N)
                   ▼
┌─────────────────────────────────────────────┐
│  워커 에이전트 (Worker)                      │
│  • 단일 태스크 구현                          │
│  • 🆕 자체 검증 실행 (테스트/curl/브라우저)    │
│  • 🆕 검증 증거 포함하여 보고                  │
│  • 결과 마더에게 보고                        │
└─────────────────────────────────────────────┘

워크플로우

메인 에이전트 역할

사용자가 구현/개발 요청 시:

1. 요구사항 파악 및 명확화
2. Ralph Loop 마더 서브에이전트 spawn
3. 마더 보고 수신 및 사용자에게 진행 상황 전달
4. 필요시 의사결정 및 방향 조정

마더 에이전트 역할

spawn 시 전달받은 요구사항으로:

Phase 1: 요구사항 정의

specs/
├── feature-a.md
├── feature-b.md
└── ...

• 각 기능별 스펙 문서 작성
• 1 topic = 1 file (and 없이 한 문장으로 설명 가능해야 함)

Phase 2: 플래닝

# IMPLEMENTATION_PLAN.md
## TODO
- [ ] 태스크 1 (예상 2-5분)
- [ ] 태스크 2 (예상 2-5분)
## DONE
- [x] 완료된 태스크 ✅ 스펙준수 ✅ 품질

• specs vs 현재 코드 gap 분석
• 우선순위 정렬된 태스크 리스트
• 🆕 태스크 크기: 2-5분 단위. 더 크면 분할.

Phase 3: 빌딩 (반복)

1. IMPLEMENTATION_PLAN.md 읽기
2. 가장 중요한 태스크 선택
3. 워커 서브에이전트 spawn (해당 태스크 + 관련 스펙 전문 전달)
4. 워커 완료 보고 수신
5. 🆕 2단계 리뷰:
   a) 스펙 준수 검증 — 워커 결과물 vs 스펙 비교
      - 누락된 요구사항 있나?
      - 스펙에 없는 것을 추가했나? (YAGNI 위반)
   b) 품질 검증 — 코드 품질, 에러 핸들링, 엣지 케이스
6. 🆕 검증 증거 확인 — "테스트 통과" 주장에 실제 출력이 있나?
7. 리뷰 통과 → 플랜 업데이트 + 커밋
   리뷰 실패 → 워커에게 수정 지시 (같은 서브에이전트)
8. 다음 태스크로 반복 또는 완료 보고

워커 에이전트 역할

마더로부터 할당받은 단일 태스크:

1. specs 및 관련 코드 분석
2. 구현
3. 🆕 검증 실행 및 증거 수집:
   • 테스트가 있으면 → 실행하고 출력 캡처
   • 웹 앱이면 → curl/브라우저로 실제 확인
   • CLI면 → 실행하고 결과 캡처
4. 결과를 마더에게 보고 (성공/실패 + 증거)

🆕 체계적 디버깅 프로토콜

버그/에러/예상치 못한 동작 발생 시:

Phase 1: 근본 원인 조사 (수정 시도 전 필수)

1. 에러 메시지 완전히 읽기 (스택 트레이스 포함)
2. 재현 가능성 확인
3. 최근 변경사항 확인 (git diff)
4. 데이터 흐름 추적

Phase 2: 가설 수립 및 최소 테스트

1. 단일 가설: "X가 근본 원인이다, 왜냐하면 Y"
2. 최소한의 변경으로 가설 검증
3. 한 번에 하나씩만 변경

Phase 3: 3회 룰

• 같은 문제에 수정 3회 실패 → 즉시 중단
• 아키텍처/설계 문제일 가능성 높음
• 마더에게 보고 → 마더가 Master에게 에스컬레이션
• 절대 4번째 패치 시도 금지

🆕 Red Flags (안티패턴 — 즉시 중단)

| 🚫 Red Flag | ✅ 올바른 행동 | |-------------|---------------| | "아마 될 거야" | 검증 실행 후 결과로 판단 | | "이것만 고치면 됨" (3번째) | 아키텍처 재검토 | | 테스트 없이 "완료" 선언 | 검증 증거 첨부 | | 스펙에 없는 기능 추가 | YAGNI — 스펙만 구현 | | 여러 수정을 한번에 | 한 번에 하나씩 | | 워커 보고만 신뢰 | 증거 직접 확인 | | "나중에 테스트" | 지금 검증 또는 미완료 처리 |

프로젝트 규모별 적용

| 규모 | TDD | 2단계 리뷰 | 3-tier 구조 | |------|-----|-----------|------------| | 단일 HTML 게임/도구 | ❌ 불필요 | ✅ 마더가 빠르게 | ⚠️ 마더만 (워커 생략 가능) | | 멀티파일 프로젝트 | ⚠️ 핵심 로직만 | ✅ 필수 | ✅ 필수 | | Rust/WASM/Godot | ✅ 필수 | ✅ 필수 | ✅ 필수 |

서브에이전트 spawn 예시

메인 → 마더:

label: ralph-mother
task: "[요구사항 요약] 구현. specs/ 작성 → IMPLEMENTATION_PLAN.md → 워커로 구현 → 2단계 리뷰 → 완료 시 보고"

마더 → 워커:

label: ralph-worker-1
task: "태스크: [구체적 태스크]. 스펙: [전문 텍스트]. 구현 후 검증 실행, 증거 포함 결과 보고."

컨텍스트 관리

• 메인: 최소 컨텍스트 유지 (사용자 대화에 집중)
• 마더: 전체 플랜과 진행 상황만 트래킹
• 워커: 단일 태스크에만 집중 (40-60% 스마트존)
• 🆕 워커에게 스펙 전문 전달 — 파일 읽기 오버헤드 제거 (Superpowers 패턴)

상세 가이드

복잡한 프로젝트는 references/workflow.md 참조.