Ralph JSON

Ralph JSON

PRD, 요구사항, 기능 설명을 Ralph 실행기가 읽을 수 있는 prd.json으로 바꾼다. 이 스킬은 구현하지 않는다. prd.json을 만들거나 검증하는 데만 집중한다.

입력

입력은 다음 중 하나다.

• PRD markdown 파일
• 요구사항 문서
• 대화에 적힌 기능 설명
• 기존 prd.json 수정 요청

파일 경로가 있으면 먼저 읽고, 프로젝트 구조가 필요한 경우 관련 문서와 AGENTS.md를 확인한다.

출력

기본 출력 위치는 프로젝트 루트의 prd.json이다. 기존 prd.json이 있으면 덮어쓰기 전에 같은 feature인지 확인하고, 다르면 사용자에게 위험을 짧게 알린다.

필수 schema:

{
  "project": "ProjectName",
  "branchName": "ralph/feature-name",
  "description": "Feature description",
  "userStories": [
    {
      "id": "US-001",
      "title": "Small story title",
      "description": "As a user, I want a focused behavior so that I get a clear benefit.",
      "acceptanceCriteria": [
        "Specific verifiable criterion",
        "Typecheck passes"
      ],
      "priority": 1,
      "type": "AFK",
      "blockedBy": [],
      "passes": false,
      "notes": ""
    }
  ]
}

변환 규칙

1. 기능 이름에서 project, branchName, description을 만든다.
2. 큰 요구사항을 user story로 쪼갠다.
3. story 하나는 Ralph iteration 하나에서 끝낼 수 있는 크기로 제한한다.
4. dependency 순서로 priority를 부여한다.
5. 자동 실행 가능한 story는 type:"AFK", 사람 판단이 필요한 story는 type:"HITL"로 표시한다.
6. 선행 story가 있으면 blockedBy:["US-001"]처럼 ID를 넣고, 없으면 빈 배열로 둔다.
7. 모든 story는 passes:false, notes:""로 시작한다.
8. ID는 US-001, US-002처럼 순차 부여한다.
9. acceptance criteria는 실제로 확인 가능한 문장만 쓴다.
10. 모든 story에 Typecheck passes를 넣는다.
11. 테스트 가능한 로직 story에는 Tests pass를 넣는다.
12. UI story에는 브라우저 검증 기준을 넣는다.

Story 크기

좋은 크기:

• DB column 또는 migration 하나 추가
• endpoint 또는 server function 하나 추가
• 기존 화면에 UI component 하나 추가
• 목록에 filter 하나 추가
• 한 가지 interaction 저장 흐름 추가

너무 큰 크기:

• 전체 dashboard 구현
• 인증 전체 구현
• API 전체 리팩터링
• 설정 페이지 전체 구현

story를 2-3문장으로 설명하기 어렵다면 더 쪼갠다.

Priority 기준

기본 순서:

1. schema, migration, storage
2. backend, service, server action, API
3. data loading, query, integration
4. UI display
5. UI interaction
6. aggregate view, polish, settings

앞 story가 뒤 story에 의존하면 안 된다.

AFK/HITL 기준

• AFK: 요구사항, 입력, 검증 기준이 충분해서 Codex가 story 하나를 바로 구현해도 되는 단위
• HITL: 디자인 결정, 제품 판단, 외부 권한, 수동 승인, 모호한 도메인 결정이 필요한 단위

ralph-flow 실행기는 기본적으로 AFK이면서 blockedBy가 모두 통과한 story만 선택한다.

Acceptance Criteria 기준

좋은 기준:

• notifications storage includes userId, title, body, readAt, createdAt
• GET /notifications returns current user's notifications sorted by createdAt descending
• Header badge displays unread count
• Clicking a notification sets readAt and updates the badge
• Typecheck passes
• Tests pass

나쁜 기준:

• Works correctly
• Good UX
• Handles edge cases
• Clean code

검증

prd.json을 만든 뒤 bundled script로 형식을 확인한다.

~/.codex/skills/ralph-json/scripts/validate-prd-json.sh prd.json

검증은 schema와 기본 품질만 확인한다. story가 실제로 충분히 작은지는 작성자가 다시 읽고 판단한다.

다음 단계

prd.json이 준비되면 $ralph-flow를 사용한다.

~/.codex/skills/ralph-flow/scripts/ralph-codex.sh --project "$PWD" --dry-run