@su-record/vibe 0.4.6 → 0.4.7

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

@@ -0,0 +1,388 @@
+# BDD + Contract Testing Guide
+
+**AI 주도 개발에 최적화된 테스팅 전략**
+
+---
+
+## 개요
+
+BDD (Behavior-Driven Development)와 Contract Testing은 **AI 에이전트가 요구사항을 정확히 이해하고 검증 가능한 코드를 생성**하는 데 필수적입니다.
+
+### 왜 AI 주도 개발에 유용한가?
+
+1. **명확한 입출력 계약** → AI가 정확히 구현 가능
+2. **자동 검증** → AI 생성 코드의 품질 즉시 확인
+3. **회귀 방지** → AI 수정이 기존 기능을 깨뜨리지 않음
+4. **문서화 자동화** → 테스트가 곧 실행 가능한 명세
+
+---
+
+## Workflow
+
+```
+SPEC 작성 (요구사항)
+     ↓
+Feature 파일 생성 (Gherkin)
+     ↓
+Contract 테스트 생성 (API 스키마)
+     ↓
+테스트 실행 (Red)
+     ↓
+AI 에이전트 구현
+     ↓
+테스트 실행 (Green)
+     ↓
+리팩토링
+     ↓
+테스트 재실행 (Green 유지)
+```
+
+---
+
+## 1. BDD (Behavior-Driven Development)
+
+### Gherkin 문법
+
+```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" 에러 메시지를 받는다
+```
+
+### Step Definitions (Python)
+
+```python
+from pytest_bdd import scenarios, given, when, then, parsers
+
+scenarios('features/login.feature')
+
+@given(parsers.parse('사용자가 "{email}"과 "{password}"로 등록되어 있다'))
+def user_exists(context, email, password):
+    context.user = create_user(email=email, password=password)
+
+@when(parsers.parse('"{email}"과 "{password}"로 로그인을 시도한다'))
+def attempt_login(context, email, password):
+    context.response = login(email=email, password=password)
+
+@then('로그인에 성공한다')
+def login_succeeds(context):
+    assert context.response.status_code == 200
+
+@then('JWT 토큰을 받는다')
+def receives_token(context):
+    assert 'access_token' in context.response.json()
+```
+
+---
+
+## 2. Contract Testing
+
+### API 계약 정의
+
+```json
+{
+  "request": {
+    "method": "POST",
+    "path": "/api/auth/login",
+    "body": {
+      "email": "string (email format)",
+      "password": "string (min 8 chars)"
+    }
+  },
+  "response": {
+    "status": 200,
+    "body": {
+      "access_token": "string (JWT)",
+      "refresh_token": "string (JWT)",
+      "user": {
+        "id": "uuid",
+        "email": "string",
+        "name": "string"
+      }
+    }
+  }
+}
+```
+
+### Contract 테스트 (Python)
+
+```python
+import pytest
+from jsonschema import validate
+
+RESPONSE_SCHEMA = {
+    "type": "object",
+    "required": ["access_token", "refresh_token", "user"],
+    "properties": {
+        "access_token": {"type": "string", "pattern": "^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+$"},
+        "refresh_token": {"type": "string"},
+        "user": {
+            "type": "object",
+            "required": ["id", "email", "name"],
+            "properties": {
+                "id": {"type": "string", "format": "uuid"},
+                "email": {"type": "string", "format": "email"},
+                "name": {"type": "string"}
+            }
+        }
+    }
+}
+
+def test_login_response_contract():
+    """로그인 응답이 계약을 준수하는지 검증"""
+    response = client.post("/api/auth/login", json={
+        "email": "test@example.com",
+        "password": "password123"
+    })
+
+    assert response.status_code == 200
+
+    # 응답 스키마 검증
+    validate(instance=response.json(), schema=RESPONSE_SCHEMA)
+
+    # JWT 토큰 형식 검증
+    token = response.json()["access_token"]
+    assert len(token.split('.')) == 3  # JWT는 3개 부분으로 구성
+```
+
+---
+
+## 3. AI 에이전트 활용
+
+### SPEC → Feature 자동 생성
+
+AI 에이전트가 SPEC의 Acceptance Criteria를 Gherkin Scenario로 자동 변환:
+
+**SPEC**:
+```markdown
+### REQ-001: 사용자 로그인
+**WHEN** 유효한 credentials로 로그인
+**THEN** JWT 토큰을 받는다
+
+#### Acceptance Criteria
+- [ ] 이메일과 비밀번호로 로그인 가능
+- [ ] access_token과 refresh_token 반환
+- [ ] 잘못된 credentials는 400 에러
+```
+
+**Generated Feature**:
+```gherkin
+Scenario: 유효한 credentials로 로그인 성공
+  Given 사용자가 등록되어 있다
+  When 유효한 이메일과 비밀번호로 로그인한다
+  Then JWT access_token을 받는다
+  And JWT refresh_token을 받는다
+```
+
+### API 스키마 → Contract 자동 생성
+
+AI 에이전트가 SPEC의 API 계약을 Contract 테스트로 자동 변환:
+
+**SPEC**:
+```markdown
+### Endpoint: 로그인
+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)
+    assert response.status_code == 200
+    validate(response.json(), LOGIN_RESPONSE_SCHEMA)
+```
+
+---
+
+## 4. Vibe 명령어
+
+### Feature 파일 생성
+
+```bash
+vibe feature "user login"
+# → .vibe/features/user-login.feature 생성
+```
+
+### Contract 테스트 생성
+
+```bash
+vibe contract "user login"
+# → tests/contract/test_user_login_contract.py 생성
+```
+
+### 테스트 실행
+
+```bash
+vibe test "user login"
+# → BDD + Contract 테스트 실행
+```
+
+### 검증
+
+```bash
+vibe verify "user login"
+# → SPEC Acceptance Criteria 100% 충족 확인
+```
+
+---
+
+## 5. Best Practices
+
+### ✅ DO
+
+1. **SPEC 먼저 작성** → Feature → Contract → 구현
+2. **Given-When-Then** 명확히 분리
+3. **계약은 구체적으로** (타입, 형식, 제약 명시)
+4. **독립적인 시나리오** (순서 무관하게 실행 가능)
+5. **에러 케이스 포함** (Happy path + Sad path)
+
+### ❌ DON'T
+
+1. **구현 세부사항 노출 금지** (Step Definitions에만 위치)
+2. **UI 테스트와 혼동 금지** (BDD는 비즈니스 로직)
+3. **과도한 Background 금지** (중복 제거만)
+4. **계약 위반 허용 금지** (스키마 변경 시 버전 업)
+
+---
+
+## 6. Coverage Mapping
+
+| SPEC REQ | Feature Scenario | Contract Test | Implementation | Status |
+|----------|------------------|---------------|----------------|--------|
+| REQ-001 | ✅ Scenario 1, 2 | ✅ test_login_contract | ✅ POST /api/auth/login | ✅ |
+| REQ-002 | ✅ Scenario 3 | ✅ test_refresh_contract | ⬜ POST /api/auth/refresh | ⬜ |
+
+**Coverage**: 1 / 2 (50%)
+
+---
+
+## 7. CI/CD Integration
+
+```yaml
+# .github/workflows/test.yml
+name: BDD + Contract Tests
+
+on: [pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Run BDD tests
+        run: pytest tests/features/ -v --gherkin-terminal-reporter
+
+      - name: Run Contract tests
+        run: pytest tests/contract/ -v
+
+      - name: Upload coverage
+        run: |
+          pytest --cov=app --cov-report=xml
+          codecov -f coverage.xml
+```
+
+---
+
+## 8. Examples
+
+### Python (FastAPI)
+
+```bash
+# 프로젝트 구조
+project/
+├── tests/
+│   ├── features/          # Gherkin feature files
+│   │   └── login.feature
+│   ├── step_defs/         # Step definitions
+│   │   └── test_login.py
+│   └── contract/          # Contract tests
+│       └── test_login_contract.py
+```
+
+### Flutter (Dart)
+
+```bash
+# 프로젝트 구조
+project/
+├── integration_test/
+│   ├── features/          # Gherkin feature files
+│   │   └── login.feature
+│   └── step_definitions/  # Step definitions
+│       └── login_test.dart
+└── test/
+    └── contract/          # Contract tests
+        └── login_contract_test.dart
+```
+
+### React (TypeScript)
+
+```bash
+# 프로젝트 구조
+project/
+├── tests/
+│   ├── features/          # Gherkin feature files
+│   │   └── login.feature
+│   ├── steps/             # Step definitions
+│   │   └── login.steps.ts
+│   └── contract/          # Contract tests
+│       └── login.contract.test.ts
+```
+
+---
+
+## 9. Tools & Frameworks
+
+### BDD
+
+| Language | Framework |
+|----------|-----------|
+| Python | pytest-bdd, behave |
+| JavaScript | Cucumber.js, Jest-Cucumber |
+| TypeScript | Cucumber.js, Playwright |
+| Dart | flutter_gherkin |
+| Java | Cucumber-JVM |
+| Ruby | Cucumber |
+
+### Contract Testing
+
+| Type | Framework |
+|------|-----------|
+| Consumer-Driven | Pact, Spring Cloud Contract |
+| Provider | Postman, Dredd |
+| Schema Validation | JSON Schema, Zod, Ajv |
+| Mock Server | MSW, WireMock, http-mock-adapter |
+
+---
+
+## Summary
+
+BDD + Contract Testing은 **AI 에이전트가 SPEC을 정확히 구현하고 자동 검증**할 수 있게 합니다:
+
+1. **명확한 요구사항** → Gherkin으로 비즈니스 언어 표현
+2. **계약 기반 개발** → API 스키마로 Frontend/Backend 독립 개발
+3. **자동화된 검증** → AI 생성 코드 품질 즉시 확인
+4. **회귀 방지** → 기존 기능 보호
+
+**Vibe에서 사용**:
+```bash
+vibe spec "feature" → vibe feature "feature" → vibe contract "feature" → vibe run
+```
+
+**Test-First → AI 구현 → Verify → Done** 🎉

package/.vibe/rules/quality/checklist.md

@@ -0,0 +1,276 @@
+# ✅ 최종 검증 체크리스트
+
+## 5.1 향상된 코드 품질 체크
+
+### 최우선 순위
+
+```typescript
+const topPriority = {
+  obeysTheGoldenRule: true,      // ✅ 요청 범위만 수정
+  preservesWorkingCode: true,    // ✅ 기존 코드 보존
+  respectsExistingStyle: true,   // ✅ 기존 스타일 유지
+};
+```
+
+### 타입 안전성
+
+```typescript
+const typeSafety = {
+  noAnyType: true,               // ✅ any 타입 사용 금지
+  strictNullCheck: true,         // ✅ null/undefined 체크
+  properTypeGuards: true,        // ✅ 타입 가드 사용
+  genericTypesWhenNeeded: true,  // ✅ 제네릭 타입 활용
+};
+```
+
+### 코드 구조 & 복잡도
+
+```typescript
+const codeStructure = {
+  singleResponsibility: true,    // ✅ 단일 책임 원칙
+  functionUnder20Lines: true,    // ✅ 함수 20줄 이하
+  maxNesting3Levels: true,       // ✅ 최대 중첩 3단계
+  cyclomaticComplexity: 10,      // ✅ 순환 복잡도 ≤ 10
+  cognitiveComplexity: 15,       // ✅ 인지 복잡도 ≤ 15
+  maxParameters: 5,              // ✅ 매개변수 최대 5개
+  componentUnder50Lines: true,   // ✅ 컴포넌트 JSX 50줄 이하
+};
+```
+
+### Halstead 메트릭
+
+```typescript
+const halsteadMetrics = {
+  vocabulary: true,              // ✅ 연산자/피연산자 다양성
+  difficulty: true,              // ✅ 코드 이해 난이도
+  effort: true,                  // ✅ 정신적 노력
+  lowComplexity: true,           // ✅ 낮은 복잡도 유지
+};
+```
+
+### 결합도 & 응집도
+
+```typescript
+const couplingCohesion = {
+  looseCoupling: true,           // ✅ 느슨한 결합 (≤ 7 dependencies)
+  highCohesion: true,            // ✅ 높은 응집도 (관련 기능만 모음)
+  noCircularDeps: true,          // ✅ 순환 의존성 없음
+  dependencyInjection: true,     // ✅ 의존성 주입 패턴
+};
+```
+
+### 에러 처리
+
+```typescript
+const errorHandling = {
+  hasErrorHandling: true,        // ✅ try-catch/error state
+  hasLoadingState: true,         // ✅ 로딩 상태
+  hasFallbackUI: true,           // ✅ 폴백 UI
+  properErrorMessages: true,     // ✅ 명확한 에러 메시지
+  errorBoundaries: true,         // ✅ Error Boundary 사용
+};
+```
+
+### 접근성 (Accessibility)
+
+```typescript
+const accessibility = {
+  hasAriaLabels: true,           // ✅ ARIA 레이블
+  keyboardAccessible: true,      // ✅ 키보드 접근성
+  semanticHTML: true,            // ✅ 시맨틱 HTML
+  focusManagement: true,         // ✅ 포커스 관리
+  screenReaderFriendly: true,    // ✅ 스크린 리더 지원
+};
+```
+
+### 성능
+
+```typescript
+const performance = {
+  noUnnecessaryRenders: true,    // ✅ 불필요한 리렌더 방지
+  memoizedExpensive: true,       // ✅ 무거운 연산 메모이제이션
+  lazyLoading: true,             // ✅ 지연 로딩
+  batchOperations: true,         // ✅ API 호출 배치 처리
+  optimizedImages: true,         // ✅ 이미지 최적화
+  codesplitting: true,           // ✅ 코드 스플리팅
+};
+```
+
+### 유지보수성
+
+```typescript
+const maintainability = {
+  hasJSDoc: true,                // ✅ 주요 함수 문서화
+  noMagicNumbers: true,          // ✅ 매직 넘버 없음
+  consistentNaming: true,        // ✅ 일관된 네이밍
+  properComments: true,          // ✅ 적절한 주석
+  testable: true,                // ✅ 테스트 가능한 구조
+};
+```
+
+### 보안
+
+```typescript
+const security = {
+  noHardcodedSecrets: true,      // ✅ 비밀 정보 하드코딩 금지
+  inputValidation: true,         // ✅ 입력값 검증
+  xssPrevention: true,           // ✅ XSS 방지
+  csrfProtection: true,          // ✅ CSRF 보호
+  sqlInjectionPrevention: true,  // ✅ SQL Injection 방지
+};
+```
+
+## 5.2 프로젝트 체크
+
+### 의존성 관리
+
+```typescript
+const dependencies = {
+  noUnusedDeps: true,            // ✅ 미사용 패키지 없음
+  noDuplicateDeps: true,         // ✅ 중복 기능 패키지 없음
+  upToDateDeps: true,            // ✅ 최신 버전 유지
+  securePackages: true,          // ✅ 보안 취약점 없음
+};
+```
+
+### 파일 구조
+
+```typescript
+const fileStructure = {
+  consistentStructure: true,     // ✅ 일관된 폴더 구조
+  noCircularDeps: true,          // ✅ 순환 참조 없음
+  logicalGrouping: true,         // ✅ 논리적 그룹핑
+  clearNaming: true,             // ✅ 명확한 파일명
+};
+```
+
+### 번들 최적화
+
+```typescript
+const bundleOptimization = {
+  treeShaking: true,             // ✅ Tree shaking
+  codeSplitting: true,           // ✅ Code splitting
+  lazyLoading: true,             // ✅ Lazy loading
+  minification: true,            // ✅ 최소화
+  compression: true,             // ✅ 압축 (gzip/brotli)
+};
+```
+
+## 체크리스트 사용법
+
+### 코드 작성 전
+
+```
+[ ] 요구사항 명확히 이해
+[ ] 기존 코드 패턴 파악
+[ ] 영향 범위 확인
+[ ] 테스트 계획 수립
+```
+
+### 코드 작성 중
+
+```
+[ ] 단일 책임 원칙 준수
+[ ] 함수 길이 20줄 이하 유지
+[ ] 중첩 깊이 3단계 이하
+[ ] 매직 넘버 상수화
+[ ] 타입 안전성 확보
+```
+
+### 코드 작성 후
+
+```
+[ ] 타입 체크 통과
+[ ] 린터 경고 없음
+[ ] 테스트 작성 및 통과
+[ ] 문서화 완료
+[ ] 코드 리뷰 준비
+```
+
+### 커밋 전
+
+```
+[ ] 불필요한 코드 제거
+[ ] 콘솔 로그 제거
+[ ] 주석 정리
+[ ] 포맷팅 적용
+[ ] 의미 있는 커밋 메시지 작성
+```
+
+## 자동 검증 도구
+
+### ESLint 설정
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  rules: {
+    'complexity': ['error', 10],
+    'max-depth': ['error', 3],
+    'max-lines-per-function': ['error', 20],
+    'max-params': ['error', 5],
+    'no-magic-numbers': ['warn', { ignore: [0, 1, -1] }],
+    '@typescript-eslint/no-explicit-any': 'error',
+  },
+};
+```
+
+### TypeScript 설정
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+  }
+}
+```
+
+### Git Hooks (pre-commit)
+
+```bash
+#!/bin/sh
+# .husky/pre-commit
+
+# 타입 체크
+npm run type-check
+
+# 린팅
+npm run lint
+
+# 테스트
+npm run test
+
+# 포맷팅 확인
+npm run format:check
+```
+
+## 등급 기준
+
+| 등급 | 점수 | 설명 |
+|------|------|------|
+| A+ | 95-100 | 완벽한 코드 품질 |
+| A | 90-94 | 우수한 품질 |
+| B+ | 85-89 | 양호한 품질 |
+| B | 80-84 | 개선 권장 |
+| C+ | 75-79 | 개선 필요 |
+| C | 70-74 | 즉시 개선 필요 |
+| F | < 70 | 리팩토링 필요 |
+
+## 빠른 체크 (1분)
+
+```
+✅ 요청 범위만 수정했는가?
+✅ any 타입이 없는가?
+✅ 함수가 20줄 이하인가?
+✅ 중첩이 3단계 이하인가?
+✅ 에러 처리를 했는가?
+✅ 매직 넘버를 상수화했는가?
+✅ 테스트를 작성했는가?
+```
+
+7개 모두 Yes → 배포 가능 ✅