✍️ 필사 모드: 거대 소프트웨어는 어떻게 개발하고 관리하고 유지할까? — SW 업데이트 시스템까지

company-repo/
  frontend/
  backend/
  mobile/
  infra/
  shared-libs/
  tools/

# API Gateway 라우팅 예시
routes:
  - path: /api/users
    service: user-service
    methods: [GET, POST]
  - path: /api/orders
    service: order-service
    methods: [GET, POST, PUT]
  - path: /api/payments
    service: payment-service
    methods: [POST]

# Istio VirtualService 예시
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: user-service
spec:
  hosts:
    - user-service
  http:
    - route:
        - destination:
            host: user-service
            subset: v2
          weight: 90
        - destination:
            host: user-service
            subset: v1
          weight: 10

# 서킷 브레이커 의사 코드
class CircuitBreaker:
    def __init__(self, threshold=5, timeout=30):
        self.failure_count = 0
        self.threshold = threshold
        self.timeout = timeout
        self.state = "CLOSED"  # CLOSED, OPEN, HALF_OPEN

    def call(self, func):
        if self.state == "OPEN":
            if self.timeout_expired():
                self.state = "HALF_OPEN"
            else:
                raise CircuitOpenError("Service unavailable")

        try:
            result = func()
            self.on_success()
            return result
        except Exception as e:
            self.on_failure()
            raise e

    def on_failure(self):
        self.failure_count += 1
        if self.failure_count >= self.threshold:
            self.state = "OPEN"

    def on_success(self):
        self.failure_count = 0
        self.state = "CLOSED"

# GitHub Actions CI 파이프라인 예시
name: CI Pipeline
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install dependencies
        run: npm ci
      - name: Lint
        run: npm run lint
      - name: Unit Tests
        run: npm run test:unit
      - name: Integration Tests
        run: npm run test:integration
      - name: Build
        run: npm run build

트래픽 분배:
  v1 (기존): 95%  ████████████████████░
  v2 (신규):  5%  █░░░░░░░░░░░░░░░░░░░

30분 후 (이상 없음):
  v1 (기존): 50%  ██████████░░░░░░░░░░
  v2 (신규): 50%  ██████████░░░░░░░░░░

1시간 후 (이상 없음):
  v1 (기존):  0%  ░░░░░░░░░░░░░░░░░░░░
  v2 (신규): 100% ████████████████████

현재: Blue (v1) ← 트래픽
      Green (v2) 대기 중

전환: Blue (v1) 대기
      Green (v2) ← 트래픽

롤백: Blue (v1) ← 트래픽 (즉시 복구)
      Green (v2) 대기

# Kubernetes Rolling Update 설정
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 4
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 1
  template:
    spec:
      containers:
        - name: my-app
          image: my-app:v2
          readinessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10

// 피처 플래그 사용 예시
const featureFlags = {
  newCheckoutFlow: false,
  darkMode: true,
  aiRecommendation: false,
};

function renderCheckout() {
  if (featureFlags.newCheckoutFlow) {
    return renderNewCheckout();
  }
  return renderLegacyCheckout();
}

# 피처 플래그 평가 엔진 (간략화)
class FeatureFlagService:
    def is_enabled(self, flag_name, user_context):
        flag = self.get_flag(flag_name)

        if not flag.enabled:
            return False

        # 특정 사용자 화이트리스트
        if user_context.user_id in flag.whitelist:
            return True

        # 퍼센티지 롤아웃
        if flag.rollout_percentage > 0:
            hash_value = hash(f"flag_name:{user_context.user_id}") % 100
            return hash_value < flag.rollout_percentage

        # 조건 기반 (국가, OS 등)
        for rule in flag.rules:
            if rule.matches(user_context):
                return True

        return False

// Electron auto-updater 구현
import { autoUpdater } from 'electron-updater';

// 업데이트 서버 설정
autoUpdater.setFeedURL({
  provider: 'github',
  owner: 'my-org',
  repo: 'my-app',
});

// 업데이트 이벤트 핸들러
autoUpdater.on('checking-for-update', () => {
  log.info('업데이트 확인 중...');
});

autoUpdater.on('update-available', (info) => {
  log.info('새 버전 발견:', info.version);
  // 사용자에게 알림 표시
  showUpdateNotification(info);
});

autoUpdater.on('download-progress', (progress) => {
  log.info('다운로드 진행률:', progress.percent.toFixed(1) + '%');
  updateProgressBar(progress.percent);
});

autoUpdater.on('update-downloaded', (info) => {
  // "업데이트를 위해 재시작" 다이얼로그 표시
  showRestartDialog(info.version);
});

// 주기적 업데이트 확인 (4시간마다)
setInterval(() => {
  autoUpdater.checkForUpdates();
}, 4 * 60 * 60 * 1000);

전체 업데이트: v1.0 (200MB) → v1.1 (200MB) = 200MB 다운로드
델타 업데이트: v1.0 (200MB) → v1.1 (200MB) = 15MB 다운로드 (차이분만)

일반적인 모바일 업데이트 흐름:

1. 개발자가 새 빌드를 스토어에 제출
2. 스토어 심사 (Apple: 24-48시간, Google: 수 시간)
3. 승인 후 스토어에 게시
4. 사용자 기기에서 자동/수동 업데이트

Day 1: 1% 출시 → 크래시 리포트 모니터링
Day 2: 5% 출시 → 사용자 피드백 확인
Day 3: 20% 출시
Day 5: 50% 출시
Day 7: 100% 출시

// React Native OTA 업데이트 (EAS Update 예시)
import * as Updates from 'expo-updates';

async function checkForOTAUpdate() {
  try {
    const update = await Updates.checkForUpdateAsync();

    if (update.isAvailable) {
      // 백그라운드에서 업데이트 다운로드
      await Updates.fetchUpdateAsync();

      // 사용자에게 재시작 확인
      Alert.alert(
        '업데이트 완료',
        '새 버전이 준비되었습니다. 지금 적용하시겠습니까?',
        [
          { text: '나중에', style: 'cancel' },
          {
            text: '지금 적용',
            onPress: () => Updates.reloadAsync(),
          },
        ]
      );
    }
  } catch (error) {
    console.error('OTA 업데이트 실패:', error);
  }
}

# ArgoCD를 이용한 GitOps 기반 서버 업데이트
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-service
spec:
  project: default
  source:
    repoURL: https://github.com/my-org/k8s-manifests
    path: services/my-service
    targetRevision: main
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

// "Update and Restart" 전체 흐름

// 1단계: 버전 체크 API
async function checkVersion(): Promise<UpdateInfo | null> {
  const currentVersion = app.getVersion(); // "2.3.1"
  const response = await fetch(
    'https://update.example.com/api/check' +
      '?app=myapp' +
      '&version=' + currentVersion +
      '&platform=' + process.platform +
      '&arch=' + process.arch
  );

  const data = await response.json();
  // data 예시:
  // {
  //   "updateAvailable": true,
  //   "latestVersion": "2.4.0",
  //   "downloadUrl": "https://cdn.example.com/myapp-2.4.0-darwin-x64.zip",
  //   "checksum": "sha256:a1b2c3...",
  //   "releaseNotes": "버그 수정 및 성능 개선",
  //   "mandatory": false,
  //   "size": 52428800
  // }

  if (data.updateAvailable) {
    return data;
  }
  return null;
}

// 2단계: 업데이트 다운로드 및 검증
async function downloadAndVerify(updateInfo: UpdateInfo): Promise<string> {
  const tempDir = path.join(os.tmpdir(), 'app-update');
  const downloadPath = path.join(tempDir, 'update.zip');

  // 다운로드 (진행률 표시)
  await downloadFile(updateInfo.downloadUrl, downloadPath, (progress) => {
    mainWindow.setProgressBar(progress / 100);
    mainWindow.webContents.send('update-progress', progress);
  });

  // 체크섬 검증
  const fileHash = await calculateHash(downloadPath, 'sha256');
  if (fileHash !== updateInfo.checksum.replace('sha256:', '')) {
    throw new Error('체크섬 불일치: 파일이 손상되었거나 변조됨');
  }

  // 서명 검증 (코드 사이닝)
  await verifySignature(downloadPath);

  return downloadPath;
}

// 3단계: 업데이트 적용 및 재시작
function applyUpdateAndRestart(updatePath: string) {
  // 현재 앱 경로 백업
  const appDir = path.dirname(process.execPath);
  const backupDir = appDir + '.backup';

  // 업데이터 스크립트 생성 (앱 종료 후 실행)
  const updaterScript = createUpdaterScript({
    currentAppDir: appDir,
    backupDir: backupDir,
    updateArchive: updatePath,
    executablePath: process.execPath,
  });

  // 업데이터를 별도 프로세스로 실행
  const child = spawn(updaterScript, {
    detached: true,
    stdio: 'ignore',
  });
  child.unref();

  // 현재 앱 종료
  app.quit();
}

#!/bin/bash
# updater.sh - 앱 종료 후 실행되는 업데이트 스크립트

# 1. 기존 앱이 완전히 종료될 때까지 대기
sleep 2
while pgrep -f "myapp" > /dev/null; do
    sleep 1
done

# 2. 기존 버전 백업
cp -r "/Applications/MyApp.app" "/Applications/MyApp.app.backup"

# 3. 새 버전 설치
unzip -o "/tmp/app-update/update.zip" -d "/Applications/"

# 4. 검증
if [ -f "/Applications/MyApp.app/Contents/MacOS/myapp" ]; then
    # 성공: 백업 삭제 후 앱 재시작
    rm -rf "/Applications/MyApp.app.backup"
    open "/Applications/MyApp.app"
else
    # 실패: 백업에서 복구
    rm -rf "/Applications/MyApp.app"
    mv "/Applications/MyApp.app.backup" "/Applications/MyApp.app"
    open "/Applications/MyApp.app"
fi

# 5. 임시 파일 정리
rm -rf "/tmp/app-update"

의도적 + 신중한: "지금은 단순 구현으로 가고, 다음 분기에 리팩토링하자"
의도적 + 무모한: "설계는 나중에 하고 일단 빨리 만들자"
비의도적 + 신중한: "구현 후 돌아보니 더 나은 설계가 있었다"
비의도적 + 무모한: "레이어드 아키텍처가 뭐지?"

# 기술 부채 측정 지표 예시
class TechDebtMetrics:
    def calculate_debt_ratio(self):
        metrics = {
            # 코드 품질
            "test_coverage": self.get_test_coverage(),        # 목표: 80%+
            "code_duplication": self.get_duplication_rate(),   # 목표: 5% 미만
            "cyclomatic_complexity": self.get_avg_complexity(),# 목표: 10 미만

            # 의존성 건강
            "outdated_deps": self.count_outdated_dependencies(),
            "security_vulns": self.count_known_vulnerabilities(),

            # 빌드/배포 건강
            "build_time_minutes": self.get_avg_build_time(),
            "deploy_frequency_per_day": self.get_deploy_frequency(),
            "change_failure_rate": self.get_change_failure_rate(),  # 목표: 15% 미만
            "mttr_hours": self.get_mean_time_to_recovery(),         # 목표: 1시간 미만
        }
        return metrics

Phase 1: 레거시(100%) ─── 신규(0%)
Phase 2: 레거시(70%)  ─── 신규(30%)
Phase 3: 레거시(30%)  ─── 신규(70%)
Phase 4: 레거시(0%)   ─── 신규(100%)  ← 레거시 제거

# 포스트모텀 템플릿

## 장애 요약
- 발생 시각: 2026-04-10 14:23 KST
- 복구 시각: 2026-04-10 15:07 KST
- 영향 범위: 전체 사용자의 약 30% (결제 서비스)
- 심각도: P1 (Critical)

## 타임라인
- 14:23 - 결제 성공률 급감 알림 발생
- 14:25 - 온콜 엔지니어 대응 시작
- 14:32 - 근본 원인 파악 (DB 커넥션 풀 고갈)
- 14:45 - 긴급 패치 배포 시작
- 15:07 - 전체 서비스 정상 복구 확인

## 근본 원인
새로 배포된 쿼리에 인덱스가 누락되어 응답 시간이
기존 50ms에서 5초로 증가. 이로 인해 커넥션 풀이 고갈됨.

## 조치 사항
- [완료] 누락된 인덱스 추가
- [진행중] 슬로우 쿼리 자동 감지 시스템 구축
- [예정] 배포 전 쿼리 성능 테스트 자동화

SLO: 99.95% 가용성 (월간)

이번 달 현재: 99.97%
에러 버짓 남은 양: 0.02%
상태: 새로운 기능 배포 가능

만약 99.93%라면?
에러 버짓 소진: 초과 사용
상태: 안정성 개선에만 집중

온콜 로테이션 예시:

주간 1: 엔지니어 A (Primary), 엔지니어 B (Secondary)
주간 2: 엔지니어 B (Primary), 엔지니어 C (Secondary)
주간 3: 엔지니어 C (Primary), 엔지니어 D (Secondary)

알림 에스컬레이션:
  0분: PagerDuty → Primary 엔지니어 (앱 알림 + 전화)
  5분: 미응답 → Secondary 엔지니어
 15분: 미응답 → 팀 리드
 30분: 미해결 → VP of Engineering

# ADR 0015: 메시지 큐로 Apache Kafka 선택

## 상태
승인됨 (2026-03-15)

## 맥락
주문 처리 시스템에서 서비스 간 비동기 통신이 필요하다.
후보: Kafka, RabbitMQ, AWS SQS

## 결정
Apache Kafka를 선택한다.

## 이유
- 높은 처리량 (초당 수십만 건)
- 이벤트 소싱 패턴에 적합
- 메시지 재처리(replay) 가능
- 팀에 Kafka 운영 경험 보유

## 결과
- Kafka 클러스터 운영 비용 발생
- 팀원 대상 Kafka 교육 필요
- 모니터링 도구(Kafka UI) 도입 필요

RFC 흐름:

1. 작성자가 RFC 문서 초안 작성 (1-2일)
2. 관련 팀에 리뷰 요청
3. 코멘트 및 토론 기간 (1-2주)
4. 최종 결정 (승인/반려/수정)
5. 구현 시작

추천 문서화 도구 조합:

코드 레벨: JSDoc / docstring + 자동 생성 API 문서
프로젝트 레벨: README.md + CONTRIBUTING.md + CHANGELOG.md
팀 레벨: Notion / Confluence 위키
조직 레벨: 검색 가능한 중앙 지식 베이스

일반적인 기업 개발:
  팀 A → 라이브러리 X 요청 → 팀 B → 백로그 대기 (2-3개월)

InnerSource 방식:
  팀 A → 라이브러리 X에 직접 PR 제출 → 팀 B 리뷰 → 머지 (1-2주)

아키텍처
  [ ] 서비스 경계가 명확하게 정의되어 있는가?
  [ ] API 버전 관리 전략이 있는가?
  [ ] 서킷 브레이커 / 재시도 정책이 구현되어 있는가?

CI/CD
  [ ] 코드 커밋부터 프로덕션 배포까지 자동화되어 있는가?
  [ ] 롤백이 5분 이내에 가능한가?
  [ ] 카나리/블루-그린 배포 전략이 있는가?

업데이트 시스템
  [ ] 자동 업데이트가 구현되어 있는가?
  [ ] 업데이트 파일의 무결성 검증(체크섬, 서명)을 하는가?
  [ ] 업데이트 실패 시 롤백 메커니즘이 있는가?

모니터링
  [ ] SLI/SLO가 정의되어 있는가?
  [ ] 알림 에스컬레이션 정책이 있는가?
  [ ] 분산 트레이싱이 구현되어 있는가?

기술 부채
  [ ] 기술 부채를 주기적으로 측정하고 있는가?
  [ ] 리팩토링에 할당된 엔지니어링 시간이 있는가?
  [ ] 의존성 업데이트 정책이 있는가?

문서화
  [ ] ADR을 작성하고 있는가?
  [ ] API 문서가 자동 생성되는가?
  [ ] 온보딩 문서가 최신 상태인가?