title: Vercel 배포 전략 v2 — 3-브랜치 + AI-First PR 처리 date: 2026-02-25T23:50:00+09:00 type: strategy layer: L0 status: draft version: v2 supersedes: vercel-deployment-strategy.md tags: [vercel, git-branch, deployment, ci-cd, staging, ai-first] author: self-healing-impl-pl project: infra reviewed_by: jarvis reviewed_at: "2026-02-25T18:05:00+09:00"

Vercel 배포 전략 v2 — 3-브랜치 + AI-First PR 처리

v1 대비 변경점: CEO 피드백 3건 반영

1. AI-First PR 처리 — VP가 gh CLI로 PR 생성/머지, CEO는 텔레그램 승인만
2. staging 환경 추가 — 온라인에서 테스트 가능한 중간 단계
3. 3-브랜치 전략 — main(개발, 배포 안 함) / staging(Preview QA) / production(실서비스)

1. 업계 표준 브랜치 전략 비교

1-1. 3대 브랜치 전략

1-2. 업계 동향 (2025~2026)

• GitFlow 창시자 Vincent Driessen도 2020년에 "GitHub Flow가 대부분 팀에 더 적합"이라고 인정 — 설치형 소프트웨어가 아닌 웹 SaaS 시대
• Trunk-Based가 이상적이나 전제조건 필수: 자동 테스트 커버리지 80%+, CI 파이프라인, feature flag 시스템 → AI 1인 기업에는 오버엔지니어링
• 환경 분리(staging)는 업계 표준: development → staging → production 3단계가 사실상 기본
• Vercel 공식 권장: Production + Preview + Custom Environment(staging) 3-tier 구조

1-3. 우리 상황에 최적인 전략

결론: Modified 3-Branch 전략 — GitHub Flow의 단순함 + staging 환경 + AI-First PR 처리 결합.

2. 3-브랜치 전략 설계

2-1. 브랜치 구조

main (개발 브랜치)
  │
  │ ← AI 에이전트(자비스/PL) 커밋
  │ ← 개발자 직접 커밋
  │ ← feature 브랜치 merge
  │
  │    Vercel: 배포 안 함 (ignoreCommand로 skip)
  │
  ├─── PR merge ───→ staging (QA/테스트 브랜치)
  │                      │
  │                      │    Vercel: Preview 배포 (자동)
  │                      │    URL: staging-{project}.vercel.app
  │                      │    용도: 온라인 QA, CEO/VP 검수
  │                      │
  │                      ├─── PR merge ───→ production (프로덕션 브랜치)
  │                      │                      │
  │                      │                      │    Vercel: Production 배포 (자동)
  │                      │                      │    URL: 커스텀 도메인 (apppro.kr 등)
  │                      │                      │
  │                      │                      └─── VP가 `gh pr merge`로 처리
  │                      │
  │                      └─── VP가 `gh pr create` + `gh pr merge`로 처리
  │
  └─── feature/* (선택적)
       └─── 큰 기능 개발 시 사용, main으로 PR

2-2. 브랜치 역할 정의

2-3. v1 대비 핵심 변경

3. Vercel 3-브랜치 설정 방법

3-1. Vercel 환경 체계 (공식 문서 기반)

Vercel은 3가지 기본 환경을 제공한다:

추가로 Custom Environment (Pro 플랜 이상)를 사용하면 staging 전용 환경을 만들 수 있다.

3-2. 설정 방법 A: Hobby 플랜 (Custom Environment 미지원)

Hobby 플랜에서는 Custom Environment를 사용할 수 없으므로, staging 브랜치를 Preview 환경으로 활용한다.

Step 1: production 브랜치를 Production Branch로 설정

Vercel Dashboard → Project Settings → Environments
→ Production Branch: production (main에서 변경)

Step 2: staging 브랜치에 도메인 연결

Vercel Dashboard → Project Settings → Domains
→ staging-{project}.vercel.app 또는 커스텀 도메인 추가
→ Edit → Git Branch: staging 으로 변경

Step 3: main 브랜치 배포 차단 (ignoreCommand)

// vercel.json
{
  "ignoreCommand": "bash scripts/should-deploy.sh"
}

#!/bin/bash
# scripts/should-deploy.sh
# exit 0 = 빌드 건너뜀, exit 1 = 빌드 진행

BRANCH=$(git rev-parse --abbrev-ref HEAD)

case "$BRANCH" in
  production|staging)
    exit 1  # 빌드 진행
    ;;
  *)
    exit 0  # 빌드 건너뜀 (main, feature/* 등)
    ;;
esac

Step 4: 환경변수 분리

Vercel Dashboard → Project Settings → Environment Variables
→ 각 변수에 대해:
   - Production: production 전용 값 (실서비스 DB, API 키)
   - Preview: staging 전용 값 (테스트 DB, 테스트 API 키)

3-3. 설정 방법 B: Pro 플랜 (Custom Environment 지원)

Pro 플랜에서는 Custom Environment로 더 명확한 staging 분리가 가능하다.

Step 1: Custom Environment 생성

Vercel Dashboard → Project Settings → Environments
→ Create Environment
→ Name: staging
→ Branch Tracking: staging 브랜치
→ Attach Domain: staging-{project}.vercel.app
→ Import Variables from: Preview (필요한 것만)

Step 2: CLI로 staging 배포 (선택적)

# staging 환경으로 직접 배포
vercel deploy --target=staging

# staging 환경변수 로컬에 가져오기
vercel pull --environment=staging

Step 3: main 배포 차단 (동일)

// vercel.json — 동일한 ignoreCommand 사용
{
  "ignoreCommand": "bash scripts/should-deploy.sh"
}

3-4. Hobby vs Pro: staging 지원 비교

권장: 상업 프로젝트(apppro.kr, richbukae.com)는 Pro 전환 시 Custom Environment 활용. 내부 프로젝트(kanban, content-pipeline)는 Hobby + Preview 기반 staging으로 충분.

4. AI-First PR 처리 플로우

4-1. 핵심 원칙

CEO가 GitHub에서 "Merge pull request" 버튼을 클릭하는 것은 AI-First가 아니다.

4-2. 전체 PR 플로우 (main → staging → production)

[1] AI 에이전트 / PL
    │
    │ git push origin main (코드 작성 완료)
    │
    ↓
[2] VP: staging PR 생성
    │
    │ gh pr create --base staging --head main \
    │   --title "Release v1.2.0: 기능 설명" \
    │   --body "변경 사항 요약"
    │
    ↓
[3] Vercel: staging Preview 배포 (자동)
    │
    │ staging-{project}.vercel.app 에서 확인 가능
    │
    ↓
[4] VP: QA 검수
    │
    │ - staging URL에서 기능 테스트
    │ - QA 체크리스트 확인
    │ - 문제 발견 시: AI 에이전트에게 수정 지시 → main에 추가 커밋 → PR 자동 업데이트
    │
    ↓
[5] VP: staging PR merge
    │
    │ gh pr merge {PR번호} --squash --delete-branch=false
    │   (staging 브랜치는 삭제하지 않음)
    │
    ↓
[6] VP: production PR 생성
    │
    │ gh pr create --base production --head staging \
    │   --title "Deploy v1.2.0 to production" \
    │   --body "staging QA 통과. 변경 내용: ..."
    │
    ↓
[7] CEO 승인 (텔레그램)
    │
    │ VP → CEO: "production 배포 승인 요청: [staging URL] [변경 요약]"
    │ CEO → VP: "승인" (텔레그램 회신)
    │
    ↓
[8] VP: production PR merge
    │
    │ gh pr merge {PR번호} --squash --delete-branch=false
    │
    ↓
[9] Vercel: Production 배포 (자동)
    │
    │ 커스텀 도메인 (apppro.kr 등) 즉시 반영
    │
    ↓
[10] VP: 배포 확인 + 보고
     │
     │ - 커스텀 도메인에서 최종 확인
     │ - CEO에게 배포 완료 보고 (텔레그램)
     │ - 자비스에게 QA 체크리스트 수행 지시 (선택)

4-3. VP가 사용하는 gh CLI 명령어 정리

main → staging PR

# PR 생성
gh pr create \
  --repo migkjy/{레포명} \
  --base staging \
  --head main \
  --title "Release: {변경 요약}" \
  --body "## 변경 사항
- {변경1}
- {변경2}

## QA 체크리스트
- [ ] staging URL 정상 접속
- [ ] 주요 기능 동작 확인
- [ ] 에러 로그 확인"

# PR 상태 확인
gh pr view {PR번호} --repo migkjy/{레포명}

# staging PR merge (QA 통과 후)
gh pr merge {PR번호} \
  --repo migkjy/{레포명} \
  --squash \
  --subject "release: {변경 요약}" \
  --delete-branch=false

staging → production PR

# PR 생성
gh pr create \
  --repo migkjy/{레포명} \
  --base production \
  --head staging \
  --title "Deploy: {변경 요약}" \
  --body "## staging QA 완료
- staging URL: {URL}
- QA 통과 항목: {N}개
- CEO 텔레그램 승인: 대기 중"

# CEO 승인 후 merge
gh pr merge {PR번호} \
  --repo migkjy/{레포명} \
  --squash \
  --subject "deploy: {변경 요약}" \
  --delete-branch=false

긴급 핫픽스 (staging 건너뛰기)

# hotfix 브랜치 생성 (production 기준)
git checkout -b hotfix/critical-fix production

# 수정 후 staging + production 동시 PR
gh pr create --base staging --head hotfix/critical-fix --title "Hotfix: {설명}"
gh pr create --base production --head hotfix/critical-fix --title "Hotfix: {설명}"

# 둘 다 merge 후 hotfix 브랜치 삭제
gh pr merge {staging-PR} --squash
gh pr merge {production-PR} --squash
git push origin --delete hotfix/critical-fix

4-4. CEO 승인이 필요한 경우 vs 불필요한 경우

VP 자율 판단 범위: 기존 기능 버그픽스, 콘텐츠만 변경, 긴급 장애 복구. 새 기능/UI 변경/API 변경은 CEO 승인 필수.

4-5. AI 에이전트 안전 규칙

### Git Push 규칙 (CLAUDE.md 추가용)
1. AI 에이전트(자비스/PL)는 `main` 브랜치에만 push한다
2. `staging`, `production` 브랜치에 직접 push 절대 금지
3. staging/production 배포는 VP가 `gh pr merge`로만 진행
4. feature/* 브랜치는 main으로 PR, staging/production으로 직접 PR 금지
5. force push (`--force`, `--force-with-lease`) 모든 브랜치에서 금지

5. 프로젝트별 적용 계획

5-1. content-pipeline (migkjy/ai-blog)

현재: main + phase1-mvp 브랜치, Vercel 2개 프로젝트(content-pipeline-sage, content-orchestration)

적용 후:
  main         → 배포 안 함 (ignoreCommand skip)
  staging      → Preview 배포 (staging-content-pipeline.vercel.app)
  production   → Production 배포 (blog.apppro.kr 연결 시)

vercel.json:

{
  "ignoreCommand": "bash scripts/should-deploy.sh",
  "git": {
    "deploymentEnabled": {
      "phase1-mvp": false
    }
  },
  "crons": [
    { "path": "/api/cron/publish", "schedule": "0 21 * * *" },
    { "path": "/api/cron/pipeline", "schedule": "0 21 * * 1-5" }
  ]
}

주의: Cron은 Production 배포에서만 실행. production 브랜치 생성 후 즉시 첫 merge 필수.

5-2. apppro-kr (migkjy/apppro.kr-)

현재: master 단일 브랜치

적용 후:
  main (master → main 이름 변경) → 배포 안 함
  staging                        → Preview 배포 (staging-apppro.vercel.app)
  production                     → Production 배포 (apppro.kr)

작업 순서:

1. master → main 이름 변경 (gh api repos/migkjy/apppro.kr-/branches/master/rename -f new_name=main)
2. staging 브랜치 생성 (git checkout -b staging main && git push -u origin staging)
3. production 브랜치 생성 (git checkout -b production main && git push -u origin production)
4. Vercel: Production Branch → production 변경
5. Vercel: Domains → apppro.kr, www.apppro.kr → production 연결 확인
6. Vercel: staging 도메인 추가 → staging 브랜치 연결
7. ignoreCommand 설정 (vercel.json 또는 scripts/should-deploy.sh)
8. GitHub Branch Protection: production + staging에 PR 필수

5-3. richbukae-store (migkjy/richbukae-store)

현재: master 단일 브랜치

동일한 작업 순서. Toss 결제 연동이 있으므로 staging에서 테스트 키, production에서 실서비스 키 분리 특히 중요.

환경변수 분리 예시:
  staging:    TOSS_SECRET_KEY=test_sk_...  (테스트 모드)
  production: TOSS_SECRET_KEY=live_sk_...  (실서비스)

5-4. kanban-dashboard (business-builder 모노레포)

현재: business-builder/main, Vercel Root Directory: projects/kanban-dashboard/

적용 후:
  main         → 배포 안 함
  staging      → Preview 배포 (kanban 변경 시만)
  production   → Production 배포 (business-builder-kanban.vercel.app)

vercel.json (모노레포 특화):

{
  "ignoreCommand": "bash scripts/should-deploy-kanban.sh"
}

#!/bin/bash
# scripts/should-deploy-kanban.sh
# 모노레포: kanban 디렉토리 변경 + staging/production 브랜치만 배포

BRANCH=$(git rev-parse --abbrev-ref HEAD)

# main 및 feature/* 브랜치는 항상 skip
case "$BRANCH" in
  production|staging)
    # kanban 디렉토리 변경 여부 체크
    git diff HEAD^ HEAD --quiet -- projects/kanban-dashboard/
    # diff가 있으면 exit 1(빌드), 없으면 exit 0(skip) — git diff --quiet의 기본 동작
    ;;
  *)
    exit 0  # 빌드 건너뜀
    ;;
esac

5-5. content-orchestration (migkjy/content-orchestration 별도 레포)

content-pipeline과 별도 레포이므로 독립적으로 브랜치 전략 적용.

적용 후:
  main         → 배포 안 함 (ignoreCommand skip)
  staging      → Preview 배포 (staging-content-orchestration.vercel.app)
  production   → Production 배포 (content-orchestration.vercel.app / 커스텀 도메인)

브랜치 현황: production 브랜치 이미 생성 완료 (2026-02-25). staging 브랜치 추가 필요.

# staging 브랜치 생성 (CEO 승인 후)
cd {content-orchestration 경로}
git checkout -b staging main
git push origin staging

5-6. koreaaihub.kr (향후)

신규 프로젝트. 처음부터 3-브랜치로 시작:

1. GitHub 레포 생성 시 기본 브랜치 = main
2. staging, production 브랜치 즉시 생성
3. Vercel: Production Branch = production
4. Vercel: staging 도메인 연결
5. ignoreCommand 설정

6. 배포 쿼터 절약 효과

6-1. v1 vs v2 배포 횟수 비교

가정: AI 에이전트가 하루 평균 30회 main에 push, staging/production merge는 주 2~3회

Hobby 100회/시간 한도를 초과할 위험이 사실상 0이 된다.

6-2. ignoreCommand 전략

6-3. .vercelignore (빌드 속도 최적화)

# .vercelignore — 모든 프로젝트 공통
.claude/
memory/
docs/
scripts/
*.md
!README.md
.git/
tests/
__tests__/

7. GitHub Branch Protection 설정

7-1. production 브랜치

Settings → Branches → Add Rule → Branch name pattern: production

✅ Require a pull request before merging
   ✅ Require approvals: 1
   ✅ Dismiss stale pull request approvals when new commits are pushed
✅ Require status checks to pass before merging
   ✅ Vercel Preview 빌드 성공 (status check)
✅ Do not allow force pushes
✅ Do not allow deletions
❌ Restrict pushes (VP가 merge 가능해야 하므로)

7-2. staging 브랜치

Settings → Branches → Add Rule → Branch name pattern: staging

✅ Require a pull request before merging
   ❌ Require approvals (VP 자율 merge)
✅ Do not allow force pushes
✅ Do not allow deletions

7-3. main 브랜치 (최소 보호)

✅ Do not allow force pushes
✅ Do not allow deletions
❌ Require a pull request (AI 에이전트 직접 push 허용)

8. 구현 작업 목록 (우선순위순)

Phase 1: 즉시 적용 (비용 없음, CEO 승인 불필요)

Phase 2: 브랜치 생성 + Vercel 설정 (CEO 승인 필요)

Phase 3: Pro 플랜 + Custom Environment (비용 발생)

비용: 최소 $20/월 (apppro.kr만 Pro), 권장 $40/월 (+ richbukae.com)

9. 위험 요소 및 대응

Cron 관련 중요 사항 (v1 동일)

Vercel Cron은 Production 배포에서만 실행된다. staging(Preview)에서는 Cron 트리거 안 됨.

• content-pipeline Cron: production 브랜치 배포 후에만 동작
• kanban-dashboard OKR Cron: production 브랜치 배포 후에만 동작
• 브랜치 전환 시 즉시 staging→production PR merge하여 Cron 중단 방지

10. 요약: v2 핵심 3가지

1. 3-브랜치 전략: main(개발, 배포 안 함) → staging(Preview QA) → production(실서비스). AI 에이전트 커밋은 main에서 완전 격리. 배포 쿼터 98% 절약.

2. AI-First PR 처리: VP가 gh CLI로 PR 생성/머지를 전부 자동 처리. CEO는 텔레그램에서 "승인" 한 마디면 끝. GitHub UI 접근 불필요.

3. 환경변수 완전 분리: staging(테스트 키) / production(실서비스 키) 분리로, 테스트 환경에서 실서비스 DB/API를 건드리는 사고 방지.

리뷰 로그

[self-healing-impl-pl 초안 작성] 2026-02-25 23:50

• v1 CEO 피드백 3건 반영: AI-First PR, staging 환경, 3-브랜치 전략
• 업계 표준 3대 브랜치 전략 비교 (GitHub Flow / Git Flow / Trunk-Based)
• Vercel 3-브랜치 설정: Hobby(Preview 기반) + Pro(Custom Environment) 2안 제시
• AI-First PR 플로우 10단계 설계 + VP gh CLI 명령어 전체 정리
• CEO 승인 필요/불필요 판단 기준 5항목 정의
• 프로젝트별(6개) 적용 계획 + 환경변수 분리 가이드
• 배포 쿼터 98% 절약 효과 산출
• 구현 작업 13개를 3 Phase로 분류

[자비스 검수] 2026-02-25T18:05:00+09:00

• ✅ CEO 피드백 3건 전부 반영 (AI-First PR 처리, staging 환경, 3-브랜치 전략)
• ✅ 업계 표준 리서치 포함 (GitHub Flow / Git Flow / Trunk-Based 비교 + 2025~26 동향)
• ✅ Vercel 3-브랜치 설정: Hobby(Preview 기반) + Pro(Custom Environment) 2안 명확
• ✅ 10단계 AI-First PR 플로우 + VP gh CLI 명령어 정리 완비
• ✅ CEO 승인 필요/불필요 판단 기준 5항목 명확 (버그픽스/콘텐츠는 VP 자율)
• ✅ 6개 프로젝트 적용 계획 + 배포 쿼터 98% 절약(960→18 배포/월) 산출
• ✅ Branch Protection 설정 (production/staging/main 각 레벨 구분)
• ✅ Cron 중단 리스크 명시 — 전환 후 즉시 staging→production merge 필수
• ✅ CLAUDE.md 추가용 AI 에이전트 안전 규칙 (Section 4-5) 포함
• ⚠️ Section 5-5 오류: content-orchestration을 "migkjy/ai-blog 동일 레포"라고 했으나 실제로는 별도 레포 (migkjy/content-orchestration). VP 승인 전 수정 필요.
• 검수 판정: ⚠️ 수정 후 VP 승인 요청