코드 리뷰 체크리스트

체크리스트는 기억력에 의존하지 않는 품질 관리 도구다. 항공기 파일럿이 이륙 전 체크리스트를 쓰듯, 소프트웨어 배포도 체계적인 확인 과정이 필요하다. 이 챕터는 웹 서비스 + AI 모델 서빙을 함께 운영하는 팀을 위한 실용 체크리스트를 제공한다.

PR 체크리스트 — 코드 제출 전

코드 품질

• 함수 하나가 하나의 역할만 수행한다 (Single Responsibility)
• 함수 길이가 50줄 이하다 (예외: 불가피한 경우 주석으로 이유 명시)
• 중복 코드가 없다 (같은 로직이 2곳 이상이면 추출)
• 매직 넘버가 없다 (timeout=30 대신 INFERENCE_TIMEOUT_SECONDS = 30)
• 변수명과 함수명이 의도를 드러낸다 (d 대신 duration_ms)
• 타입 힌트가 모든 함수 시그니처에 있다 (Python)
• console.log / print 디버그 코드가 없다
• TODO/FIXME 주석이 이슈 링크와 함께 있다 (기한 없는 TODO 금지)

테스트

• 새 기능에 단위 테스트가 있다
• 엣지 케이스(빈 입력, 최댓값, 잘못된 타입)를 테스트한다
• 테스트가 서로 독립적이다 (순서 의존성 없음)
• 테스트가 실제로 실패했다가 통과한다 (TDD 확인)
• 외부 서비스 호출이 mock으로 처리되어 있다
• CI에서 테스트가 통과한다

보안

• 사용자 입력이 Pydantic 스키마로 검증된다
• SQL 쿼리에 f-string이 없다 (ORM 또는 파라미터 바인딩 사용)
• 비밀키/토큰이 코드에 하드코딩되지 않았다
• API 키가 응답에 노출되지 않는다
• 새 엔드포인트에 인증이 적용되었는가 (의도적 공개 엔드포인트인 경우 주석)
• 파일 업로드 기능이 있다면 파일 타입과 크기를 검증한다

에러 처리

• 모든 외부 I/O(DB, API, 파일)에 예외 처리가 있다
• 에러 메시지가 사용자에게 내부 구현을 노출하지 않는다
• HTTP 상태 코드가 의미에 맞다 (404 vs 400 vs 500)
• 예외를 무시하는 except: pass가 없다

문서

• 공개 API 엔드포인트에 docstring이 있다
• 복잡한 비즈니스 로직에 주석이 있다
• README 또는 API 문서가 변경 사항을 반영한다

배포 전 체크리스트

환경 설정

• 프로덕션 환경변수가 .env.production에 설정되어 있다
• 개발 환경의 debug 플래그가 꺼져 있다 (DEBUG=False)
• 데이터베이스 URL이 프로덕션 DB를 가리킨다
• CORS 허용 origin이 프로덕션 도메인으로 설정되어 있다
• 비밀키(SECRET_KEY)가 개발용 기본값이 아닌 강력한 랜덤 값이다

데이터베이스

• Alembic 마이그레이션이 최신이다 (alembic upgrade head 확인)
• 마이그레이션이 롤백 가능하다 (downgrade 구현)
• 대용량 마이그레이션이 있다면 점진적 배포를 계획했다
• DB 백업이 최신이다

빌드와 의존성

• pnpm build 경고 없이 성공한다
• pip install -r requirements.txt가 성공한다
• 의존성 버전이 고정되어 있다 (requirements.txt 또는 pnpm-lock.yaml)
• 불필요한 개발 의존성이 프로덕션 이미지에 포함되지 않는다

성능과 인프라

• ML 모델 파일이 프로덕션 서버에 배포되었다
• nginx 설정이 유효하다 (nginx -t)
• proxy_read_timeout이 ML 추론 시간보다 충분히 크다
• 디스크 용량이 충분하다 (로그, 모델 파일, DB)
• 메모리가 모델 로딩에 충분하다

관측성

• 로깅이 프로덕션 레벨(INFO 이상)로 설정되어 있다
• Prometheus 메트릭 엔드포인트가 동작한다
• 알림(alert) 규칙이 설정되어 있다 (에러율 5% 초과 시 알림 등)
• 롤백 계획이 있다 (이전 버전으로 되돌리는 절차)

운영 체크리스트 — 정기 점검

주간 점검

• 에러 로그에서 반복되는 패턴을 확인했다
• p99 응답 시간이 목표치 이하다
• 디스크 사용량 증가 추세를 확인했다
• 의존성 보안 취약점이 없다 (pip audit, pnpm audit)

월간 점검

• DB 쿼리 슬로우 로그를 분석했다
• 미사용 인덱스를 확인했다
• 로그 보존 기간이 정책에 맞게 설정되어 있다
• 백업 복원 테스트를 수행했다
• 사용하지 않는 API 엔드포인트나 기능을 식별했다

AI 모델 서비스 특화 체크리스트

AI/ML 모델을 웹 서비스에 통합할 때 추가로 확인해야 할 항목들이다.

모델 관리

• 모델 버전이 명시되어 있다 (파일명에 버전 포함 또는 메타데이터)
• 모델 로딩 실패 시 서비스가 graceful하게 에러를 반환한다 (500 대신 503)
• 프로덕션 모델과 개발 모델이 분리되어 있다
• 모델 업데이트 시 롤백 가능하다 (이전 버전 보관)
• 모델 파일의 무결성을 검증한다 (checksum)

추론 품질

• 입력 데이터 유효성 검사가 있다 (길이, 형식, 인코딩)
• 모델 출력에 신뢰도 점수가 포함된다 (가능한 경우)
• 낮은 신뢰도 응답에 대한 처리 정책이 있다
• 추론 결과가 로그에 샘플링되어 기록된다 (모니터링용)
• 입력-출력 분포 모니터링이 설정되어 있다 (데이터 드리프트 탐지)

리소스와 확장성

• GPU/CPU 메모리 사용량이 모니터링된다
• 동시 추론 요청 수에 제한이 있다 (OOM 방지)
• 요청 큐 크기가 모니터링된다
• 부하 테스트로 최대 처리량을 검증했다
• 배치 추론이 구현되어 있다 (GPU 효율)

규정 준수

• 사용자 입력 데이터 보존 기간 정책이 있다
• 민감한 데이터(PII)가 모델 입력으로 전달되지 않는다
• 모델의 편향성(bias) 평가를 수행했다
• 모델 판단에 대한 설명 가능성이 필요한지 검토했다

핵심 정리

• PR 체크리스트 — 코드 품질, 테스트, 보안, 에러 처리, 문서를 제출 전 모두 확인한다.
• 배포 전 체크리스트 — 환경 변수, DB 마이그레이션, 빌드 성공, 관측성 설정을 순서대로 점검한다.
• 운영 체크리스트 — 주간/월간 정기 점검으로 장기 품질 저하를 방지한다.
• AI 모델 특화 항목 — 모델 버전 관리, 추론 품질 모니터링, 데이터 드리프트 탐지는 일반 웹 서비스에는 없는 AI 서비스 고유의 운영 항목이다.
• 체크리스트는 기억을 대체하는 도구다. 팀의 실제 장애 사례를 기반으로 지속적으로 갱신한다.