Ralph TUI - 비즈 생성
PRD를 ralph-tui 자율 실행을 위한 비즈(에픽 + 하위 작업)로 변환합니다.
참고: 이 스킬은 ralph-tui의 Beads 트래커 플러그인과 함께 제공됩니다. 향후 트래커 플러그인(Linear, GitHub Issues 등)은 각각 자체 작업 생성 스킬을 번들로 제공할 예정입니다.
작업
PRD(마크다운 파일 또는 텍스트)를 가져와 .beads/beads.jsonl에 비즈를 생성합니다:
- PRD의 '품질 게이트' 섹션에서 품질 게이트 추출
- 기능에 대한 에픽 비즈 생성
- 각 사용자 스토리에 대한 하위 비즈 생성 (품질 게이트 추가)
- 비즈 간 의존성 설정 (스키마 → 백엔드 → UI)
ralph-tui run --tracker beads실행 준비 완료
1단계: 품질 게이트 추출
PRD에서 '품질 게이트' 섹션을 찾습니다:
## 품질 게이트
모든 사용자 스토리에서 통과해야 하는 명령:
- `pnpm typecheck` - 타입 검사
- `pnpm lint` - 린팅
UI 스토리의 경우 다음도 포함:
- dev-browser 스킬을 사용하여 브라우저에서 확인
추출 대상:
- 공용 게이트: 모든 스토리에 적용되는 명령 (예:
pnpm typecheck) - UI 게이트: UI 스토리에만 적용되는 명령 (예: 브라우저 확인)
품질 게이트 섹션이 없는 경우: 사용자에게 어떤 명령이 통과해야 하는지 묻거나, npm run typecheck와 같은 적절한 기본값을 사용합니다.
출력 형식
비즈는 특수 문자를 안전하게 처리하기 위해 HEREDOC 구문과 함께 bd create 명령을 사용합니다:
# 에픽 생성 (소스 PRD로 연결)
bd create --type=epic \
--title="[기능 이름]" \
--description="$(cat <<'EOF'
[PRD의 기능 설명]
EOF
)" \
--external-ref="prd:./tasks/feature-name-prd.md"
# 하위 비즈 생성 (수락 기준에 품질 게이트 포함)
bd create \
--parent=EPIC_ID \
--title="[스토리 제목]" \
--description="$(cat <<'EOF'
[품질 게이트를 포함한 수락 기준이 있는 스토리 설명]
EOF
)" \
--priority=[1-4]
중요: 항상
<<'EOF'(작은따옴표)를 HEREDOC 구분자로 사용하세요. 이렇게 하면 설명에서 백틱,$변수,()의 셸 해석을 방지할 수 있습니다.
스토리 크기: 가장 중요한 규칙
각 스토리는 ralph-tui 한 번의 반복(약 한 번의 에이전트 컨텍스트 윈도우) 내에 완료 가능해야 합니다.
ralph-tui는 반복마다 새로운 에이전트 인스턴스를 생성하며 이전 작업에 대한 메모리가 없습니다. 스토리가 너무 크면 에이전트가 작업을 끝내기 전에 컨텍스트가 소진됩니다.
적절한 크기의 스토리:
- 데이터베이스 컬럼 추가 + 마이그레이션
- 기존 페이지에 UI 컴포넌트 추가
- 새로운 로직으로 서버 액션 업데이트
- 목록에 필터 드롭다운 추가
너무 큰 경우 (분할 필요):
- "전체 대시보드 구축" → 스키마, 쿼리, UI 컴포넌트, 필터로 분할
- "인증 추가" → 스키마, 미들웨어, 로그인 UI, 세션 처리로 분할
- "API 리팩터링" → 엔드포인트 또는 패턴별로 하나의 스토리로 분할
경험 법칙: 변경 사항을 2-3문장으로 설명할 수 없다면 너무 큰 것입니다.
스토리 순서: 의존성 우선
스토리는 의존성 순서대로 실행됩니다. 앞선 스토리는 이후 스토리에 의존해서는 안 됩니다.
올바른 순서:
- 스키마/데이터베이스 변경 (마이그레이션)
- 서버 액션 / 백엔드 로직
- 백엔드를 사용하는 UI 컴포넌트
- 데이터를 집계하는 대시보드/요약 뷰
잘못된 순서:
- ❌ UI 컴포넌트 (아직 존재하지 않는 스키마에 의존)
- ❌ 스키마 변경
bd dep add로 의존성 추가
bd dep add 명령을 사용하여 먼저 완료되어야 하는 비즈를 지정합니다:
# 먼저 비즈 생성
bd create --parent=epic-123 --title="US-001: 스키마 추가" ...
bd create --parent=epic-123 --title="US-002: API 생성" ...
bd create --parent=epic-123 --title="US-003: UI 구축" ...
# 그런 다음 의존성 추가 (이슈는 차단자에 의존)
bd dep add ralph-tui-002 ralph-tui-001 # US-002는 US-001에 의존
bd dep add ralph-tui-003 ralph-tui-002 # US-003은 US-002에 의존
구문: bd dep add <이슈> <의존-대상> — 이슈는 의존-대상에 의존함 (차단됨).
ralph-tui는:
- 의존성이 완료될 때까지 차단된 비즈를 "차단됨"으로 표시
- 의존성이 열려 있는 동안 해당 비즈를 실행 대상으로 선택하지 않음
- 비즈 작업 시 프롬프트에 의존성 컨텍스트 포함
올바른 의존성 순서:
- 스키마/데이터베이스 변경 (의존성 없음)
- 백엔드 로직 (스키마에 의존)
- UI 컴포넌트 (백엔드에 의존)
- 통합/개선 (UI에 의존)
수락 기준: 품질 게이트 + 스토리별 기준
각 비즈의 설명에는 다음 수락 기준이 포함되어야 합니다:
- 스토리별 기준 (PRD에서 가져온, 이 스토리가 달성하는 내용)
- 품질 게이트 (PRD의 품질 게이트 섹션에서 가져온, 끝에 추가)
좋은 기준 (검증 가능):
- "investor 테이블에 기본값 'cold'인
investorType컬럼 추가" - "필터 드롭다운에 옵션: 전체, 콜드, 친구"
- "토글 클릭 시 확인 대화상자 표시"
나쁜 기준 (모호):
- ❌ "올바르게 작동"
- ❌ "사용자가 X를 쉽게 할 수 있음"
- ❌ "좋은 UX"
- ❌ "엣지 케이스 처리"
변환 규칙
- PRD에서 품질 게이트 추출 우선
- 각 사용자 스토리 → 하나의 비즈
- 첫 번째 스토리: 의존성 없음 (기초 생성)
- 후속 스토리: 이전 스토리에 의존 (UI는 백엔드에 의존 등)
- 우선순위: 의존성 순서 기반, 그다음 문서 순서 (0=중요, 2=보통, 4=백로그)
- 모든 스토리:
status: "open" - 수락 기준: 스토리 기준 + 품질 게이트 추가
- UI 스토리: UI별 게이트도 추가 (브라우저 확인)
대형 PRD 분할
PRD에 큰 기능이 있는 경우 분할합니다:
원본:
"다른 메시징을 사용한 친구 아웃리치 트랙 추가"
분할:
- US-001: 데이터베이스에 investorType 필드 추가
- US-002: 투자자 목록 UI에 유형 토글 추가
- US-003: 친구별 단계 진행 로직 생성
- US-004: 친구 메시지 템플릿 생성
- US-005: 친구용 작업 생성 연결
- US-006: 유형별 필터 추가
- US-007: 신규 투자자 양식 업데이트
- US-008: 대시보드 카운트 업데이트
각각은 집중된 변경이며 독립적으로 완료 및 검증 가능합니다.
예제
입력 PRD:
# PRD: 친구 아웃리치
투자자를 '친구'로 표시하여 따뜻한 아웃리치를 할 수 있는 기능 추가.
## 품질 게이트
모든 사용자 스토리에서 통과해야 하는 명령:
- `pnpm typecheck` - 타입 검사
- `pnpm lint` - 린팅
UI 스토리의 경우 다음도 포함:
- dev-browser 스킬을 사용하여 브라우저에서 확인
## 사용자 스토리
### US-001: investor 테이블에 investorType 필드 추가
**설명:** 개발자로서 투자자를 'cold' 또는 'friend'로 분류해야 합니다.
**수락 기준:**
- [ ] investorType 컬럼 추가: 'cold' | 'friend' (기본값 'cold')
- [ ] 마이그레이션 생성 및 성공적으로 실행
### US-002: 투자자 목록 행에 유형 토글 추가
**설명:** Ryan으로서 목록에서 직접 투자자 유형을 전환하고 싶습니다.
**수락 기준:**
- [ ] 각 행에 Cold | Friend 토글 있음
- [ ] 전환 시 확인 대화상자 표시
- [ ] 확인 시: 데이터베이스에서 유형 업데이트
### US-003: 유형별 투자자 필터링
**설명:** Ryan으로서 목록을 필터링하여 친구 또는 cold만 보고 싶습니다.
**수락 기준:**
- [ ] 필터 드롭다운: 전체 | Cold | Friend
- [ ] 필터가 URL 파라미터에 유지됨
출력 비즈:
# 에픽 생성 (소스 PRD로 연결)
bd create --type=epic \
--title="친구 아웃리치 트랙" \
--description="$(cat <<'EOF'
덱 피드백을 위한 따뜻한 아웃리치
EOF
)" \
--external-ref="prd:./tasks/friends-outreach-prd.md"
# US-001: 의존성 없음 (처음 - 스키마 생성)
bd create --parent=ralph-tui-abc \
--title="US-001: investor 테이블에 investorType 필드 추가" \
--description="$(cat <<'EOF'
개발자로서 투자자를 'cold' 또는 'friend'로 분류해야 합니다.
## 수락 기준
- [ ] investorType 컬럼 추가: 'cold' | 'friend' (기본값 'cold')
- [ ] 마이그레이션 생성 및 성공적으로 실행
- [ ] pnpm typecheck 통과
- [ ] pnpm lint 통과
EOF
)" \
--priority=1
# US-002: UI 스토리 (브라우저 확인도 추가)
bd create --parent=ralph-tui-abc \
--title="US-002: 투자자 목록 행에 유형 토글 추가" \
--description="$(cat <<'EOF'
Ryan으로서 목록에서 직접 투자자 유형을 전환하고 싶습니다.
## 수락 기준
- [ ] 각 행에 Cold | Friend 토글 있음
- [ ] 전환 시 확인 대화상자 표시
- [ ] 확인 시: 데이터베이스에서 유형 업데이트
- [ ] pnpm typecheck 통과
- [ ] pnpm lint 통과
- [ ] dev-browser 스킬을 사용하여 브라우저에서 확인
EOF
)" \
--priority=2
# 의존성 추가: US-002는 US-001에 의존
bd dep add ralph-tui-002 ralph-tui-001
# US-003: UI 스토리
bd create --parent=ralph-tui-abc \
--title="US-003: 유형별 투자자 필터링" \
--description="$(cat <<'EOF'
Ryan으로서 목록을 필터링하여 친구 또는 cold만 보고 싶습니다.
## 수락 기준
- [ ] 필터 드롭다운: 전체 | Cold | Friend
- [ ] 필터가 URL 파라미터에 유지됨
- [ ] pnpm typecheck 통과
- [ ] pnpm lint 통과
- [ ] dev-browser 스킬을 사용하여 브라우저에서 확인
EOF
)" \
--priority=3
# 의존성 추가: US-003은 US-002에 의존
bd dep add ralph-tui-003 ralph-tui-002
출력 위치
비즈는 다음 위치에 기록됩니다: .beads/beads.jsonl
생성 후 ralph-tui를 실행합니다:
# 특정 에픽 작업
ralph-tui run --tracker beads --epic ralph-tui-abc
# 또는 자동으로 가장 좋은 작업 선택
ralph-tui run --tracker beads
ralph-tui는:
- 지정된 에픽 내의 비즈를 작업 (또는 가장 좋은 사용 가능한 작업 선택)
- 완료 시 각 비즈 닫기
- 모든 하위 비즈가 완료되면 에픽 닫기
- 에픽 완료 시
<promise>COMPLETE</promise>출력
비즈 생성 전 체크리스트
- PRD에서 품질 게이트 추출 (또는 없는 경우 사용자에게 문의)
- 각 스토리가 한 번의 반복 내에 완료 가능 (충분히 작은 크기)
- 스토리가 의존성 순서대로 정렬됨 (스키마 → 백엔드 → UI)
- 모든 비즈의 수락 기준에 품질 게이트 추가
- UI 스토리에 브라우저 확인 포함 (품질 게이트에 지정된 경우)
- 수락 기준이 검증 가능 (모호하지 않음)
- 어떤 스토리도 이후 스토리에 의존하지 않음 (이전 스토리만)
- 비즈 생성 후
bd dep add로 의존성 추가