openclaw / ralph-loop

Skill Content

---
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태스크 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: 플래닝**
```markdown
# 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](references/workflow.md) 참조.