ralph-story-executor

name

ralph-story-executor

description

prd.json에 적힌 사용자 스토리를 한 번에 딱 하나씩, "매번 새 컨텍스트(fresh-context)"로 골라 구현하고 → test·lint·build 백프레셔(backpressure) 검사를 돌리고 → 커밋하고 → progress.md에 배운 점을 기록한 뒤 다음 스토리로 넘어가는 자동화 루프입니다. 모든 스토리가 passes: true가 될 때까지 반복합니다. 사용자가 "랠프 루프 돌려줘", "prd.json 스토리 하나씩 다 구현해줘", "백로그 스토리 자동으로 끝까지 처리해줘", ".ralph 스토리 실행", "Ralph Story Executor", "run the ralph loop", "implement the prd stories one by one", "execute the backlog until every story passes"처럼 .ralph/ 스캐폴딩에 쌓인 스토리를 무인으로 하나씩 완주시키고 싶을 때 사용하세요. (구분: 체크리스트형 spec.md 요구사항을 하나씩 구현하는 건 looping:spec-first-ship, 실패가 같은 식으로 두 번 반복되면 .ralph/guardrails.md에 사인을 남기는 건 looping:guardrails-learning-loop, 테스트부터 쓰는 TDD 반복은 looping:autoloop-tdd, 브랜치에서 구현→푸시→PR까지 끌고 가는 건 looping:ship-pr-until-green)

랠프 스토리 실행기 (Ralph Story Executor)

매번 새 컨텍스트로: prd.json에서 미완료 스토리 하나를 골라 구현하고, 백프레셔 검사를 돌린 뒤 커밋하고, 다음 반복 전에 진행 상황을 기록합니다.

항목	값
카테고리	자동화(Automation)
트리거	수동(manual) — 사람이 직접 시작
종료 조건(Exit)	.ralph/prd.json에 passes: false인 스토리가 하나도 남지 않을 때 (응답: ALL STORIES ARE COMPLETE)
반복 한도(Max iterations)	20
매 반복 체크 명령	npm test && npm run lint && npm run build
설치 파일	있음 — .ralph/prd.json·.ralph/progress.md 스캐폴딩이 디스크에 있어야 함
가드레일	강화됨(Hardened)
지원 에이전트	Claude Code · Cursor · Codex

이 루프는 언제 쓰나

PRD를 잘게 쪼갠 사용자 스토리 백로그가 있고, 이걸 "알아서 하나씩 다 구현해줘"라고 맡기고 싶을 때 씁니다. 이름의 "랠프(Ralph)"는 매 반복을 새 컨텍스트에서 시작하는 방식을 가리킵니다. 대화 기록에 상태를 쌓아두지 않고, 진실은 전부 디스크(.ralph/prd.json, .ralph/progress.md)에 둡니다. 그래서 컨텍스트가 길어지며 흐려지는 문제 없이, 매 회차가 깨끗한 머리로 스토리 하나에만 집중합니다.

한 반복이 하는 일은 단순합니다. 미완료 스토리 하나를 골라 최소 범위로 구현 → test·lint·build 백프레셔로 회귀를 막기 → 스토리 단위로 커밋 → passes: true로 표시하고 progress.md에 배운 점 한 줄. 그리고 다음 회차에 같은 일을 반복합니다. 핵심은 욕심내지 않는 것입니다. 한 번에 여러 스토리를 건드려 검사를 다 빨갛게 만드는 대신, 딱 하나씩 green으로 끝내고 넘어갑니다.

루프 흐름

수동 시작
   │
   ▼
① 상태 읽기   .ralph/prd.json · .ralph/progress.md
   │           (inProgress 있으면 이어받고, 없으면 passes:false 중 최저 우선순위 선택)
   ▼
② 스토리 1개 구현   inProgress로 표시 후, 최소 범위로 구현
   │
   ▼
③ 백프레셔 실행   npm test && npm run lint && npm run build  (실패면 커밋 전에 수정)
   │
   ▼
④ 커밋 · 기록   스토리 단위 커밋 → passes:true → progress.md에 학습 추가
   │
   ▼
〔피드백 게이트〕passes:false 스토리가 아직 남았나?
   │
   ├─ 예(남음)   → ① 로 돌아가 다음 스토리 반복 (최대 20회)
   └─ 아니오(전부 passes:true) → 종료 ("ALL STORIES ARE COMPLETE")

매 반복(pass)마다 하는 일

1. 상태 읽기 — .ralph/prd.json과 .ralph/progress.md를 읽습니다. inProgress로 표시된 스토리가 있으면 그걸 이어받고, 없으면 passes: false인 스토리 중 우선순위가 가장 낮은(=가장 먼저 해야 할) 것을 고릅니다.
2. 스토리 1개 구현 — 사용자 스토리를 정확히 하나만, 최소 범위로 구현합니다. 코딩을 시작하기 전에 prd.json에서 그 스토리를 inProgress로 표시하세요.
3. 백프레셔 실행 — AGENTS.md에 적힌 프로젝트의 test·lint·build 명령을 돌립니다. 실패가 있으면 커밋하기 전에 고칩니다.

   npm test && npm run lint && npm run build
   

4. 커밋 · 기록 — 스토리 범위에 맞는 메시지로 커밋합니다. prd.json에서 해당 스토리를 passes: true로 바꾸고, 배운 점을 progress.md에 덧붙입니다.

가드레일 (점수 조작 방지 규칙)

종료 조건을 "가짜로" 통과시키지 못하게 막는 규칙입니다. 반드시 지키세요.

• 체크 명령이나 종료 기준을 고쳐서 억지로 성공시키지 않는다.
• 체크를 건너뛰거나 비활성화·우회해서 종료 조건을 통과시키지 않는다.
• 여러 번 반복해도 막히면, 지표를 조작하지 말고 멈추고 블로커를 보고한다.

Claude Code에서 실행하기

이 루프는 수동(manual) 트리거입니다. 아래 kickoff 프롬프트를 그대로 붙여넣으면 에이전트가 스스로 페이싱하며 스토리를 하나씩 완주시킵니다.

전제 — .ralph/ 스캐폴딩이 디스크에 있어야 합니다. 이 루프는 .ralph/prd.json(스토리 백로그)과 .ralph/progress.md(학습 로그)를 읽습니다. 원본 사이트의 Install files zip을 받아 레포 루트에 풀거나, 직접 두 파일을 만들어 두세요. (최소 형태는 아래 "팁 / 변형" 참고.) 브라우저는 레포에 파일을 써넣지 못하므로, 파일을 손수 올리기 전까지는 "설치된" 상태가 아닙니다.

붙여넣을 kickoff:

"랠프 스토리 실행기(Ralph Story Executor)" 루프를 시작합니다.

목표: .ralph/prd.json의 모든 스토리가 passes: true
최대 반복: 20
매 반복 사이 실행: npm test && npm run lint && npm run build
종료 조건: passes: false인 스토리가 하나도 남지 않을 때 ("ALL STORIES ARE COMPLETE"라고 응답)

1단계: .ralph/prd.json과 .ralph/progress.md를 읽는다. 미완료 스토리 하나를 골라
구현하고, 백프레셔 검사를 돌리고, 커밋하고, prd.json과 progress.md를 갱신한 뒤,
이번 반복을 멈춘다.

이 루프를 스스로 페이싱(self-pace)하라. 매 반복은 정확히 스토리 하나만 처리한다.
상태는 채팅 기록이 아니라 디스크에 저장된다.

팁: npm test && npm run lint && npm run build는 예시입니다. 프로젝트의 실제 명령은 AGENTS.md에 적힌 것을 따르세요(예: pnpm test && pnpm lint && pnpm build, pytest && ruff check . && python -m build).

팁 / 변형

• prd.json 최소 형태: 스토리마다 우선순위와 passes 플래그만 있으면 됩니다. 루프는 inProgress로 재개할 스토리를 표시하고, passes로 완료를 추적합니다.

  {
    "stories": [
      { "id": "S1", "priority": 1, "story": "사용자는 이메일로 로그인할 수 있다", "passes": false },
      { "id": "S2", "priority": 2, "story": "비밀번호 재설정 메일을 받는다", "passes": false }
    ]
  }
  

• 백프레셔 교체: 검사 명령을 생태계에 맞게 바꾸세요. 모노레포면 turbo run test lint build, Go면 go test ./... && golangci-lint run && go build ./..., Rust면 cargo test && cargo clippy && cargo build.
• 막힐 때: 같은 스토리에서 백프레셔가 반복해서 빨개지면, 가드레일대로 검사를 약화시키지 말고 멈춰서 블로커를 보고하게 하세요. 실패 패턴을 디스크에 학습으로 남기고 싶으면 looping:guardrails-learning-loop와 함께 돌립니다.
• 연관 루프: 스토리 대신 spec.md 체크리스트로 출시하려면 looping:spec-first-ship, 구현이 "끝났다"고 주장한 뒤 독립 검증을 붙이려면 looping:independent-verifier-pass, 통과 후 정리 패스는 looping:de-sloppify-pass.

원본 영어 kickoff (loops.elorm.xyz 원문)

Start the "Ralph Story Executor" loop.

Goal: every story in .ralph/prd.json has passes: true
Max iterations: 20
Between iterations run: npm test && npm run lint && npm run build
Exit when: no stories remain with passes: false (respond "ALL STORIES ARE COMPLETE")

Step 1: Read .ralph/prd.json and .ralph/progress.md. Pick one incomplete story, implement it, run backpressure checks, commit, update prd.json and progress.md, then stop this iteration.

Self-pace this loop. Each iteration does exactly one story. State lives on disk, not in chat history.

출처: https://loops.elorm.xyz/loops/ralph-story-executor