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