main (항상 릴리즈 가능)
├── feature/us-123-recommendation-api (수명: 1-2일)
├── feature/us-124-websocket-updates (수명: 1-2일)
└── fix/recommendation-null-check (수명: 4시간)

// src/config/feature-flags.ts
export const FEATURE_FLAGS = {
  RECOMMENDATION_V2: process.env.FEATURE_RECOMMENDATION_V2 === 'true',
  WEBSOCKET_REAL_TIME: process.env.FEATURE_WEBSOCKET === 'true',
} as const;

// 컴포넌트에서 사용
function HomePage() {
  return (
    <div>
      {FEATURE_FLAGS.RECOMMENDATION_V2 && <RecommendationSection />}
      <ProductList />
    </div>
  );
}

# .git/config 또는 팀 공유 설정
[branch "main"]
  # main 브랜치에 직접 푸시 금지
  # GitHub Branch Protection Rules로 설정

# 권장 워크플로우
git checkout -b feature/us-123-recommendation-api
# Claude와 함께 개발 (여러 작은 커밋)
git commit -m "feat(recommendation): add purchase history query"
git commit -m "test(recommendation): add unit tests for recommendation service"
git commit -m "feat(recommendation): add recommendation API endpoint"
# PR 생성 → CI 통과 → 코드 리뷰 → 머지

type(scope): description

[optional body]

[optional footer(s)]

feat(recommendation): add purchase history based product recommendations

- Implement collaborative filtering algorithm
- Add RecommendationService with top-10 product selection
- Exclude already purchased products from recommendations

Closes #123

# conventional-changelog 설치
npm install --save-dev @commitlint/cli @commitlint/config-conventional
npm install --save-dev conventional-changelog-cli

# .commitlintrc.json
{
  "extends": ["@commitlint/config-conventional"]
}

# package.json scripts
{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
    "release": "standard-version"
  }
}

# Changelog

## [1.3.0] - 2026-03-17

### Features

- **recommendation:** add purchase history based product recommendations

### Bug Fixes

- **cart:** fix quantity update when adding duplicate items

### Performance

- **recommendation:** add Redis caching for recommendation results

# .github/workflows/ai-code-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get PR diff
        id: diff
        run: |
          git diff origin/main...HEAD > pr_diff.txt
          echo "diff_size=$(wc -l < pr_diff.txt)" >> $GITHUB_OUTPUT

      - name: AI Review with Claude API
        if: steps.diff.outputs.diff_size < 1000
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # Claude API 호출 스크립트
          node scripts/ai-review.js

# GitHub CLI로 설정
gh api repos/OWNER/REPO/branches/main/protection \
--method PUT \
--field required_status_checks='{"strict":true,"contexts":["ci/build","ci/test","ci/lint"]}' \
--field enforce_admins=true \
--field required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \
--field restrictions=null

# .github/CODEOWNERS
# 핵심 아키텍처 파일
/src/core/ @senior-dev @tech-lead
/src/domain/ @domain-expert

# 보안 관련
/src/auth/ @security-team
*.env* @security-team

# CI/CD 설정
/.github/ @devops-team
/docker/ @devops-team

# .github/workflows/ci-cd.yml
name: CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  NODE_VERSION: '20'
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  # ─── CI 단계 ───────────────────────────────────────────

  lint:
    name: Lint & Format Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm run format:check

  type-check:
    name: TypeScript Type Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm run type-check

  test-unit:
    name: Unit Tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm run test:unit -- --coverage
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          flags: unit

  test-integration:
    name: Integration Tests
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: testpassword
          POSTGRES_DB: testdb
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
      redis:
        image: redis:7
        ports:
          - 6379:6379
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm run test:integration
        env:
          DATABASE_URL: postgresql://postgres:testpassword@localhost:5432/testdb
          REDIS_URL: redis://localhost:6379

  security-scan:
    name: Security Scan
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          scan-ref: '.'
          format: 'sarif'
          output: 'trivy-results.sarif'
      - name: Upload Trivy scan results
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: 'trivy-results.sarif'
      - name: npm audit
        run: npm audit --audit-level=high

  mutation-test:
    name: Mutation Testing
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npx stryker run
      - name: Comment mutation score on PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = JSON.parse(fs.readFileSync('reports/mutation/mutation.json'));
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Mutation Score: ${report.metrics.mutationScore.toFixed(1)}%`
            });

  # ─── CD 단계 (main 브랜치만) ─────────────────────────

  build-image:
    name: Build & Push Docker Image
    runs-on: ubuntu-latest
    needs: [lint, type-check, test-unit, test-integration, security-scan]
    if: github.ref == 'refs/heads/main'
    outputs:
      image-digest: ${{ steps.build.outputs.digest }}
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build and push
        id: build
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

  deploy-staging:
    name: Deploy to Staging
    runs-on: ubuntu-latest
    needs: [build-image]
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Kubernetes Staging
        run: |
          kubectl set image deployment/app \
            app=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.build-image.outputs.image-digest }} \
            --namespace=staging
          kubectl rollout status deployment/app --namespace=staging

  deploy-production:
    name: Deploy to Production
    runs-on: ubuntu-latest
    needs: [deploy-staging]
    environment:
      name: production
      url: https://myapp.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Production
        run: |
          kubectl set image deployment/app \
            app=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.build-image.outputs.image-digest }} \
            --namespace=production
          kubectl rollout status deployment/app --namespace=production

.claude/
  commands/
    commit.md
    pr-description.md
    test.md
    review.md
    docs.md
    refactor.md
    security-check.md
    changelog.md

# commit

스테이징된 변경사항을 분석하여 Conventional Commits 규격의 커밋 메시지를 생성합니다.

## 규칙

- feat/fix/docs/style/refactor/test/chore/perf 타입 사용
- scope는 영향 받는 모듈/컴포넌트 (선택사항)
- 제목: 50자 이하, 현재형, 첫 글자 소문자
- 본문: 무엇을, 왜 변경했는지 설명
- BREAKING CHANGE 있으면 footer에 명시

## 출력 형식

# pr-description

현재 브랜치의 변경사항을 분석하여 PR 설명을 생성합니다.

## 출력 형식

### 변경 사항 요약

[1-3줄 요약]

### 작업 내용

- [ ] 구현 항목 1
- [ ] 구현 항목 2

### 테스트 방법

1. 단계별 테스트 방법

### 스크린샷 (UI 변경 시)

[여기에 스크린샷 추가]

### 관련 이슈

Closes #이슈번호

### 체크리스트

- [ ] 단위 테스트 작성 완료
- [ ] 통합 테스트 통과
- [ ] CLAUDE.md 규칙 준수
- [ ] 문서 업데이트 (필요 시)

# test

선택된 파일 또는 함수에 대한 포괄적인 테스트를 생성합니다.

## 포함 내용

1. 단위 테스트 (Jest/Vitest)
   - 정상 케이스
   - 엣지 케이스 (경계값, null, undefined)
   - 에러 케이스
2. 목(Mock) 설정
3. 속성 기반 테스트 (복잡한 비즈니스 로직)

## 규칙

- CLAUDE.md의 테스트 커버리지 목표 준수
- AAA 패턴 (Arrange/Act/Assert) 사용
- 테스트 설명은 한국어로 작성
- 비동기 테스트에 async/await 사용

# review

현재 변경사항 또는 지정된 파일에 대한 심층 코드 리뷰를 수행합니다.

## 리뷰 체크리스트

### 코드 품질

- [ ] SOLID 원칙 준수
- [ ] DRY 원칙 (중복 코드 없음)
- [ ] 함수/클래스 단일 책임
- [ ] 명명 규칙 (CLAUDE.md 기준)

### 보안

- [ ] SQL 인젝션 위험
- [ ] XSS 취약점
- [ ] 민감 정보 노출 (시크릿, PII)
- [ ] 인증/인가 검증

### 성능

- [ ] N+1 쿼리 문제
- [ ] 불필요한 재렌더링
- [ ] 메모리 누수 위험

### 테스트

- [ ] 테스트 커버리지 충분
- [ ] 엣지 케이스 커버

## 출력 형식

각 이슈: [Critical/Major/Minor] 설명 + 개선 코드 예시

# refactor

선택된 코드의 리팩토링 제안을 생성합니다.

## 분석 기준

1. Extract Method: 긴 함수를 의미 있는 함수로 분리
2. Extract Class: 단일 책임 원칙 위반 클래스 분리
3. Replace Conditional with Polymorphism: if/else 체인 제거
4. Introduce Parameter Object: 파라미터가 3개 이상인 함수
5. Remove Duplicate Code: 중복 로직 공통화

## 출력 형식

- 원본 코드 문제점 설명
- 리팩토링된 코드
- 변경 이유
- 추가 고려사항

# docs

선택된 코드의 문서를 생성합니다.

## 생성 항목

1. JSDoc/TSDoc 주석
2. README.md (모듈 또는 함수 설명)
3. API 문서 (OpenAPI/Swagger 형식)

## 규칙

- 한국어로 작성 (영어 기술 용어는 그대로)
- 예시 코드 포함
- 파라미터 타입과 의미 설명
- 반환값 설명
- 예외 상황 문서화

// eslint.config.js (ESLint v9 flat config)
import js from '@eslint/js'
import typescript from '@typescript-eslint/eslint-plugin'
import tsParser from '@typescript-eslint/parser'
import prettier from 'eslint-config-prettier'
import importPlugin from 'eslint-plugin-import'
import sonarjs from 'eslint-plugin-sonarjs'

export default [
  js.configs.recommended,
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        project: './tsconfig.json',
      },
    },
    plugins: {
      '@typescript-eslint': typescript,
      import: importPlugin,
      sonarjs: sonarjs,
    },
    rules: {
      // TypeScript 규칙
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/strict-null-checks': 'error',
      '@typescript-eslint/no-unused-vars': 'error',
      '@typescript-eslint/explicit-function-return-type': 'warn',

      // 복잡도 제한
      complexity: ['error', 10],
      'max-lines-per-function': ['warn', 30],
      'max-depth': ['error', 3],

      // SonarJS 코드 품질
      'sonarjs/no-duplicate-string': 'warn',
      'sonarjs/cognitive-complexity': ['error', 15],
      'sonarjs/no-identical-functions': 'error',

      // import 정렬
      'import/order': [
        'error',
        {
          groups: ['builtin', 'external', 'internal', 'parent', 'sibling'],
          'newlines-between': 'always',
        },
      ],
    },
  },
  prettier,
]

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

# .github/workflows/sonarqube.yml
name: SonarQube Analysis

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  sonar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run test:unit -- --coverage
      - name: SonarQube Scan
        uses: sonarsource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        with:
          args: >
            -Dsonar.projectKey=my-project
            -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info
            -Dsonar.qualitygate.wait=true

sonar.projectKey=my-ecommerce-platform
sonar.sources=src
sonar.tests=src
sonar.test.inclusions=**/*.spec.ts,**/*.test.ts
sonar.coverage.exclusions=**/*.spec.ts,**/*.test.ts,**/index.ts

# Quality Gate 기준
sonar.qualitygate.conditions=\
  new_coverage<80,\
  new_duplicated_lines_density>3,\
  new_blocker_violations>0,\
  new_critical_violations>0

// src/config/feature-flags.ts
import { z } from 'zod'

const featureFlagSchema = z.object({
  RECOMMENDATION_V2: z.boolean().default(false),
  WEBSOCKET_REAL_TIME: z.boolean().default(false),
  NEW_CHECKOUT_FLOW: z.boolean().default(false),
  AI_SEARCH: z.boolean().default(false),
})

function loadFeatureFlags() {
  return featureFlagSchema.parse({
    RECOMMENDATION_V2: process.env.FEATURE_RECOMMENDATION_V2 === 'true',
    WEBSOCKET_REAL_TIME: process.env.FEATURE_WEBSOCKET === 'true',
    NEW_CHECKOUT_FLOW: process.env.FEATURE_NEW_CHECKOUT === 'true',
    AI_SEARCH: process.env.FEATURE_AI_SEARCH === 'true',
  })
}

export const FEATURES = loadFeatureFlags()

src/
  modules/
    user/          # 팀원 A 담당
      domain/
      application/
      infrastructure/
      presentation/
    product/       # 팀원 B 담당
    order/         # 팀원 C 담당
    recommendation/ # 팀원 D 담당
  shared/          # 공용 코드 (변경 최소화)
    utils/
    types/
    errors/

머지 충돌이 발생했습니다. 두 변경사항을 분석하고 올바른 머지 방법을 제안해줘:

<<<<<<< HEAD (내 변경사항)
[코드 붙여넣기]
=======
[상대방 코드 붙여넣기]
>>>>>>> feature/recommendation

양쪽 변경의 의도를 파악하고 두 변경을 모두 보존하는 머지 결과를 생성해줘.

# 기술 부채 리뷰 프롬프트 (Sprint 종료 시)

다음 코드베이스를 분석하고 기술 부채를 식별해줘:
[변경된 파일 목록]

분석 항목:

1. 중복 코드 (DRY 위반)
2. 과도한 복잡도 (순환 복잡도 10 이상)
3. 불필요한 추상화 레이어
4. 일관성 없는 에러 처리
5. 테스트 커버리지 낮은 영역

각 항목에 대해:

- 위치 (파일, 라인)
- 심각도 (Critical/Major/Minor)
- 리팩토링 예상 시간
- 권장 접근 방법

# 기술 부채 관리를 위한 Sprint 할당량
# 매 Sprint의 20%는 기술 부채 해결에 할당

# GitHub Issues 레이블 전략
labels:
  - name: tech-debt
    color: '#e4e669'
    description: 기술 부채 이슈
  - name: ai-generated
    color: '#7c3aed'
    description: AI가 생성한 코드 리뷰 필요
  - name: needs-refactor
    color: '#f97316'
    description: 리팩토링 필요