hgzero/claude/userstory-writing.md

유저스토리 작성 방법

개요

이 가이드는 마이크로서비스 기반 시스템 개발을 위한 유저스토리 작성 표준을 제공합니다.
표준화된 형식을 통해 일관성 있고 완전한 요구사항을 정의할 수 있습니다.

작성 구성 요소

1. 서비스

마이크로서비스명을 명시합니다.

• 형식: 서비스 도메인명
• 예시: 홈페이지, 가입설계, 주문관리, 결제처리

2. ID

User Story ID로서 표준화된 식별자입니다.

• 형식: <유저스토리 유형 코드>-<서비스약어>-<일련번호>
  • 유저스토리 유형 코드
    • UFR(User Functional Requirements): 사용자 기능 요구사항
    • AFR(Admin Functional Requirements): 어드민 기능 요구사항
    • NFR(Non Functiional Requirements): 비기능 요구사항(확장성, 회복성, 유연성, 성능, 보안, 운영성)
  • 서비스약어: 3~4자로 작성
  • 일련번호: 3자리로 하고 010부터 시작하여 10개씩 증가 예) UFR-HOME-010, UFR-HOME-020
• 예시:
  • UFR-HOME-010: 홈페이지 서비스의 첫 번째 유저스토리
  • UFR-PAY-020: 결제 서비스의 다섯 번째 유저스토리

3. Epic

유저스토리의 상위 카테고리를 분류합니다.

• 용도: 관련 유저스토리들을 그룹화
• 예시: 사용자 관리, 상품 관리, 주문 처리

4. 유저스토리

표준 형식에 따라 작성합니다. 각 파트는 파이프로 구분합니다.

• 형식: [유저스토리 제목] <유저유형>으로서 | 나는, <비즈니스 목적>을 위해 | <작업/기능>을(를) 원합니다.
• 예시:
  • [상품검색] 쇼핑몰 고객으로서 | 나는, 상품을 쉽게 찾기 위해 | 카테고리별 상품 검색 기능을 원합니다.
  • [주문현황] 관리자로서 | 나는, 주문 상태를 파악하기 위해 | 실시간 주문 현황 대시보드를 원합니다.

중요) 유저유형은 사람 뿐 아니라 시스템, API 등으로 정의할 수도 있음

• 이벤트 스토밍은 사용자 중심으로 수행하기 위해 사람만 Actor로 허용
• 유저스토리는 충분한 요구사항 전달을 위해 사람이 아닌 유저유형도 허용함

5. Biz중요도 (MoSCoW 분류)

우선순위에 따른 분류입니다.

분류	의미	설명
M (Must)	반드시 필요	핵심 비즈니스 기능, 없으면 서비스 불가능
S (Should)	매우 필요하나 대체할 방법은 있음	중요하지만 우회 방법이 존재
C (Could)	있으면 좋으나 우선 순위는 떨어짐 (Nice to have)	사용자 편의성 향상 기능
W (Won't)	가장 우선순위가 떨어지므로 보류해도 됨	향후 개발 고려 기능

6. 인수테스트 시나리오

기능 완성도를 검증하기 위한 테스트 시나리오입니다.

시나리오명

• 테스트할 기능이나 상황을 명확히 표현
• 예시: "정상적인 회원 가입 처리", "중복 이메일 가입 시도"

인수기준 (Given-When-Then 형식)

• 형식: <Given> | <When> | <Then>

  • Given (사전 조건/상황): 테스트 실행 전 준비사항
  • When (Action): 사용자가 수행하는 액션
  • Then (결과): 기대되는 결과 또는 시스템 반응

• 예시

미 로그인 상태로 서비스에 접근하여 | ID와 암호를 입력하여 로그인 요청을 하면 | 대시보드 페이지가 표시된다. 

체크리스트

세부 테스트 항목을 최대한 자세히 작성합니다.

• 기능/비기능 요구사항 검증 항목
• 예외 상황 처리 검증
• 통합 테스트 항목

7. Score

구현 난이도를 피보나치 수열을 이용하여 표현합니다.

• 수열: 1, 2, 3, 5, 8, 13, 21, 34, 55, 89...
• 기준:

점수	난이도	설명	세부 기준	예시
1-2	매우 간단	기본적인 CRUD 작업	• 단일 파일 수정 • 간단한 설정 변경 • 단순 명령어 실행	• README 작성 • 간단한 스크립트 실행 • 환경변수 설정
3-5	간단	기본 비즈니스 로직 포함	• 여러 파일 수정 • 간단한 테스트 작성 • 기본 에러 처리	• 설정 파일 파싱 • 간단한 데이터 변환 • 기본 유효성 검사
8-13	보통	복잡한 비즈니스 로직	• API 연동 • 데이터베이스 처리 • 복잡한 알고리즘 • 외부 도구 통합	• MCP 서버 연동 • 파일 시스템 조작 • CLI 인터페이스 개발
21-34	복잡	다중 시스템 연동	• 여러 서비스 통합 • 복잡한 상태 관리 • 성능 최적화 필요 • 보안 고려사항	• GitHub API 통합 • 실시간 모니터링 • 복잡한 워크플로우
55+	매우 복잡	새로운 기술/패러다임	• 신규 아키텍처 설계 • 혁신적 기능 개발 • 대규모 리팩토링 • 연구개발 요소	• 새로운 플러그인 아키텍처 • AI 모델 통합 • 분산 시스템 설계

결과 형식

• 코드블록 내에 작성함
• 구성

{서비스 일련번호}. {서비스명}
{Epic 일련번호}. {Epic}
{유저스토리 ID}: [{유저스토리 제목}]: {유저스토리}
- 시나리오: {시나리오}
  {인수기준}
  - {체크 리스트}
- {Biz중요도}/{Score}

작성예시

1. User 서비스
1) 사용자 인증 및 관리
RQ-USER-010: [회원가입] 사용자로서 | 나는, 여행 계획을 관리하기 위해 | 간편하게 회원가입하고 싶다.
- 시나리오: 회원가입 
  미 로그인 상태로 서비스에 접근한 상황에서 | 사용자 기본정보(이름, 이메일, 연락처), ID, 암호를 입력하여 회원가입 요청하면 | 회원가입이 된다.
  - [ ] 이름, 이메일, 연락처 등록 체크   
  - [ ] ID는 5자 이상의 영숫자 
  - [ ] 암호는 8자 이상의 영숫자와 특수문자가 최소 1개 이상 포함 
- M/5 

추가 항목

추가 항목은 필요 시 추가 가능합니다. 예를 들어 '기술 태스크'와 같은 기술적 내용을 추가할 수 있습니다. 예시)

UFR-AI-010: [AI일정생성] 여행자로서 | 나는 맞춤형 여행 일정을 받기 위해 | AI가 내 여행 정보와 이동수단 선호도를 기반으로 최적화된 일정을 생성하기를 원한다.
- 시나리오: AI 일정 생성 결과 확인
  여행 기본정보와 여행지를 설정하고 AI 일정 생성을 요청한 상황에서 | 5초 이내에 생성이 완료되면 | 선호 이동수단을 기반으로 한 시간대별 상세 일정이 생성되어 확인할 수 있다.
  
  [생성 결과 검증]
  - 모든 여행지에 대한 일정 존재
  - 각 일자별 시작/종료 시간 일치
  - ...
- M/8
- 기술 태스크
  - AI 서비스 API 구현
    - POST /ai/schedules/generate (일정 생성 요청)
    - GET /ai/schedules/{id}/status (진행 상태 조회)
    - GET /ai/schedules/{id} (생성된 일정 조회)
  - AI 모델 통합
    - Claude API 연동
    - 프롬프트 엔지니어링
    - 응답 파싱 및 구조화

참고 자료

• 유저스토리 작성 샘플

결과 파일

작성된 유저스토리는 다음 위치에 저장됩니다:

• 파일 경로: design/Userstory.md
• 형식: 마크다운 형식으로 모든 유저스토리를 포함

작성 시 주의사항

1. 명확성: 모호한 표현 대신 구체적이고 측정 가능한 표현 사용
2. 완전성: 모든 필수 구성 요소를 빠짐없이 작성
3. 추적성: ID를 통해 설계 문서와 연결 가능하도록 작성
4. 테스트 가능성: 인수테스트 시나리오가 실제 테스트로 실행 가능하도록 구체적으로 작성
5. 우선순위: MoSCoW 분류를 통해 개발 우선순위 명확화