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 (발견)

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

요구사항 파악
- 사용자가 요청한 기능을 명확히 이해
- 모호한 부분은 사용자에게 질문
Example Mapping
- 규칙(Rules)과 예시(Examples) 도출
- 엣지 케이스 식별
- 질문 목록 작성
시나리오 목록 작성
- 핵심 시나리오 나열 (Happy Path)
- 예외 시나리오 나열 (Edge Cases)
- 우선순위 기준:
  1. Happy Path (정상 플로우) - 가장 먼저
  2. 가장 흔한 예외 케이스
  3. 비즈니스 크리티컬 케이스
  4. 엣지 케이스 - 나중에
- 예: "다음 시나리오들을 순서대로 진행하겠습니다: 1) 유효한 로그인, 2) 잘못된 비밀번호, 3) 존재하지 않는 사용자"
사용자 확인
- 시나리오 목록 보여주기
- 누락된 케이스 확인
Phase 2로 진행

Phase 2: Formulation (명세화)

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

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

.feature 파일 작성

Feature: 기능명
  기능에 대한 설명

  Scenario: 시나리오명
    Given 전제조건
    When 행동
    Then 결과

Gherkin 작성 원칙
- 한 시나리오에 하나의 행동만
- 구체적인 예시 데이터 사용
- 구현 세부사항 노출 금지 (UI 요소, DB 쿼리 등)
- 비즈니스 언어로 작성
상세 문법: resources/01-gherkin-syntax.md 참조
사용자 확인
- 작성된 시나리오 보여주기
- "이 시나리오가 요구사항을 정확히 반영하나요?"
living-docs 연계 (선택)
- .feature는 living-docs의 요구사항 문서로 활용 가능
- docs/requirements/ 또는 features/ 디렉토리에 배치 권장
Phase 3으로 진행

Phase 3: Automation (선택)

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

자동화 여부 확인
- 명세만 필요한 경우 → Phase 2에서 완료
- 자동화 테스트가 필요한 경우 → 아래 진행
상세 가이드: resources/02-automation.md 참조
- Step definitions 작성 (Python/JavaScript)
- pytest-bdd, behave, cucumber-js 설정
- RED → GREEN → REFACTOR 사이클
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

bdd-practices

Install Skill

SKILL.md