klaus/sodalive-android
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
26eae18edce0cc0d50d63a2c6429797fb7e20667
sodalive-android/docs/sample/sample-prd.md

12 KiB
Raw Blame History

제품 요구사항 문서(PRD) 샘플

이 문서는 요구사항을 API Contract와 goal 실행형 plan-task.md로 연결하기 위한 템플릿이다. 실제 prd.md를 만들 때 <...> placeholder와 예시 ID를 모두 제품의 구체적인 값으로 교체한다.

문서 정보

항목 내용
문서 상태 초안 / 검토 중 / 구현 기준 확정 / 구현 완료
작성일 YYYY-MM-DD
최종 수정일 YYYY-MM-DD
대상 제품 <제품 또는 기능 이름>
작성자·결정권자 <이름 또는 역할>
관련 API Contract <대상 api-contract.md 경로>
관련 구현 계획 <대상 plan-task.md 경로>
관련 review <없음 또는 같은 작업 디렉터리의 reviews/ 아래 문서 링크>

요구사항 상태

상태 의미 구현 처리
확정 제품·기술 결정이 완료되어 구현 기준으로 사용 plan-task.md의 Task와 완료 증거로 추적
미결 제품·UX·운영 결정이 더 필요함 권고안과 결정 주체·기한을 기록하고 임의 구현 금지
외부 의존 프론트엔드 밖의 계약·권한·환경 제공이 필요함 담당 주체·영향·재개 조건을 기록하고 추정 구현 금지
권고 미결 항목에 대한 현재 추천안 확정되기 전 계약이나 수용 기준으로 사용하지 않음
제외 현재 릴리스에서 구현하지 않기로 결정 제외 이유와 후속 조건을 Decision Log에 기록

문서 우선순위와 갱신 순서

  1. 사용자·제품 결정은 이 PRD에 기록한다.
  2. request/response/error 계약은 api-contract.md에 정규화한다.
  3. 구현 범위·순서·완료 증거는 plan-task.md에 반영한다.
  4. 요구사항이 바뀌면 Decision Log → 관련 요구사항·수용 기준 → API Contract → plan 순서로 갱신한다.
  5. 기존 결정과 검증 기록은 삭제하거나 덮어쓰지 않고 정정 기록을 누적한다.

1. Overview

<누가 어떤 상황에서 어떤 가치를 얻는 제품인지 2~4문장으로 설명한다.>

2. Problem Statement

현재 사용자는 다음 문제를 겪는다.

  • <관찰 가능한 현재 문제>
  • <기존 방식의 비용·위험·제약>
  • <해결하지 않을 때의 사용자 또는 사업 영향>

문제를 해결했다는 판단은 <측정하거나 직접 확인할 결과>로 한다.

3. Goals

3.1 제품 목표

  • <사용자가 완료할 수 있어야 하는 핵심 결과>
  • <안전성·운영 효율·데이터 품질 목표>
  • <릴리스 후 측정 가능한 성공 목표>

3.2 UX 목표

  • <핵심 흐름의 명확성·속도 목표>
  • <오류·loading·empty·success feedback 목표>
  • <반응형·keyboard·접근성 목표>

4. Non-Goals

  • <명시적으로 구현하지 않을 기능>
  • <다음 릴리스 또는 외부 시스템 소유 범위>
  • <복원, hard delete, 자동 갱신처럼 금지할 동작>

Non-Goal을 변경하려면 Decision Log와 plan-task.md 범위를 먼저 갱신한다.

5. Target Users and Permissions

5.1 사용자

사용자 목표 주요 작업 사용 환경
<역할> <달성 목표> <조회·생성·수정 등> <desktop/mobile 등>

5.2 권한

  • 인증 주체: <사용자 또는 시스템>
  • 허용 역할: <role 목록>
  • 거부 조건: <401/403 또는 제품 정책>
  • 리소스 소유권: <tenant, characterId, ownerId 등 격리 기준>
  • read-only 조건: <비활성·권한 부족·외부 상태 등>

6. 핵심 사용자 흐름

  1. <시작 조건과 진입점>
  2. <대상 탐색·선택>
  3. <핵심 생성·조회·수정 동작>
  4. <성공 feedback과 다음 화면>
  5. <오류·권한·session 만료 복구>

각 흐름은 plan-task.md의 최소 하나의 Phase 결과와 E2E 완료 증거로 연결한다.

7. 정보 구조와 라우팅

/<entry>
/<resource>
/<resource>/:resourceId
  /<child-resource>
  • 전역 화면과 선택된 리소스 문맥의 경계를 명시한다.
  • URL path와 query에 보존할 식별자·검색·filter·page 상태를 명시한다.
  • 직접 링크·새로고침이 가능한 화면과 collection modal/Sheet처럼 별도 route가 없는 화면을 구분한다.
  • 존재하지 않음, 다른 소유자, 비활성 리소스의 처리는 서버 계약과 공통 오류 정책을 따른다.

8. 기능 요구사항

요구사항 ID는 <DOMAIN>-NNN 형식을 사용한다. 하나의 행에는 독립적으로 판정 가능한 요구사항 하나만 작성한다.

8.1 <도메인 A>

ID 상태 요구사항 수용 기준 계약/Goal 연결
DOMAINA-001 확정 <사용자가 할 수 있어야 하는 동작> <관찰 가능한 성공·오류 결과> api-contract.md §<번호>, P1-T1
DOMAINA-002 확정 <payload·상태·권한 불변식> <보내야/보내지 말아야 할 값과 test> P1-T2
DOMAINA-003 외부 의존 <외부 제공이 필요한 계약> <제공 전 network integration 0건> EXT-001, P1-T1

8.2 <도메인 B>

ID 상태 요구사항 수용 기준 계약/Goal 연결
DOMAINB-001 확정 <목록·상세·mutation 흐름> <loading·empty·error·success 포함> api-contract.md §<번호>, P2-T2
DOMAINB-002 미결 <제품 결정이 필요한 항목> <확정 전 최대값·동작 추정 금지> OQ-001

8.3 공통 파일·데이터 정책

ID 상태 요구사항 수용 기준 계약/Goal 연결
FILE-001 확정 <허용 확장자·MIME·크기> <정확한 byte 경계 test> api-contract.md §<번호>, <Goal ID>
DATA-001 확정 <날짜·가격·enum·pagination 규칙> <formatter/schema/contract test> <Goal ID>

9. 반응형 기능 범위

기능 Desktop Tablet Mobile 비고
조회 전체 전체 전체 <예외>
생성·수정 허용 허용 허용 / 조회 전용 <직접 route 차단 정책>
파일 upload 허용 허용 허용 / 미지원 <이유>
  • 화면에서 action을 숨기는 것뿐 아니라 직접 route와 mutation capability도 같은 정책으로 차단한다.
  • 최소 viewport, zoom, touch target과 virtual keyboard 조건을 수용 기준에 연결한다.

10. UI/UX Expectations

10.1 디자인과 component 원칙

  • <브랜드 token, theme 범위, typography>
  • Page는 route·query·permission·component 조합을 담당한다.
  • 도메인 표시·입력·상호작용은 feature component가 담당한다.
  • 두 개 이상 Phase에서 같은 의미·동작으로 재사용할 때만 shared component로 올린다.

10.2 화면 상태

  • 모든 비동기 화면에 loading·empty·error·success 상태를 정의한다.
  • mutation에는 진행 중·성공·실패·재시도·중복 제출 정책을 정의한다.
  • destructive action에는 대상·영향·복구 여부를 알리는 확인 절차를 둔다.

10.3 접근성

  • 모든 input은 visible label과 연결된 오류를 가진다.
  • keyboard-only 흐름, focus 표시·복귀, skip link와 live region 기준을 명시한다.
  • 색상만으로 상태를 전달하지 않고 목표 대비와 touch target을 명시한다.
  • <지원 viewport>, 200% zoom과 axe critical·serious 0건을 수용 기준으로 사용한다.

11. API 계약

11.1 공통 규칙

  • base URL과 인증 header: <값>
  • locale: <header와 값>
  • 성공 envelope: <type 또는 예시>
  • 오류 envelope와 status: <type 또는 예시>
  • pagination: <page/size/total/hasNext 규칙>
  • multipart JSON part: <이름>

11.2 Endpoint 추적

요구사항 Method Path 계약 상태 API Contract 소유 Goal
DOMAINA-001 <METHOD> <path> 제공됨 / 보정 필요 / 제공 대기 §<번호> <Goal ID>

11.3 외부 제공 대기 계약

ID 우선순위 제공 필요 계약 담당 주체 구현 영향 재개 조건
EXT-001 P0 / P1 <endpoint·DTO·오류 규칙> <팀/역할> <차단되는 흐름> <문서와 fixture 제공>
  • P0 계약이 없으면 영향을 받는 network flow를 완료로 표시하지 않는다.
  • 계약에 의존하지 않는 UI shell·상태 inventory·문서화는 독립적으로 진행할 수 있다.

12. 보안과 데이터 취급

  • 인증 정보 저장 위치와 lifecycle: <정확한 정책>
  • log·분석·오류 리포트 금지 값: <token, password, signed URL 등>
  • 업로드 파일명·MIME·본문 취급: <정책>
  • 리소스 격리와 ownership 검증: <정책>
  • 401·403·동시 실패 처리: <정책>
  • 감사 로그: <포함, 외부 의존 또는 후속 범위>

13. 성능과 품질 요구사항

  • 목록 pagination과 전체 로드 예외: <정책>
  • 검색 debounce와 기존 데이터 유지: <정책>
  • image layout shift와 lazy loading: <정책>
  • mutation 중복 제출·upload 취소/재시도: <정책>
  • 지원 runtime·browser: <정확한 범위>
  • test stack과 필수 Gate: <unit/integration/E2E/typecheck/lint/build>
  • backend 구현 전 UI 확인: <불필요 또는 explicit mock mode, production 금지, no-auto-fallback, mock/server 완료 상태 분리>

14. 성공 기준

14.1 기능 수용 기준

  • <핵심 사용자 journey가 성공한다.> (DOMAINA-001, P1-GATE)
  • <권한·오류·payload 불변식이 검증된다.> (DOMAINA-002, <test>)
  • <외부 의존의 구현 또는 제외 결정이 문서화된다.> (EXT-001)

14.2 UI/UX 수용 기준

  • loading·empty·error·success 상태가 있다.
  • keyboard-only로 핵심 흐름을 완료한다.
  • <최소 viewport>와 200% zoom에서 핵심 control이 가려지지 않는다.
  • axe critical·serious 위반이 0건이다.

14.3 추적성 완료 기준

  • 모든 확정 요구사항이 API Contract와 하나 이상의 Task/Goal 완료 증거로 연결된다.
  • 모든 미결 항목에 결정 주체와 다음 행동이 있다.
  • 모든 외부 의존 항목에 담당 주체·영향·재개 조건이 있다.
  • 제외 항목에 Decision Log와 후속 조건이 있다.

15. Open Questions

ID 상태 결정 필요 사항 현재 권고 결정 주체 결정 기한/시점 영향 Goal
OQ-001 미결 <질문> <권고안 또는 없음> <역할> <날짜 또는 UI 작성 후> <Goal ID>
  • Open Question과 외부 의존을 혼합하지 않는다. 제품이 결정할 수 없는 backend 계약은 EXT-*로 관리한다.
  • 미결 값을 임의의 상수·enum·endpoint로 구현하지 않는다.

16. 요구사항 추적표

요구사항 범위 API Contract 계획 Phase Goal 자동 검증 수동 검증
DOMAINA-001~003 §<번호> 1 P1-T1, P1-T2, P1-GATE <test 경로> <흐름>
DOMAINB-001~002 §<번호 또는 제공 대기> 2 P2-T1, P2-T2, P2-GATE <test 경로> <흐름>

17. Decision Log

날짜 ID 상태 결정 근거 영향 요구사항·계약·Goal
YYYY-MM-DD DEC-001 확정 / 정정 / 폐기 <결정 내용> <인터뷰·계약·검증 근거> <ID와 문서 section>
  • 기존 결정을 수정할 때 원문을 지우지 않고 정정 행을 추가한다.
  • 범위 변경, Non-Goal 변경, 외부 의존 제외, 안전한 기본값과 주요 기술 선택을 기록한다.

18. 변경 관리

요구사항 변경 시 다음을 확인한다.

  • Decision Log에 변경 이유와 날짜를 기록했다.
  • 관련 요구사항 상태·본문·수용 기준을 갱신했다.
  • API Contract의 request/response/error와 fixture를 갱신했다.
  • plan-task.md의 범위·Files·Interfaces·체크박스·완료 증거를 코드 변경 전에 갱신했다.
  • 기존 Progress·review·검증 기록을 삭제하거나 덮어쓰지 않았다.