| name | ralph-loop |
| description | AI 자율 구현 방법론. 구현/개발/코딩 요청 시 자동 적용. 메인은 마더 서브에이전트를 spawn하고, 마더가 워커들을 관리. specs/ → IMPLEMENTATION_PLAN.md → 1태스크씩 구현 → 2단계 리뷰 → 테스트 → 반복. |
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사이클 — 작게 쪼개서 스마트존 유지
- 3-tier 에이전트 구조 — 메인 → 마더 → 워커
- 파일이 메모리 — 상태는 디스크에 기록
- 백프레셔 — 테스트/린트로 품질 게이트
- 🆕 검증 우선 (Evidence Before Claims) — "완료"는 증거와 함께만
- 🆕 3회 룰 — 같은 문제 3번 실패 → 아키텍처 재검토 (더 이상 패치 금지)
- 🆕 YAGNI 강제 — 스펙에 없으면 구현 금지. "있으면 좋겠다" = 구현 안 함
에이전트 구조
┌─────────────────────────────────────────────┐
│ 메인 에이전트 (Main) │
│ • 사용자와 대화 │
│ • Ralph Loop 마더 spawn │
│ • 전체 조율 및 의사결정 │
└──────────────────┬──────────────────────────┘
│ spawn (label: ralph-mother)
▼
┌─────────────────────────────────────────────┐
│ 마더 에이전트 (Mother) │
│ • specs/ 폴더 생성 및 관리 │
│ • IMPLEMENTATION_PLAN.md 생성/업데이트 │
│ • 워커 서브에이전트 spawn │
│ • 🆕 2단계 리뷰 수행 (스펙 준수 → 품질) │
│ • 진행 상황 메인에게 보고 │
└──────────────────┬──────────────────────────┘
│ spawn (label: ralph-worker-N)
▼
┌─────────────────────────────────────────────┐
│ 워커 에이전트 (Worker) │
│ • 단일 태스크 구현 │
│ • 🆕 자체 검증 실행 (테스트/curl/브라우저) │
│ • 🆕 검증 증거 포함하여 보고 │
│ • 결과 마더에게 보고 │
└─────────────────────────────────────────────┘
워크플로우
메인 에이전트 역할
사용자가 구현/개발 요청 시:
- 요구사항 파악 및 명확화
- Ralph Loop 마더 서브에이전트 spawn
- 마더 보고 수신 및 사용자에게 진행 상황 전달
- 필요시 의사결정 및 방향 조정
마더 에이전트 역할
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. 다음 태스크로 반복 또는 완료 보고
워커 에이전트 역할
마더로부터 할당받은 단일 태스크:
- specs 및 관련 코드 분석
- 구현
- 🆕 검증 실행 및 증거 수집:
- 테스트가 있으면 → 실행하고 출력 캡처
- 웹 앱이면 → curl/브라우저로 실제 확인
- CLI면 → 실행하고 결과 캡처
- 결과를 마더에게 보고 (성공/실패 + 증거)
🆕 체계적 디버깅 프로토콜
버그/에러/예상치 못한 동작 발생 시:
Phase 1: 근본 원인 조사 (수정 시도 전 필수)
- 에러 메시지 완전히 읽기 (스택 트레이스 포함)
- 재현 가능성 확인
- 최근 변경사항 확인 (git diff)
- 데이터 흐름 추적
Phase 2: 가설 수립 및 최소 테스트
- 단일 가설: "X가 근본 원인이다, 왜냐하면 Y"
- 최소한의 변경으로 가설 검증
- 한 번에 하나씩만 변경
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 참조.
