Ralph TUI - JSON 태스크 생성
PRD를 ralph-tui 자율 실행을 위한 prd.json 형식으로 변환합니다.
참고: 이 스킬은 ralph-tui의 JSON 트래커 플러그인과 함께 번들로 제공됩니다. 향후 트래커 플러그인(Linear, GitHub Issues 등)은 자체 태스크 생성 스킬을 번들로 제공할 예정입니다.
⚠️ 중요: 출력은 루트 레벨에 "name"과 "userStories"를 가진 평면 JSON 객체여야 합니다. 내용을 "prd" 객체로 감싸거나 "tasks" 배열을 사용하지 마세요. 아래 "스키마 안티패턴" 섹션을 참조하세요.
작업
PRD(마크다운 파일 또는 텍스트)를 가져와 prd.json 파일을 생성합니다:
- PRD의 "Quality Gates" 섹션에서 품질 게이트 추출
- PRD에서 사용자 스토리 파싱
- 각 스토리의 수락 기준에 품질 게이트 추가
- 스토리 간 종속성 설정
ralph-tui run --prd <path>실행을 위한 출력 준비
1단계: 품질 게이트 추출
PRD에서 "Quality Gates" 섹션을 찾으세요:
## Quality Gates
모든 사용자 스토리에서 통과해야 하는 명령어:
- `pnpm typecheck` - 타입 검사
- `pnpm lint` - 린트
UI 스토리의 경우 다음도 포함합니다:
- dev-browser 스킬을 사용하여 브라우저에서 확인
추출:
- 공통 게이트: 모든 스토리에 적용되는 명령어(예:
pnpm typecheck) - UI 게이트: UI 스토리에만 적용되는 명령어(예: 브라우저 확인)
Quality Gates 섹션이 없는 경우: 사용자에게 어떤 명령어가 통과해야 하는지 물어보거나, npm run typecheck와 같은 합리적인 기본값을 사용하세요.
출력 형식
JSON 파일은 루트 레벨에서 평면 객체여야 합니다:
{
"name": "[PRD 또는 디렉토리의 프로젝트 이름]",
"branchName": "ralph/[기능-이름-케밥-케이스]",
"description": "[PRD의 기능 설명]",
"userStories": [
{
"id": "US-001",
"title": "[스토리 제목]",
"description": "As a [사용자], I want [기능] so that [이점]",
"acceptanceCriteria": [
"PRD의 기준 1",
"PRD의 기준 2",
"pnpm typecheck 통과",
"pnpm lint 통과"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "[US-001에 의존하는 UI 스토리]",
"description": "...",
"acceptanceCriteria": [
"...",
"pnpm typecheck 통과",
"pnpm lint 통과",
"dev-browser 스킬을 사용하여 브라우저에서 확인"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
}
]
}
중요: 스키마 안티패턴 (사용 금지)
다음 패턴은 유효하지 않으며 검증 오류가 발생합니다:
❌ 잘못됨: 래퍼 객체
{
"prd": {
"name": "...",
"userStories": [...]
}
}
이것은 모든 것을 "prd" 객체로 감쌉니다. 이렇게 하지 마세요. "name"과 "userStories" 필드는 루트 레벨에 있어야 합니다.
❌ 잘못됨: "userStories" 대신 "tasks" 사용
{
"name": "...",
"tasks": [...]
}
배열의 이름은 "userStories" 이지 "tasks"가 아닙니다.
❌ 잘못됨: 복잡한 중첩 구조
{
"metadata": {...},
"overview": {...},
"migration_strategy": {
"phases": [...]
}
}
PRD에서 단계/마일스톤/스프린트를 설명하더라도, 이것들을 단일 "userStories" 배열로 평탄화해야 합니다.
❌ 잘못됨: "passes" 대신 "status" 사용
{
"userStories": [{
"id": "US-001",
"status": "open" // 잘못됨!
}]
}
미완료 스토리에는 "passes": false를, 완료된 스토리에는 "passes": true를 사용하세요.
✅ 올바름: 루트의 평면 구조
{
"name": "Android Kotlin 마이그레이션",
"branchName": "ralph/kotlin-migration",
"userStories": [
{"id": "US-001", "title": "Scraper 인터페이스 생성", "passes": false, "dependsOn": []},
{"id": "US-002", "title": "WeebCentralScraper 구현", "passes": false, "dependsOn": ["US-001"]}
]
}
스토리 크기: 가장 중요한 규칙
각 스토리는 하나의 ralph-tui 반복(~에이전트 컨텍스트 창 하나) 안에 완료 가능해야 합니다.
Ralph-tui는 반복마다 이전 작업에 대한 메모리 없이 새로운 에이전트 인스턴스를 생성합니다. 스토리가 너무 크면 에이전트가 완료하기 전에 컨텍스트가 소진됩니다.
적절한 크기의 스토리:
- 데이터베이스 열 + 마이그레이션 추가
- 기존 페이지에 UI 컴포넌트 추가
- 새 로직으로 서버 액션 업데이트
- 목록에 필터 드롭다운 추가
너무 큰 스토리(분할 필요):
- "전체 대시보드 구축" → 스키마, 쿼리, UI 컴포넌트, 필터로 분할
- "인증 추가" → 스키마, 미들웨어, 로그인 UI, 세션 처리로 분할
- "API 리팩토링" → 엔드포인트 또는 패턴별로 하나의 스토리로 분할
경험 법칙: 변경 사항을 2-3 문장으로 설명할 수 없다면 너무 큰 것입니다.
dependsOn을 사용한 종속성
dependsOn 배열을 사용하여 먼저 완료되어야 하는 스토리를 지정하세요:
{
"id": "US-002",
"title": "API 엔드포인트 생성",
"dependsOn": ["US-001"], // US-001이 통과될 때까지 선택되지 않음
...
}
Ralph-tui는:
- US-001이 완료될 때까지 US-002를 "차단됨"으로 표시
- US-001이 열려 있는 동안 US-002를 실행용으로 선택하지 않음
- US-002 작업 시 프롬프트에 "전제 조건: US-001" 포함
올바른 종속성 순서:
- 스키마/데이터베이스 변경(종속성 없음)
- 백엔드 로직(스키마에 의존)
- UI 컴포넌트(백엔드에 의존)
- 통합/정리(UI에 의존)
수락 기준: 품질 게이트 + 스토리별
각 스토리의 수락 기준에는 다음이 포함되어야 합니다:
- PRD의 스토리별 기준(이 스토리가 수행하는 작업)
- PRD의 Quality Gates 섹션의 품질 게이트(끝에 추가)
좋은 기준(검증 가능):
- "tasks 테이블에 기본값 'open'인
status열 추가" - "필터 드롭다운에 옵션: All, Open, Closed"
- "삭제 클릭 시 확인 대화상자 표시"
나쁜 기준(모호함):
- ❌ "올바르게 작동"
- ❌ "사용자가 쉽게 X를 할 수 있음"
- ❌ "좋은 UX"
- ❌ "엣지 케이스 처리"
변환 규칙
- PRD에서 품질 게이트 추출 먼저 수행
- 각 사용자 스토리 → 하나의 JSON 항목
- ID: 순차적(US-001, US-002 등)
- 우선순위: 종속성 순서 기반(1 = 가장 높음)
- dependsOn: 이 스토리가 필요로 하는 스토리 ID 배열
- 모든 스토리:
passes: false및 빈notes - branchName: 기능 이름에서 파생, 케밥-케이스,
ralph/접두사 - 수락 기준: 스토리 기준 + 품질 게이트 추가
- UI 스토리: UI 관련 게이트도 추가(브라우저 확인)
출력 위치
기본값: ./tasks/prd.json (PRD 마크다운 파일과 같은 위치)
이렇게 하면 모든 PRD 관련 파일이 tasks/ 디렉토리에 함께 유지됩니다.
또는 다른 경로를 지정하세요 - ralph-tui는 다음 명령어로 사용합니다:
ralph-tui run --prd ./path/to/prd.json
예시
입력 PRD:
# PRD: 태스크 우선순위 시스템
태스크에 우선순위 레벨을 추가합니다.
## Quality Gates
모든 사용자 스토리에서 통과해야 하는 명령어:
- `pnpm typecheck` - 타입 검사
- `pnpm lint` - 린트
UI 스토리의 경우 다음도 포함합니다:
- dev-browser 스킬을 사용하여 브라우저에서 확인
## 사용자 스토리
### US-001: 데이터베이스에 우선순위 필드 추가
**설명:** 개발자로서 태스크 우선순위를 저장해야 합니다.
**수락 기준:**
- [ ] 우선순위 열 추가: 1-4 (기본값 2)
- [ ] 마이그레이션 성공적으로 실행
### US-002: 태스크 카드에 우선순위 배지 표시
**설명:** 사용자로서 태스크 우선순위를 한 눈에 보고 싶습니다.
**수락 기준:**
- [ ] 배지에 P1/P2/P3/P4 색상 표시
- [ ] 배지가 호버 없이도 보임
### US-003: 우선순위 필터 드롭다운 추가
**설명:** 사용자로서 태스크를 우선순위별로 필터링하고 싶습니다.
**수락 기준:**
- [ ] 필터 드롭다운: All, P1, P2, P3, P4
- [ ] 필터가 URL에 유지됨
출력 prd.json:
{
"project": "my-app",
"branchName": "ralph/task-priority",
"description": "태스크에 우선순위 레벨 추가",
"userStories": [
{
"id": "US-001",
"title": "데이터베이스에 우선순위 필드 추가",
"description": "As a developer, I need to store task priority.",
"acceptanceCriteria": [
"우선순위 열 추가: 1-4 (기본값 2)",
"마이그레이션 성공적으로 실행",
"pnpm typecheck 통과",
"pnpm lint 통과"
],
"priority": 1,
"passes": false,
"notes": "",
"dependsOn": []
},
{
"id": "US-002",
"title": "태스크 카드에 우선순위 배지 표시",
"description": "As a user, I want to see task priority at a glance.",
"acceptanceCriteria": [
"배지에 P1/P2/P3/P4 색상 표시",
"배지가 호버 없이도 보임",
"pnpm typecheck 통과",
"pnpm lint 통과",
"dev-browser 스킬을 사용하여 브라우저에서 확인"
],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
},
{
"id": "US-003",
"title": "우선순위 필터 드롭다운 추가",
"description": "As a user, I want to filter tasks by priority.",
"acceptanceCriteria": [
"필터 드롭다운: All, P1, P2, P3, P4",
"필터가 URL에 유지됨",
"pnpm typecheck 통과",
"pnpm lint 통과",
"dev-browser 스킬을 사용하여 브라우저에서 확인"
],
"priority": 3,
"passes": false,
"notes": "",
"dependsOn": ["US-002"]
}
]
}
ralph-tui로 실행하기
prd.json 생성 후:
ralph-tui run --prd ./tasks/prd.json
Ralph-tui는:
- prd.json에서 스토리 로드
passes: false이고 차단 종속성이 없는 가장 높은 우선순위 스토리 선택- 스토리 세부 정보 + 수락 기준이 포함된 프롬프트 생성
- 스토리 구현을 위해 에이전트 실행
- 완료 시
passes: true표시 - 모든 스토리가 통과될 때까지 반복
저장 전 확인 목록
- PRD에서 품질 게이트를 추출했거나(또는 없는 경우 사용자에게 물어봄)
- 각 스토리가 한 번의 반복에서 완료 가능함
- 스토리가 종속성 순서로 정렬됨(스키마 → 백엔드 → UI)
- 각 스토리에
dependsOn이 올바르게 설정됨 - 모든 스토리의 수락 기준에 품질 게이트가 추가됨
- UI 스토리에 브라우저 확인이 있음(Quality Gates에 지정된 경우)
- 수락 기준이 검증 가능함(모호하지 않음)
- 순환 종속성이 없음