bdd-practices

name	bdd-practices
description	Gherkin 기반 BDD와 기능 명세를 지원합니다. "bdd", "명세", ".feature", "시나리오", "Given/When/Then" 요청 시 사용하세요.

BDD Practices

Gherkin 형식으로 기능을 명세하고, 선택적으로 자동화 테스트로 연결합니다.

핵심 철학:

• Feature First: .feature 명세 먼저, 구현 나중
• Specification by Example: 추상적 요구사항 대신 구체적 시나리오
• Living Documentation: .feature = 실행 가능한 문서 (자동화 없이도 가치 있음)

.feature 파일의 가치

.feature 파일 자체가:

• 요구사항 명세서 - Given/When/Then으로 구조화
• 인수 조건 (Acceptance Criteria) - 완료 기준 명확화
• 엣지 케이스 문서 - 예외 상황 정리
• 팀 커뮤니케이션 도구 - 비개발자도 읽을 수 있음

자동화 없이 명세로만 사용해도 충분한 가치가 있습니다.

Phase 1: Discovery (발견)

새 기능이나 요구사항 논의 시:

1. 요구사항 파악

   • 사용자가 요청한 기능을 명확히 이해
   • 모호한 부분은 사용자에게 질문

2. Example Mapping

   • 규칙(Rules)과 예시(Examples) 도출
   • 엣지 케이스 식별
   • 질문 목록 작성

3. 시나리오 목록 작성

   • 핵심 시나리오 나열 (Happy Path)
   • 예외 시나리오 나열 (Edge Cases)
   • 우선순위 기준:
     1. Happy Path (정상 플로우) - 가장 먼저
     2. 가장 흔한 예외 케이스
     3. 비즈니스 크리티컬 케이스
     4. 엣지 케이스 - 나중에
   • 예: "다음 시나리오들을 순서대로 진행하겠습니다: 1) 유효한 로그인, 2) 잘못된 비밀번호, 3) 존재하지 않는 사용자"

4. 사용자 확인

   • 시나리오 목록 보여주기
   • 누락된 케이스 확인

5. Phase 2로 진행

---

Phase 2: Formulation (명세화)

시나리오를 Gherkin 형식으로 작성:

1. 파일 위치 결정

   • 프로젝트 내 features/ 디렉토리 (권장)
   • 기존 .feature 파일이 있는지 확인
   • 사용자에게 확인

2. .feature 파일 작성

   Feature: 기능명
     기능에 대한 설명
   
     Scenario: 시나리오명
       Given 전제조건
       When 행동
       Then 결과
   

3. Gherkin 작성 원칙

   • 한 시나리오에 하나의 행동만
   • 구체적인 예시 데이터 사용
   • 구현 세부사항 노출 금지 (UI 요소, DB 쿼리 등)
   • 비즈니스 언어로 작성

4. 상세 문법: resources/01-gherkin-syntax.md 참조

5. 사용자 확인

   • 작성된 시나리오 보여주기
   • "이 시나리오가 요구사항을 정확히 반영하나요?"

6. living-docs 연계 (선택)

   • .feature는 living-docs의 요구사항 문서로 활용 가능
   • docs/requirements/ 또는 features/ 디렉토리에 배치 권장

7. Phase 3으로 진행

---

Phase 3: Automation (선택)

.feature를 자동화 테스트로 연결하려면:

1. 자동화 여부 확인

   • 명세만 필요한 경우 → Phase 2에서 완료
   • 자동화 테스트가 필요한 경우 → 아래 진행

2. 상세 가이드: resources/02-automation.md 참조

   • Step definitions 작성 (Python/JavaScript)
   • pytest-bdd, behave, cucumber-js 설정
   • RED → GREEN → REFACTOR 사이클

3. tdd-practices 연계

   • Step definition은 얇게 유지
   • 복잡한 내부 로직은 tdd-practices로 개발

---

AI Red Flags 🚨

다음 징후 발견 시 즉시 중단하고 사용자에게 보고:

• 🚨 .feature 없이 구현부터 시작

  • BDD는 명세 먼저, 구현 나중
  • "먼저 시나리오를 작성하겠습니다"

• 🚨 Step definition 없이 테스트 실행 시도

  • Step definition이 없으면 테스트 실행 불가
  • Phase 3 건너뛰기 금지

• 🚨 시나리오에 없는 기능 구현

  • .feature에 정의된 행동만 구현
  • 추가 기능은 새 시나리오로

• 🚨 구현 세부사항을 .feature에 노출

  • "버튼을 클릭한다" ❌
  • "로그인을 시도한다" ✅

---

tdd-practices 연계

BDD vs TDD:

• BDD: 시나리오 레벨 (.feature → Step definitions)
• TDD: 유닛 레벨 (테스트 → 함수/클래스)

연계 시점: 자동화 단계에서 복잡한 로직이 필요할 때

• Step definition은 얇게 유지
• 내부 로직은 tdd-practices의 RED-GREEN-REFACTOR로 개발

---

Examples

기능 명세 작성 (자동화 없음)

User: "주문 취소 기능 명세해줘"
→ Phase 1: 시나리오 도출
  - 배송 전 취소 → 전액 환불
  - 배송 중 취소 → 불가
  - 배송 완료 후 → 반품 절차
→ Phase 2: features/order-cancel.feature 생성
→ 완료 (명세 문서로 활용)

BDD 전체 플로우 (자동화 포함)

User: "로그인 기능 BDD로 구현해줘"
→ Phase 1-2: .feature 작성
→ Phase 3: resources/02-automation.md 참조
→ Step definitions + 구현

기존 .feature에 시나리오 추가

User: "비밀번호 찾기 시나리오 추가해줘"
→ Phase 1: 시나리오 도출
→ Phase 2: 기존 .feature에 추가

---

Technical Details

• Gherkin 상세 문법: resources/01-gherkin-syntax.md
• 자동화 가이드: resources/02-automation.md
• 템플릿: templates/crud.feature, templates/auth.feature
• 유닛 테스트 연계: tdd-practices