ai-rules › handbook › 공통 배포 계약

공통 배포 계약

프로젝트별 서버/인프라가 달라도 동일한 배포 정책과 검증 흐름으로 운영할 수 있도록 공통 계약을 정의한다.

guide docs/guide/DEPLOYMENT_CONTRACT.md

목적: 프로젝트별 서버/인프라가 달라도 동일한 배포 정책과 검증 흐름으로 운영할 수 있도록 공통 계약을 정의한다. 관련 문서: AITEM_TO_COMMON_GOVERNANCE.md

왜 배포 계약이 필요한가

프로젝트마다 배포 방식은 다를 수 있다.

  • Vercel
  • Cloudflare Pages
  • Docker + VM
  • Kubernetes
  • GitHub Actions 기반 수동/반자동 배포

하지만 배포 전후에 확인해야 할 운영 규칙은 상당 부분 공통이다.

즉, 배포 정책은 공통화하고 실제 실행은 adapter로 분리해야 한다.

공통 원칙

1. 정책과 실행을 분리한다

  • 정책: 언제 배포 가능한가, 무엇을 검증해야 하는가
  • 실행: 어떤 명령으로 어디에 배포하는가

2. 배포는 단계적 게이트를 통과해야 한다

  • pre-merge
  • pre-deploy
  • deploy
  • post-deploy verify
  • rollback

3. 위험도에 따라 승인 기준을 다르게 둔다

  • staging 배포: 자동 또는 1회 승인
  • production 배포: 명시적 승인 필수
  • DB 관련 변경 포함 배포: 추가 안전 검토 필요

4. 배포 결과는 공통 리포트 형식으로 남긴다

  • 어떤 환경에 배포했는지
  • 어떤 검증을 통과했는지
  • 어떤 우회를 사용했는지
  • rollback이 있었는지

공통 배포 계약

모든 프로젝트는 아래 인터페이스를 개념적으로 충족해야 한다.

1. pre_merge_checks

목적:

  • PR 병합 전에 코드가 최소 품질 기준을 만족하는지 확인

기본 체크:

  • lint
  • typecheck
  • unit test
  • security scan
  • API contract check
  • migration safety check

출력:

  • pass
  • conditional
  • fail

2. pre_deploy_checks

목적:

  • 특정 환경 배포 직전에 환경별 위험 요소를 다시 확인

기본 체크:

  • 현재 브랜치/태그 확인
  • 대상 환경 확인 (staging / production)
  • 환경변수 누락 여부
  • build artifact 생성 가능 여부
  • DB migration 포함 여부
  • bypass 사용 여부

출력:

  • deployable
  • approval_required
  • blocked

3. deploy_staging

목적:

  • staging 환경 배포

요구사항:

  • pre_deploy_checks 통과
  • staging adapter 존재
  • post-deploy verify 자동 실행

4. deploy_production

목적:

  • production 환경 배포

요구사항:

  • 명시적 승인 필수
  • production adapter 존재
  • rollback 또는 recovery 레일 존재
  • post-deploy verify 자동 실행

5. rollback

목적:

  • 배포 실패 또는 회귀 발생 시 안정 상태로 복귀

허용 방식 예시:

  • revert 배포
  • 이전 artifact 재배포
  • rollback script
  • revert PR 자동 생성

최소 요구사항:

  • rollback 가능 여부 명시
  • 자동/수동 여부 명시
  • 실패 시 다음 대응 명시

6. post_deploy_verify

목적:

  • 배포 후 실제 서비스 상태 확인

기본 체크:

  • health endpoint
  • smoke test
  • 주요 사용자 흐름
  • 에러율/로그 이상 여부

출력:

  • healthy
  • degraded
  • rollback_required

환경별 기본 정책

staging

  • 자동 배포 가능
  • 단, pre_deploy_checks 통과 필요
  • smoke test 실패 시 degraded

production

  • 사용자 또는 운영 승인 필수
  • bypass 사용 시 별도 기록 필수
  • rollback 경로 없는 production 배포는 원칙적으로 금지

배포 adapter 구조

배포 adapter는 공통 계약의 실제 구현체다.

예시:

  • adapter/vercel
  • adapter/cloudflare-pages
  • adapter/docker-vm
  • adapter/k8s
  • adapter/github-actions

각 adapter는 최소한 아래 정보를 제공해야 한다.

  • 지원 환경 (staging, production)
  • 배포 명령
  • rollback 지원 여부
  • health check 방법
  • required secrets
  • build artifact 방식

프로젝트별 override 허용 범위

다음은 프로젝트별 override 가능:

  • deploy target
  • build 명령
  • required secrets
  • smoke test 시나리오
  • domain-specific verify 항목

다음은 공통 정책으로 유지:

  • production 승인 필요
  • bypass 기록 필수
  • post-deploy verify 필요
  • rollback 가능 여부 명시

AITEM 기준 매핑 예시

AITEM에서 공통으로 추출 가능한 것

  • pre-merge validation
  • branch protection
  • post-merge recovery
  • scheduled audit

AITEM 전용 override로 남길 것

  • 결제/인증 강화 검증
  • AITEM 특화 threshold
  • AITEM 특화 배포 모드

배포 리포트 최소 형식

# Deployment Report

- project: aitem
- environment: staging
- adapter: docker-vm
- commit: abc1234
- pre_merge_checks: pass
- pre_deploy_checks: deployable
- bypass_used: none
- post_deploy_verify: healthy
- rollback: not_needed

이 형식은 Markdown이든 JSON이든 동일한 의미를 유지해야 한다.

Capability Matrix와의 연결

이 계약은 이후 PROJECT_CAPABILITY_MATRIX.md에서 아래 항목으로 관리한다.

  • deploy adapter
  • staging 지원 여부
  • production 지원 여부
  • rollback 지원 여부
  • post-deploy verify 수준
  • bypass 허용 여부

한 줄 결론

배포 환경은 달라도, 배포 정책과 검증 흐름은 공통 계약으로 만들 수 있다. ai-rules는 이 계약을 기준으로 하고, 각 프로젝트는 adapter로 실제 배포를 구현한다.