코드 리뷰와 커밋 컨벤션: 팀 협업의 핵심

<type>[optional scope]: <description>
 
[optional body]
 
[optional footer(s)]

feat(auth)!: change token format to JWT v5
 
BREAKING CHANGE: Token format changed from HS256 to ES256.
All existing tokens will be invalidated.
Migration guide: docs/migration/token-v5.md

# 기능 추가
feat(payment): add cryptocurrency payment support
 
Implement Bitcoin and Ethereum payment processing
using CoinGate API integration.
 
Closes #234
 
# 버그 수정
fix(auth): resolve JWT refresh token race condition
 
Multiple concurrent refresh requests could generate
duplicate tokens. Added mutex lock to token refresh handler.
 
Fixes #567
 
# 리팩토링
refactor(order): extract validation logic to separate service
 
Move order validation from OrderController to
OrderValidationService for better testability and reuse.
 
# 성능 개선
perf(query): optimize user search with database index
 
Add composite index on (email, created_at) to users table.
Query time reduced from 450ms to 12ms for 1M records.

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── 하위 호환되는 버그 수정 (fix:)
  │     └──────── 하위 호환되는 기능 추가 (feat:)
  └────────────── 하위 호환되지 않는 변경 (BREAKING CHANGE)
 
예: 2.4.1
    │ │ │
    │ │ └── 1번째 패치 (버그 수정)
    │ └──── 4번째 마이너 (기능 추가)
    └────── 2번째 메이저 (호환성 깨짐)

1.0.0-alpha.1     ← 알파 버전
1.0.0-beta.1      ← 베타 버전
1.0.0-rc.1        ← 릴리스 후보 (Release Candidate)
1.0.0             ← 정식 릴리스

{
  "dependencies": {
    "express": "^4.18.0",  // 4.x.x (MINOR, PATCH 업데이트 허용)
    "lodash": "~4.17.0",   // 4.17.x (PATCH 업데이트만 허용)
    "react": "18.2.0"      // 정확히 이 버전만
  }
}

커밋 히스토리 분석
    │
    ├── feat: → MINOR 버전 증가
    ├── fix: → PATCH 버전 증가
    ├── BREAKING CHANGE → MAJOR 버전 증가
    │
    ▼
package.json 버전 업데이트
    │
    ▼
CHANGELOG.md 자동 생성
    │
    ▼
Git 태그 생성 (v2.1.0)
    │
    ▼
GitHub Release 생성
    │
    ▼
npm/PyPI 등에 패키지 배포

# GitHub Actions 예시
name: Release
on:
  push:
    branches: [main]
 
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 전체 히스토리 필요
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm test
      - run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

# Changelog
 
## [2.1.0] - 2026-02-10
 
### Features
- **payment**: add cryptocurrency payment support (#234)
- **auth**: implement OAuth 2.1 PKCE flow (#245)
 
### Bug Fixes
- **auth**: resolve JWT refresh token race condition (#567)
- **order**: fix decimal precision in total calculation (#571)
 
### Performance
- **query**: optimize user search with database index (#580)

# 설치
npm install --save-dev husky lint-staged
 
# Husky 초기화
npx husky init

// package.json
{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md}": [
      "prettier --write"
    ],
    "*.test.{ts,tsx}": [
      "jest --bail --findRelatedTests"
    ]
  }
}

# .husky/pre-commit
npx lint-staged

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

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'build', 'ci', 'chore', 'revert'
    ]],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100]
  }
};

# .husky/commit-msg
npx --no -- commitlint --edit $1

git commit -m "feat: add payment"
    │
    ▼
[pre-commit hook]
├── lint-staged: ESLint + Prettier 실행
├── 테스트: 변경 파일 관련 테스트만 실행
│
├── 실패 → 커밋 차단, 에러 메시지 출력
└── 성공 ↓
 
[commit-msg hook]
├── commitlint: 메시지 형식 검증
│
├── 실패 → 커밋 차단 ("subject may not be empty")
└── 성공 → 커밋 완료

# .github/CODEOWNERS
 
# 전역 기본 소유자
* @team-lead @senior-dev
 
# 서비스별 소유자
/services/auth-service/    @auth-team
/services/payment-service/ @payment-team @security-team
/services/notification/    @platform-team
 
# 인프라 코드
/infrastructure/           @devops-team
/terraform/                @devops-team @security-team
/.github/                  @devops-team
 
# 보안 민감 파일
/services/*/security/      @security-team
*.env.example              @security-team
 
# 공유 라이브러리
/packages/shared-utils/    @platform-team
/packages/api-client/      @api-team
 
# 문서
/docs/                     @tech-writer @team-lead

## Summary
<!-- 변경사항 요약 (1-3문장) -->
 
## Motivation
<!-- 왜 이 변경이 필요한가? (관련 이슈 링크) -->
 
## Changes
<!-- 주요 변경 목록 -->
 
## Test Plan
<!-- 테스트 방법과 결과 -->
 
## Screenshots
<!-- UI 변경이 있는 경우 스크린샷 -->
 
## Checklist

PR 생성
    │
    ▼
[AI 리뷰 단계]
├── 코드 스타일/포맷팅 자동 수정
├── 보안 취약점 자동 스캔
├── 테스트 커버리지 분석
├── 중복 코드 탐지
│
    ▼
[인간 리뷰 단계]
├── 비즈니스 로직 검증
├── 아키텍처 적합성 확인
├── 장기적 유지보수 고려
├── AI 지적 사항 검토 (수용/기각)
│
    ▼
[승인 정책]
├── AI: 자동 수정/경고 (차단 권한 없음)
├── 인간: 최종 승인 권한
└── 보안 관련: 보안 팀 리뷰 필수

# GPG 키 생성
gpg --full-generate-key
 
# 키 목록 확인
gpg --list-secret-keys --keyid-format=long
 
# Git에 GPG 키 설정
git config --global user.signingkey ABC123DEF456
git config --global commit.gpgsign true
 
# 서명된 커밋
git commit -S -m "feat: add secure payment"
 
# 서명 확인
git log --show-signature

# SSH 키로 서명 (GPG보다 간단)
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
 
# 서명된 커밋 (자동)
git commit -m "feat: add secure payment"

개발자가 코드 작성
    │
    ▼
[pre-commit hook] ── lint-staged (ESLint, Prettier)
    │
    ▼
[commit-msg hook] ── commitlint (메시지 형식 검증)
    │
    ▼
git push
    │
    ▼
[CI Pipeline]
├── 빌드 (Build)
├── 단위 테스트 (Unit Test)
├── 통합 테스트 (Integration Test)
├── 보안 스캔 (SAST)
├── 코드 커버리지 (Coverage)
│
    ▼
[PR 생성]
├── AI 리뷰 (자동)
├── CODEOWNERS 기반 리뷰어 할당
├── 인간 리뷰
│
    ▼
[Merge Queue]
├── 자동 리베이스
├── 테스트 재실행
├── main 머지
│
    ▼
[semantic-release]
├── 버전 결정 (커밋 분석)
├── CHANGELOG 생성
├── Git 태그 생성
├── GitHub Release 생성
├── 패키지 배포
│
    ▼
[CD Pipeline]
├── Staging 배포
├── Canary 배포
└── Production 배포