@su-record/vibe 2.4.56 → 2.4.57

package/vibe/rules/quality/bdd-contract-testing.md

@@ -1,66 +1,66 @@
 # BDD + Contract Testing Guide
 
-**AI 주도 개발에 최적화된 테스팅 전략**
+**Testing strategy optimized for AI-driven development**
 
 ---
 
-## 개요
+## Overview
 
-BDD (Behavior-Driven Development)와 Contract Testing은 **AI 에이전트가 요구사항을 정확히 이해하고 검증 가능한 코드를 생성**하는 데 필수적입니다.
+BDD (Behavior-Driven Development) and Contract Testing are essential for **AI agents to accurately understand requirements and generate verifiable code**.
 
-### 왜 AI 주도 개발에 유용한가?
+### Why is it useful for AI-driven development?
 
-1. **명확한 입출력 계약** → AI가 정확히 구현 가능
-2. **자동 검증** → AI 생성 코드의 품질 즉시 확인
-3. **회귀 방지** → AI 수정이 기존 기능을 깨뜨리지 않음
-4. **문서화 자동화** → 테스트가 곧 실행 가능한 명세
+1. **Clear input/output contracts** → AI can implement accurately
+2. **Automated verification** → Immediately verify AI-generated code quality
+3. **Regression prevention** → AI modifications don't break existing functionality
+4. **Automated documentation** → Tests serve as executable specifications
 
 ---
 
 ## Workflow
 
 ```
-SPEC 작성 (요구사항)
+Write SPEC (Requirements)
      ↓
-Feature 파일 생성 (Gherkin)
+Generate Feature file (Gherkin)
      ↓
-Contract 테스트 생성 (API 스키마)
+Generate Contract tests (API schema)
      ↓
-테스트 실행 (Red)
+Run tests (Red)
      ↓
-AI 에이전트 구현
+AI agent implementation
      ↓
-테스트 실행 (Green)
+Run tests (Green)
      ↓
-리팩토링
+Refactoring
      ↓
-테스트 재실행 (Green 유지)
+Run tests again (Stay Green)
 ```
 
 ---
 
 ## 1. BDD (Behavior-Driven Development)
 
-### Gherkin 문법
+### Gherkin Syntax
 
 ```gherkin
-Feature: 사용자 로그인
-  As a 사용자
-  I want to 로그인하고 싶다
-  So that 개인화된 서비스를 이용할 수 있다
-
-  Scenario: 유효한 credentials로 로그인 성공
-    Given 사용자가 "test@example.com"과 "password123"으로 등록되어 있다
-    When "test@example.com"과 "password123"으로 로그인을 시도한다
-    Then 로그인에 성공한다
-    And JWT 토큰을 받는다
-    And 홈 화면으로 리디렉션된다
-
-  Scenario: 잘못된 비밀번호로 로그인 실패
-    Given 사용자가 "test@example.com"으로 등록되어 있다
-    When "test@example.com"과 "wrong-password"로 로그인을 시도한다
-    Then 로그인에 실패한다
-    And "Invalid credentials" 에러 메시지를 받는다
+Feature: User Login
+  As a user
+  I want to login
+  So that I can access personalized services
+
+  Scenario: Successful login with valid credentials
+    Given user is registered with "test@example.com" and "password123"
+    When login is attempted with "test@example.com" and "password123"
+    Then login succeeds
+    And receives JWT token
+    And redirected to home screen
+
+  Scenario: Failed login with wrong password
+    Given user is registered with "test@example.com"
+    When login is attempted with "test@example.com" and "wrong-password"
+    Then login fails
+    And receives "Invalid credentials" error message
 ```
 
 ### Step Definitions (Python)
@@ -70,19 +70,19 @@ from pytest_bdd import scenarios, given, when, then, parsers
 
 scenarios('features/login.feature')
 
-@given(parsers.parse('사용자가 "{email}"과 "{password}"로 등록되어 있다'))
+@given(parsers.parse('user is registered with "{email}" and "{password}"'))
 def user_exists(context, email, password):
     context.user = create_user(email=email, password=password)
 
-@when(parsers.parse('"{email}"과 "{password}"로 로그인을 시도한다'))
+@when(parsers.parse('login is attempted with "{email}" and "{password}"'))
 def attempt_login(context, email, password):
     context.response = login(email=email, password=password)
 
-@then('로그인에 성공한다')
+@then('login succeeds')
 def login_succeeds(context):
     assert context.response.status_code == 200
 
-@then('JWT 토큰을 받는다')
+@then('receives JWT token')
 def receives_token(context):
     assert 'access_token' in context.response.json()
 ```
@@ -91,7 +91,7 @@ def receives_token(context):
 
 ## 2. Contract Testing
 
-### API 계약 정의
+### API Contract Definition
 
 ```json
 {
@@ -118,7 +118,7 @@ def receives_token(context):
 }
 ```
 
-### Contract 테스트 (Python)
+### Contract Test (Python)
 
 ```python
 import pytest
@@ -143,7 +143,7 @@ RESPONSE_SCHEMA = {
 }
 
 def test_login_response_contract():
-    """로그인 응답이 계약을 준수하는지 검증"""
+    """Verify login response adheres to contract"""
     response = client.post("/api/auth/login", json={
         "email": "test@example.com",
         "password": "password123"
@@ -151,56 +151,60 @@ def test_login_response_contract():
 
     assert response.status_code == 200
 
-    # 응답 스키마 검증
+    # Validate response schema
     validate(instance=response.json(), schema=RESPONSE_SCHEMA)
 
-    # JWT 토큰 형식 검증
+    # Validate JWT token format
     token = response.json()["access_token"]
-    assert len(token.split('.')) == 3  # JWT는 3개 부분으로 구성
+    assert len(token.split('.')) == 3  # JWT has 3 parts
 ```
 
 ---
 
-## 3. AI 에이전트 활용
+## 3. AI Agent Utilization
 
-### SPEC → Feature 자동 생성
+### SPEC → Feature Auto-generation
 
-AI 에이전트가 SPEC의 Acceptance Criteria를 Gherkin Scenario로 자동 변환:
+AI agent automatically converts SPEC Acceptance Criteria to Gherkin Scenarios:
 
 **SPEC**:
+
 ```markdown
-### REQ-001: 사용자 로그인
-**WHEN** 유효한 credentials로 로그인
-**THEN** JWT 토큰을 받는다
+### REQ-001: User Login
+**WHEN** login with valid credentials
+**THEN** receive JWT token
 
 #### Acceptance Criteria
-- [ ] 이메일과 비밀번호로 로그인 가능
-- [ ] access_token과 refresh_token 반환
-- [ ] 잘못된 credentials는 400 에러
+- [ ] Login with email and password
+- [ ] Return access_token and refresh_token
+- [ ] Invalid credentials return 400 error
 ```
 
 **Generated Feature**:
+
 ```gherkin
-Scenario: 유효한 credentials로 로그인 성공
-  Given 사용자가 등록되어 있다
-  When 유효한 이메일과 비밀번호로 로그인한다
-  Then JWT access_token을 받는다
-  And JWT refresh_token을 받는다
+Scenario: Successful login with valid credentials
+  Given user is registered
+  When login with valid email and password
+  Then receive JWT access_token
+  And receive JWT refresh_token
 ```
 
-### API 스키마 → Contract 자동 생성
+### API Schema → Contract Auto-generation
 
-AI 에이전트가 SPEC의 API 계약을 Contract 테스트로 자동 변환:
+AI agent automatically converts SPEC API contracts to Contract tests:
 
 **SPEC**:
+
 ```markdown
-### Endpoint: 로그인
+### Endpoint: Login
 POST /api/auth/login
 Request: { email, password }
 Response: { access_token, refresh_token, user }
 ```
 
 **Generated Contract Test**:
+
 ```python
 def test_login_contract():
     response = client.post("/api/auth/login", json=valid_credentials)
@@ -210,34 +214,34 @@ def test_login_contract():
 
 ---
 
-## 4. Vibe 명령어
+## 4. Vibe Commands
 
-### Feature 파일 생성
+### Generate Feature File
 
 ```bash
 vibe feature "user login"
-# → .claude/vibe/features/user-login.feature 생성
+# → Creates .claude/vibe/features/user-login.feature
 ```
 
-### Contract 테스트 생성
+### Generate Contract Test
 
 ```bash
 vibe contract "user login"
-# → tests/contract/test_user_login_contract.py 생성
+# → Creates tests/contract/test_user_login_contract.py
 ```
 
-### 테스트 실행
+### Run Tests
 
 ```bash
 vibe test "user login"
-# → BDD + Contract 테스트 실행
+# → Runs BDD + Contract tests
 ```
 
-### 검증
+### Verify
 
 ```bash
 vibe verify "user login"
-# → SPEC Acceptance Criteria 100% 충족 확인
+# → Confirms 100% SPEC Acceptance Criteria met
 ```
 
 ---
@@ -246,18 +250,18 @@ vibe verify "user login"
 
 ### ✅ DO
 
-1. **SPEC 먼저 작성** → Feature → Contract → 구현
-2. **Given-When-Then** 명확히 분리
-3. **계약은 구체적으로** (타입, 형식, 제약 명시)
-4. **독립적인 시나리오** (순서 무관하게 실행 가능)
-5. **에러 케이스 포함** (Happy path + Sad path)
+1. **Write SPEC first** → Feature → Contract → Implementation
+2. **Clearly separate Given-When-Then**
+3. **Be specific with contracts** (specify types, formats, constraints)
+4. **Independent scenarios** (can run in any order)
+5. **Include error cases** (Happy path + Sad path)
 
 ### ❌ DON'T
 
-1. **구현 세부사항 노출 금지** (Step Definitions에만 위치)
-2. **UI 테스트와 혼동 금지** (BDD는 비즈니스 로직)
-3. **과도한 Background 금지** (중복 제거만)
-4. **계약 위반 허용 금지** (스키마 변경 시 버전 업)
+1. **Don't expose implementation details** (keep in Step Definitions only)
+2. **Don't confuse with UI testing** (BDD is for business logic)
+3. **Don't overuse Background** (only for deduplication)
+4. **Don't allow contract violations** (version up on schema changes)
 
 ---
 
@@ -305,7 +309,7 @@ jobs:
 ### Python (FastAPI)
 
 ```bash
-# 프로젝트 구조
+# Project structure
 project/
 ├── tests/
 │   ├── features/          # Gherkin feature files
@@ -319,7 +323,7 @@ project/
 ### Flutter (Dart)
 
 ```bash
-# 프로젝트 구조
+# Project structure
 project/
 ├── integration_test/
 │   ├── features/          # Gherkin feature files
@@ -334,7 +338,7 @@ project/
 ### React (TypeScript)
 
 ```bash
-# 프로젝트 구조
+# Project structure
 project/
 ├── tests/
 │   ├── features/          # Gherkin feature files
@@ -373,16 +377,17 @@ project/
 
 ## Summary
 
-BDD + Contract Testing은 **AI 에이전트가 SPEC을 정확히 구현하고 자동 검증**할 수 있게 합니다:
+BDD + Contract Testing enables **AI agents to accurately implement SPECs and automatically verify**:
+
+1. **Clear requirements** → Express business language with Gherkin
+2. **Contract-based development** → Independent Frontend/Backend development with API schema
+3. **Automated verification** → Immediately verify AI-generated code quality
+4. **Regression prevention** → Protect existing functionality
 
-1. **명확한 요구사항** → Gherkin으로 비즈니스 언어 표현
-2. **계약 기반 개발** → API 스키마로 Frontend/Backend 독립 개발
-3. **자동화된 검증** → AI 생성 코드 품질 즉시 확인
-4. **회귀 방지** → 기존 기능 보호
+**Usage in Vibe**:
 
-**Vibe에서 사용**:
 ```bash
 vibe spec "feature" → vibe feature "feature" → vibe contract "feature" → vibe run
 ```
 
-**Test-First → AI 구현 → Verify → Done** 🎉
+**Test-First → AI Implementation → Verify → Done** 🎉