Ralph 사용 가이드

프로젝트 구조

ralph-test/
├── CLAUDE.md                  # Claude가 자동으로 읽는 프로젝트 설명서
├── PROJECT_STRUCTURE.md       # 구조 설명 문서
├── RALPH_GUIDE.md             # 이 파일 — Ralph 사용 가이드
├── .gitignore
│
├── .claude/
│   └── settings.json          # Claude 권한 + Stop Hook 설정
│
├── .ralph/
│   ├── fix_plan.md            # Ralph 할 일 목록
│   └── PROMPT.md              # Ralph 지시문
│
├── scripts/
│   ├── ralph-loop.sh          # Ralph 실행 스크립트
│   └── ralph-stop-hook.sh     # 완료 조건 검증 Hook
│
├── django-api/
│   ├── .venv/                 # Python 가상환경
│   └── requirements.txt       # Python 패키지 목록
│
└── node-api/
    ├── node_modules/          # Node 패키지
    ├── package.json
    └── eslint.config.js

---

Ralph를 쓰기 위해 필요한 것

1. CLAUDE.md

"이 프로젝트가 뭔지" Claude에게 알려주는 파일.
Claude는 세션 시작 시 이 파일을 자동으로 읽고 프로젝트 컨텍스트를 파악한다.

2. .ralph/fix_plan.md

"뭘 만들어야 하는지" 할 일 목록. Ralph가 이 파일을 보고 순서대로 구현한다.

## P1: 긴급 (반드시 완료)
- [ ] 미완료 항목  ← Claude가 구현
- [x] 완료 항목   ← 구현 + 테스트 통과 후 Claude가 직접 체크

## P2: 중요
- [ ] ...

## P3: 개선
- [ ] ...

3. .ralph/PROMPT.md

"어떻게 일해야 하는지" Claude에게 주는 지시문.
역할, 작업 순서, 완료 조건, 절대 금지 사항을 정의한다.

4. .claude/settings.json

Claude가 실행할 수 있는 명령어(allow)와 없는 명령어(deny), 그리고 Stop Hook 연결을 정의한다.

{
  "permissions": {
    "allow": ["pytest 실행", "git commit", ...],
    "deny": ["rm -rf", "git push force", ...]
  },
  "hooks": {
    "Stop": [{ "command": "bash scripts/ralph-stop-hook.sh" }]
  }
}

5. scripts/ralph-stop-hook.sh

Claude가 멈추려 할 때마다 자동 실행되는 검증 스크립트.
모든 조건을 통과해야만 Claude가 종료할 수 있다.

미완료 항목 있음?     → block (계속 작업하라)
Django 테스트 실패?  → block (고쳐라)
Django 린트 에러?    → block (고쳐라)
Node 테스트 실패?    → block (고쳐라)
Node 린트 에러?      → block (고쳐라)
전부 통과?           → allow  (종료 허용)
max-iterations 초과? → allow  (강제 종료)

6. 환경 세팅

Claude가 실제로 테스트/린트를 실행할 수 있는 환경.

환경	설정	도구
Django	.venv/ 가상환경	pytest, ruff
Node.js	node_modules/	jest, eslint

---

Ralph 실행 방법

# 기본 실행 (최대 30회)
bash scripts/ralph-loop.sh

# 반복 횟수 지정
bash scripts/ralph-loop.sh --max-iterations 10

# 오버나이트 (백그라운드)
nohup bash scripts/ralph-loop.sh --max-iterations 50 > logs/ralph-session.log 2>&1 &

---

전체 실행 흐름

사람이 fix_plan.md 작성
        ↓
bash scripts/ralph-loop.sh 실행
        ↓
새 브랜치 생성 (ralph/run-YYYYMMDD-HHMM)
        ↓
PROMPT.md → Claude에게 전달
        ↓
┌─── Claude 루프 시작 ──────────────────────┐
│  fix_plan.md 읽기 → 미완료 항목 선택       │
│  테스트 먼저 작성 (TDD — Red)              │
│  구현 (Green)                             │
│  테스트 + 린트 실행                        │
│  통과 → fix_plan.md [x] 표시 + git commit │
│  완료 시도                                 │
│         ↓                                 │
│  ralph-stop-hook.sh 실행                  │
│  ├─ 미통과 → block → 루프 계속 ───────────┘
│  └─ 통과   → allow → 종료
└───────────────────────────────────────────

---

max-iterations란?

Ralph가 최대 몇 번 반복할지 제한하는 숫자.
Claude가 작업 완료를 시도할 때마다 1회로 카운트된다.

상황	추천 값
처음 테스트, 빠르게 확인	5~10
기능 몇 개 구현	20~30
오버나이트 풀 개발	50

---

결과 확인 방법

# 어디까지 커밋됐는지
git log --oneline

# 항목별 완료 상태 확인
cat .ralph/fix_plan.md

# [x] 완료
# [!] 3회 연속 실패로 건너뜀 → 사람이 직접 확인 필요
# [ ] 미완료 → fix_plan.md 그대로 두고 다시 Ralph 실행