joechrisnaldy/production-readiness

프로덕션 준비 상태 체크리스트

각 항목은 확인해야 할 사항을 명시합니다. CLAUDE.md에 정의된 단계 티어를 사용하여 프로젝트 단계에 맞는 항목을 적용하고, 단계가 정의되지 않은 경우 단계(프로토타입, MVP, 프로덕션 또는 스케일)를 추론하여 명시합니다. 리뷰에서 프로젝트 단계에 맞지 않는 항목은 '아직 해당 없음'으로 표시하고, 해당 항목이 관련성을 갖게 되는 트리거를 명시합니다.

1. 보안 및 접근 제어

• 권한 부여: 모든 엔드포인트와 접근하는 모든 객체에 대해 서버 측 권한을 확인합니다(로그인 시에만 확인하지 않음). 이는 IDOR 및 BOLA를 방지합니다. Supabase, Firebase 또는 유사한 백엔드를 사용하는 경우 행 수준 보안 또는 보안 규칙을 활성화하고 테스트해야 합니다.
• 입력 검증: 모든 신뢰 경계에서 스키마 라이브러리(Zod, Pydantic 또는 이에 상응하는 라이브러리)를 사용하여 유형, 길이, 형식 및 범위를 검증합니다. 클라이언트 측 검증은 UX를 위한 것이며 보안을 위한 것이 아닙니다.
• SQL 인젝션: 매개변수화된 쿼리 또는 ORM 바인딩만 사용합니다. 정렬 열과 같은 동적 식별자는 허용 목록을 사용합니다.
• XSS: 프레임워크 이스케이프에 의존합니다. 신뢰할 수 없는 데이터와 함께 innerHTML, dangerouslySetInnerHTML 및 v-html을 사용하지 않거나 검증된 라이브러리(예: DOMPurify)로 살균합니다. 콘텐츠 보안 정책을 추가합니다.
• CSRF: 쿠키 기반 세션의 경우 SameSite 쿠키와 CSRF 토큰 또는 상태 변경 요청에 대한 출처 검사를 사용합니다. GET 요청으로 상태를 변경하지 마십시오.
• CORS: 정확한 출처를 허용 목록에 추가합니다. 임의의 출처를 반영하거나 자격 증명과 함께 와일드카드를 허용하지 마십시오. CORS는 접근 제어가 아닙니다.
• SSRF: 서버가 사용자가 제공한 URL을 가져올 때 대상을 허용 목록에 추가하고, IPv4 및 IPv6에 대한 개인, 루프백 및 링크-로컬 주소(169.254.169.254의 클라우드 메타데이터 포함)를 차단하며, 리디렉션 및 DNS 확인 후 다시 확인합니다.
• 시크릿 관리: 환경 변수 또는 시크릿 관리자에서 시크릿을 로드합니다. 시크릿은 코드, 로그, 컨테이너 이미지 또는 git 기록에 절대 나타나지 않으며, 유출된 모든 항목은 교체됩니다.
• IAM: 모든 사람, 서비스 및 토큰에 최소 권한을 적용합니다. 환경별 및 서비스별로 별도의 자격 증명을 사용하고, 애플리케이션에서 루트 또는 관리자 키를 절대 사용하지 마십시오.
• OAuth: 사용자 지정 인증보다는 검증된 제공자 또는 라이브러리를 사용합니다. 브라우저 및 모바일 클라이언트에는 PKCE가 포함된 인증 코드를 사용하고, 정확한 리디렉션 URI 일치, 상태 검증 및 최소 범위를 사용합니다.
• JWT 순환: 수명이 짧은 액세스 토큰, 재사용 감지를 통한 순환 새로 고침 토큰, 키 ID(kid) 및 JWKS를 통해 순환되는 서명 키를 사용합니다. 항상 서명, 알고리즘, 발급자, 대상자 및 만료를 확인합니다.
• 비밀번호 및 세션 보안: Argon2id 또는 bcrypt로 비밀번호를 해시합니다. 세션 쿠키를 HttpOnly, Secure 및 SameSite로 설정합니다. 계정에 가치가 있는 경우 MFA를 제공합니다.
• TLS: 자동 인증서 갱신, TLS 1.2 이상(1.3 권장) 및 HSTS를 사용하여 모든 곳에서 HTTPS를 제공합니다. 인증서 확인을 비활성화하지 마십시오.
• 전송 중 암호화: 공개 트래픽뿐만 아니라 서비스, 데이터베이스, 캐시 및 큐 연결을 포함한 내부 트래픽도 암호화합니다.
• 저장 데이터 암호화: KMS의 키를 사용하여 데이터베이스, 디스크, 백업 및 객체 스토리지를 암호화합니다. 매우 민감한 데이터의 경우 필드 수준 암호화를 고려합니다.
• 보안 헤더: Content-Security-Policy(클릭재킹 방지를 위한 frame-ancestors 포함), Strict-Transport-Security, X-Content-Type-Options: nosniff 및 Referrer-Policy를 설정합니다.
• WAF: 퍼블릭 프로덕션 앱 앞에 관리형 규칙 세트가 있는 웹 애플리케이션 방화벽을 배치합니다.
• DDoS 보호: 제공자 보호(Cloudflare, AWS Shield 또는 플랫폼 기본값)에 의존하고 속도 제한 및 오토스케일링 상한을 추가하여 공격이 무제한 청구로 이어지지 않도록 합니다.
• 공급망 보안: CI에서 종속성 취약점 검사(npm audit, pip-audit, Dependabot 등)를 실행합니다. 모든 새 패키지가 실제이고 올바르게 명명되었으며 유지 관리되는지 확인합니다.
• 파일 업로드: 확장자가 아닌 콘텐츠로 유형을 확인하고, 크기를 제한하고, 임의의 이름으로 객체 스토리지에 저장하고, 수명이 짧은 서명된 URL을 통해 개인 파일을 제공합니다.
• 감사 로그: 민감한 작업(인증 이벤트, 권한 변경, 데이터 내보내기, 자금 이동)에 대해 누가, 언제, 무엇을 했는지 추가 전용 스토리지에 기록합니다.
• 개인정보 및 PII: 최소한으로 수집하고, 개인 데이터가 있는 위치를 파악하고, 로그에 포함되지 않도록 하고, 보존 기간을 정의하고, GDPR 또는 CCPA와 같은 법률이 적용되는 경우 삭제 및 내보내기를 지원합니다.

2. 데이터 및 데이터베이스

• 데이터베이스 인덱싱: 커질 테이블의 필터, 조인 및 정렬에 사용되는 열(외래 키 포함)을 인덱싱합니다. 쓰기 속도를 저하시키는 중복 인덱스를 피합니다.
• 쿼리 최적화: 느리거나 빈번한 쿼리에 대해 EXPLAIN으로 계획을 확인합니다. 필요한 열만 선택하고 WHERE 절 내에서 인덱싱된 열을 함수로 래핑하지 않습니다.
• N+1 쿼리: 항목당 한 번씩 쿼리하는 루프를 찾습니다. 조인, 즉시 로딩 또는 일괄 처리로 대체합니다.
• 연결 풀링: 데이터베이스 한도에 맞게 풀 크기를 조정합니다. 서버리스에서는 모든 인스턴스가 자체 연결을 열기 때문에 풀러(PgBouncer, RDS Proxy 또는 제공자의 풀러)를 사용합니다.
• 트랜잭션: 함께 성공하거나 실패해야 하는 다중 단계 쓰기를 하나의 트랜잭션으로 래핑하고, 격리 수준을 의도적으로 선택합니다.
• 제약 조건: NOT NULL, UNIQUE, 외래 키 및 CHECK 제약 조건으로 데이터베이스에서 무결성을 적용합니다. 애플리케이션 수준의 검사만으로는 경쟁 조건에 취약합니다.
• 페이지매이션: 모든 목록 엔드포인트와 쿼리를 제한된 페이지 크기로 페이지매이션합니다. 크거나 변경되는 데이터의 경우 커서(키셋) 페이지매이션을 선호합니다.
• 돈과 시간: 돈은 정수 하위 단위 또는 10진수 유형으로 저장합니다. 타임스탬프는 UTC로 저장하고 표시 시에만 변환합니다.
• 읽기 복제본: 읽기가 기본 데이터베이스에 과부하를 줄 때만 추가하고, 특히 사용자가 자신의 쓰기를 읽을 때 복제 지연을 처리합니다.
• 복제: 동기식인지 비동기식인지와 장애 조치 시 손실될 수 있는 데이터 양을 파악합니다.
• 파티셔닝: 인덱스와 유지 관리를 관리하기 쉽게 유지하기 위해 매우 큰 테이블(종종 시간별로)을 파티셔닝하고, 파티션을 삭제하여 오래된 데이터를 만료시킵니다.
• 샤딩: 인덱싱, 캐싱, 복제본 및 수직 확장 후 최후의 수단으로 처리합니다. 핫스팟과 교차 샤드 쿼리를 피하는 샤드 키를 선택합니다.
• 데이터베이스 마이그레이션: 마이그레이션을 버전 관리, 검토, 배포 시 자동화 및 가능하면 되돌릴 수 있도록 유지합니다. 무중단 배포를 위해 확장 및 축소를 사용합니다. 추가, 백필, 전환, 이후 릴리스에서 제거합니다. 파괴적인 변경 전에 백업합니다.
• 스키마 버전 관리: 데이터 계약(데이터베이스 스키마, 이벤트 페이로드, API 스키마)의 버전을 관리하여 배포 중에 이전 코드와 새 코드가 함께 실행될 수 있도록 합니다.

3. 동시성 및 분산 시스템

• 경쟁 조건: 확인 후 실행 패턴(잔액, 재고, 고유 사용자 이름, 쿠폰 사용)을 찾습니다. 원자적 업데이트, 제약 조건, 트랜잭션 또는 잠금으로 수정합니다.
• 스레드 안전성: 스레드, 작업자 및 비동기 작업 간에 공유되는 변경 가능한 상태를 동기화하거나 제거합니다. 모듈 수준 전역 변수는 종종 요청 간에 공유됩니다.
• 낙관적 잠금: 업데이트 시 버전 열 또는 ETag를 확인하고 충돌 시 409 또는 412를 반환합니다.
• 비관적 잠금: 경합이 심한 중요 섹션에 대해 SELECT ... FOR UPDATE를 사용하고 잠금을 짧게 유지합니다.
• 교착 상태: 일관된 순서로 잠금을 획득하고, 트랜잭션을 짧게 유지하며, 교착 상태 오류 시 재시도합니다.
• 분산 잠금: 만료되는 임대와 펜싱 토큰을 사용하여 프로세스 간 조정에만 사용합니다. 가능한 경우 데이터베이스 제약 조건이나 큐를 선호합니다.
• 분산 트랜잭션: 서비스 간 2단계 커밋을 피합니다. 가능하면 하나의 데이터베이스 내에서 트랜잭션 경계를 유지합니다.
• 사가 패턴: 서비스에 걸친 워크플로의 경우 로컬 트랜잭션을 보상 작업으로 연결하고 모든 단계를 멱등성으로 만듭니다.
• CAP 정리: 네트워크 분할 중에 시스템은 일관성 또는 가용성을 선택해야 합니다. 잔액 및 재고는 일관성이 필요하고, 피드 및 카운터는 지연을 허용할 수 있으므로 기능별로 결정합니다.
• 최종 일관성: 허용되는 경우 UI와 로직을 지연된 읽기용으로 설계하고 업데이트가 수렴되도록 합니다.
• 리더 선출: 정확히 하나의 인스턴스가 작동해야 하는 경우(스케줄러, 싱글톤 작업자) 임대 또는 플랫폼 프리미티브를 사용하고 하드코딩된 인스턴스를 사용하지 않습니다.
• 네트워크 파티션: 모든 호출이 중간에 실패하거나 응답 없이 성공할 수 있다고 가정합니다. 타임아웃, 멱등성 및 조정을 사용하여 설계합니다.
• 클록 스큐: 순서 또는 정확성을 위해 여러 시스템의 클록에 절대 의존하지 마십시오. 데이터베이스 타임스탬프, 시퀀스 번호 또는 논리적 클록을 사용하고 토큰 만료 확인 시 약간의 여유를 허용합니다.
• 서비스 디스커버리: DNS, 플랫폼 또는 레지스트리를 통해 서비스를 확인하고 하드코딩된 IP는 사용하지 않습니다.

4. 복원력 및 내결함성

• 타임아웃: 모든 아웃바운드 호출(HTTP, 데이터베이스, 캐시, 큐, LLM API)에 대해 호출자 자체 마감 시간 내에 맞는 연결 및 요청 타임아웃을 제공합니다.
• 재시도: 멱등성 작업에서만 일시적인 오류(타임아웃, 연결 오류, 429, 502, 503, 504)를 재시도하고 시도 횟수를 제한합니다. 모든 계층에서 동시에 재시도하지 마십시오. 이는 부하를 배가시킵니다.
• 지수 백오프: 지터와 함께 지수적으로 백오프하고 Retry-After 헤더를 준수합니다.
• 차단기(Circuit Breaker): 반복적인 오류 후 실패하는 종속성 호출을 중단하고, 폴백으로 빠르게 실패하며, 복구를 위해 프로브합니다.
• 멱등성: 재시도될 수 있는 작업(결제, 주문, 웹훅 핸들러, 작업)에 멱등성 키 또는 자연 키를 제공하여 중복이 추가 효과를 내지 않도록 합니다.
• 역압(Backpressure): 큐, 버퍼 및 동시성을 제한합니다. 과부하 시 무제한 작업을 수락하는 대신 부하를 분산하거나 429 또는 503을 반환합니다.
• 격리(Bulkheads): 리소스(별도 풀 또는 작업자)를 격리하여 하나의 느린 종속성이 모든 것을 소진하지 못하도록 합니다.
• 정상적 성능 저하: 종속성이 중단되었을 때 여전히 작동하는 항목(예: 캐시된 데이터, 읽기 전용 모드, 기능 일시 숨기기)을 결정합니다.
• 정상 종료: SIGTERM 수신 시 새 작업 수락을 중단하고, 진행 중인 요청 및 작업을 완료한 다음 연결을 닫습니다.
• 헬스 체크: 로드 밸런서 또는 플랫폼을 위해 저렴한 헬스 엔드포인트를 노출합니다.
• 활성(Liveness) 및 준비 상태(Readiness) 프로브: Liveness는 중단된 프로세스만 감지하며 외부 서비스에 의존해서는 안 됩니다. 그렇지 않으면 하나의 데이터베이스 장애로 모든 것이 다시 시작됩니다. Readiness는 인스턴스가 트래픽을 수신해야 하는지 여부를 결정하며 종속성을 확인할 수 있습니다.
• 장애 조치: 기본 데이터베이스, 영역 또는 제공자가 실패할 때 발생하는 상황을 파악합니다. 가동 시간이 중요한 경우 자동화하고 테스트합니다.

5. 메시징, 백그라운드 작업 및 실시간

• 메시지 큐: 느리거나, 재시도 가능하거나, 버스트 가능한 작업(이메일, 미디어 처리, 타사 호출)을 요청 경로에서 큐와 작업자가 있는 곳으로 이동합니다.
• 전달 의미 체계: 최소 한 번 전달을 가정하므로 소비자는 멱등성이 있어야 합니다. 시스템이 키별로 순서를 보장하지 않는 한 순서를 가정하지 마십시오.
• 데드 레터 큐(DLQ): 재시도를 모두 소진한 메시지를 경고 및 재생 경로와 함께 DLQ로 라우팅합니다. 자동으로 삭제하거나 영원히 재시도하지 마십시오.
• Pub/Sub: 정의된 이벤트 스키마 및 소유권과 함께 여러 독립적인 소비자에게 팬아웃하는 데 사용합니다.
• 이벤트 기반 아키텍처: 분리가 디버깅 비용을 감수할 가치가 있을 때 채택합니다. 이벤트를 버전이 지정된 계약으로 처리하고 요청을 추적 가능하게 유지합니다.
• 트랜잭션 아웃박스: 데이터베이스 쓰기가 이벤트도 게시해야 하는 경우 두 작업을 하나의 트랜잭션(아웃박스 테이블)으로 작성하고 비동기적으로 전달하여 이중 쓰기 문제를 방지합니다.
• Cron 작업: 예약된 작업을 멱등성 있게 만들고, 두 번 실행되거나 중복되어도 안전하며, 한 번에 하나의 인스턴스로 제한하고, 누락되거나 실패한 실행을 모니터링합니다.
• WebSocket: 연결 시 인증하고, 하트비트를 보내고, 백오프로 재연결하고, 여러 인스턴스(공유 pub/sub 또는 고정 세션)를 계획합니다.
• Server-Sent Events(SSE): 알림, 진행 상황 및 LLM 토큰 스트리밍과 같은 단방향 서버-클라이언트 스트림의 경우 WebSocket보다 SSE를 선호합니다.
• 롱 폴링: WebSocket 및 SSE를 사용할 수 없을 때 폴백으로 사용하고, 타임아웃과 보류 연결 수에 제한을 둡니다.
• Webhook: 수신 웹훅의 경우 서명(HMAC)을 확인하고, 재생 방지를 위해 만료된 타임스탬프를 거부하고, 빠르게 승인하고 비동기적으로 처리하며, 이벤트 ID로 중복을 제거합니다. 발신 웹훅의 경우 페이로드에 서명하고, 백오프와 함께 재시도하고, 이벤트 형식의 버전을 관리합니다.

6. 트래픽, 엣지 및 네트워킹

• 속도 제한: 퍼블릭, 인증 및 비용이 많이 드는 엔드포인트(로그인, 회원가입, 비밀번호 재설정, OTP, LLM 호출)에서 사용자, API 키 및 IP별로 제한합니다. Retry-After와 함께 429를 반환합니다.
• 로드 밸런싱: 헬스 체크된 인스턴스에 트래픽을 분산합니다. 앱 서버를 상태 비저장으로 유지하여 모든 인스턴스가 모든 요청을 처리할 수 있도록 합니다.
• 리버스 프록시: 프록시에서 TLS를 종료하고, 압축하고, 본문 크기 및 타임아웃 제한을 적용합니다. 클라이언트 IP가 스푸핑되지 않도록 알려진 프록시에서만 X-Forwarded-For를 신뢰합니다.
• API 게이트웨이: 여러 서비스 또는 퍼블릭 API가 있는 경우 인증, 속도 제한, 라우팅 및 검증을 중앙 집중화합니다. 단일 앱에서는 거의 필요하지 않습니다.
• CDN: 긴 캐시 수명과 콘텐츠 해시 파일 이름을 사용하여 정적 자산 및 미디어를 CDN을 통해 제공합니다.
• DNS: 마이그레이션 전에 TTL을 낮추고, 가능하면 레코드를 코드로 관리하며, 전파 지연을 예상합니다.
• TCP vs UDP: 기본적으로 TCP 기반 프로토콜을 사용합니다. UDP는 손실을 허용하는 지연 시간에 민감한 트래픽(실시간 미디어, 게임)에 대해서만 애플리케이션 수준 처리를 통해 사용합니다.
• HTTP/2 및 HTTP/3: 멀티플렉싱 및 더 빠른 연결을 위해 엣지 또는 CDN에서 활성화합니다. 이는 일반적으로 애플리케이션 코드가 아닌 구성입니다.
• gRPC: 엄격한 계약 또는 스트리밍이 필요한 내부 서비스 호출에 사용하고 모든 호출에 마감 시간을 설정합니다. 브라우저는 gRPC-Web 또는 게이트웨이가 필요합니다.

7. 캐싱

• 캐싱: 필요성을 측정한 후에만 캐싱하고 각 캐시의 키, TTL 및 대상을 정의합니다. 공유 캐시에 일반 키로 사용자별 또는 권한 종속 데이터를 저장하지 마십시오.
• 엣지 캐싱: Cache-Control을 명시적으로 설정하고, 개인화된 응답을 private 또는 no-store로 표시하며, 신선도가 만료된 경우 stale-while-revalidate를 사용합니다.

...

(참고: 원본 SKILL.md의 내용이 길어 일부 항목이 생략되었습니다. 전체 번역 버전은 원본의 모든 섹션을涵盖합니다)