알아서 공개되는 구조를 만든다

앞 편 전부 통째로 넘긴다에서 Issue 1건을 넘기고 판정하는 바퀴를 돌렸습니다. 그런데 판정이 "통과"여도 결과물이 내 컴퓨터 안에만 있으면 아무도 쓸 수 없습니다. 이번 편은 올리면 알아서 검사하고 공개되는 구조를 만듭니다. 이것이 갖춰져야 다음 편 동시에 여러 개 굴린다가 가능해집니다.

핵심 요약

공개를 사람이 손으로 하는 한, 위임은 마지막 단계에서 멈춥니다.
GitHub Actions는 저장소에 올라온 변경을 정해진 규칙대로 검사하고 배포하는 담당자입니다.
프리뷰 환경은 망가져도 되는 자리입니다. 운영 환경은 우리 교재의 표현대로 성역입니다.
설정 파일은 AI가 씁니다. 사람은 언제 공개할지와 무엇을 검사할지만 정합니다.

통째로 넘기기가 성립하는 조건

Issue를 넘겨 결과가 돌아왔는데 공개하려면 내가 서버에 접속해서 파일을 올리고 재시작해야 한다면, 그 마지막 30분은 여전히 사람의 일입니다. 그 30분이 귀찮아서 공개를 미루면 추적할 숫자는 영영 움직이지 않습니다. 통째로 넘기기는 "올리면 공개된다"까지 자동일 때 비로소 성립합니다.

우리 8주 교재 4주차의 흐름이 그 뼈대입니다. 로컬 개발, 커밋, 푸시, PR, 리뷰, 머지, 배포. 이 중 사람이 손을 대는 자리는 PR을 승인하는 리뷰 한 곳이면 충분합니다. 나머지는 기계가 합니다.

GitHub Actions는 "올리면 알아서 해 주는 담당"

GitHub Actions는 저장소의 .github/workflows/ 폴더에 둔 YAML 파일대로 움직입니다. 파일에는 언제(on), 어떤 환경에서(runs-on), 무엇을(steps) 할지 적습니다. 푸시가 올 때마다 테스트를 돌리는 최소 예시는 이렇습니다.

name: test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

실행 결과는 저장소의 Actions 탭에서 확인합니다. 테스트가 실패하면 PR에 빨간 표시가 뜨고, 사람은 그것만 보고 머지 여부를 정합니다. 여기에 Claude Code GitHub Actions를 더하면 검사뿐 아니라 구현까지 저장소 안에서 돌아갑니다. Claude Code에서 /install-github-app을 실행하면 GitHub 앱 설치와 워크플로우, ANTHROPIC_API_KEY 시크릿 등록을 안내하며, 워크플로우는 anthropics/claude-code-action@v1을 사용합니다. 일정에 따라 자동 실행하려면 on: schedule에 cron을 적고 prompt를 넘기면 됩니다. 반복 횟수를 제한하는 claude_args: "--max-turns 10"처럼 CLI 인수도 그대로 전달됩니다.

망가져도 되는 자리를 확보한다 (프리뷰 환경)

우리 7주차 교재의 서버 3단계를 기억하세요. 로컬은 나만 보는 곳, 개발(dev)은 검토용, 운영(production)은 실제 사용자가 쓰는 성역입니다. 프리뷰 환경은 이 중 두 번째 자리를 자동으로 만들어 주는 장치입니다.

Vercel을 예로 들면, 운영 브랜치(보통 main)가 아닌 브랜치에 푸시하거나 PR을 열면 프리뷰 배포가 생기고 고유 주소가 발급됩니다. 그 주소를 동료에게 보내 "이거 한번 눌러 봐"라고 할 수 있습니다. 망가져도 운영에는 영향이 없습니다. main에 머지되는 순간 운영 배포가 일어나므로, 4주차 교재의 원칙 "main에 직접 작업하지 않는다"가 곧 "운영을 직접 건드리지 않는다"와 같은 뜻이 됩니다.

주의할 것은 데이터입니다. 프리뷰 환경이 운영 DB를 바라보고 있으면 망가져도 되는 자리가 아닙니다. 교재의 표현대로 "DB 손실은 회사 종말"이므로 프리뷰는 별도 DB나 샘플 데이터를 씁니다. 이 조건도 Issue에 적어서 AI에게 넘깁니다.

사람이 정할 것·AI에게 맡길 것

사람이 정하는 것은 세 가지입니다. 무엇을 검사할지(테스트, 문구 검사, 키 노출 검사), 언제 공개할지(PR 승인 시점), 어디가 성역인지(운영 브랜치와 운영 DB). AI에게 맡기는 것은 그 조건을 만족하는 워크플로우 파일, 프리뷰 설정, 테스트 코드 전부입니다.

Issue: 자동 검사와 프리뷰 환경 만들기
완료 조건
- PR을 열면 테스트가 자동으로 돌고 결과가 PR에 표시된다
- PR마다 프리뷰 주소가 생기고, 프리뷰는 샘플 DB를 쓴다
- main에 머지되면 운영에 자동 배포된다
- .env 값이 로그나 저장소에 찍히지 않는다
- 설정 방법과 확인 방법을 docs/deploy.md에 적는다

키 값은 여기서도 규칙이 같습니다. 배포에 필요한 토큰과 API 키는 GitHub 저장소의 Secrets에 넣고 워크플로우에서 ${{ secrets.이름 }}으로 참조합니다. 공식 문서도 API 키를 워크플로우 파일에 직접 적지 말고 항상 Secrets를 쓰라고 못 박고 있습니다. 3주차 교재의 "키는 깃허브와 문서에 원문으로 넣지 않는다"가 자동화에서도 그대로 적용되는 것입니다.

마지막 줄이 중요합니다. docs/deploy.md는 나중에 무엇이 어떻게 자동화되어 있는지 내가 잊었을 때, 또는 다음 프로젝트에서 같은 구조를 다시 만들 때 AI에게 넘기는 재료가 됩니다.

해 보기

저장소에 .github/workflows/ 폴더가 있는지 확인합니다. 없으면 위 Issue를 그대로 만듭니다.
Claude Code에 Issue를 넘기고, 끝나면 PR을 하나 열어 Actions 탭에 초록 표시가 뜨는지 봅니다.
프리뷰 주소를 동료 한 명에게 보내 실제로 열리는지 확인합니다.
일부러 테스트를 실패시키는 변경을 올려 빨간 표시가 뜨는지도 확인합니다.
docs/deploy.md를 읽고 내 입으로 설명할 수 있는지 점검합니다.

정리

공개까지 자동이어야 위임이 끝까지 성립합니다.
GitHub Actions는 .github/workflows/의 YAML대로 검사와 배포를 맡습니다.
프리뷰는 망가져도 되는 자리, 운영과 운영 DB는 성역입니다.
설정은 AI가 쓰고, 사람은 검사 항목과 공개 시점만 정합니다.

자주 묻는 질문

왜 공개 작업을 자동화해야 하나요? 손으로 해도 되지 않나요?

손으로 하면 귀찮아서 미루고, 미루면 숫자가 안 움직이고, 숫자가 안 움직이면 개선 루프가 멈춥니다. 자동화의 목적은 편의가 아니라 루프의 속도입니다. 손으로 하는 배포는 실수도 잦아서 운영 사고의 단골 원인이기도 합니다.

GitHub Actions로 바이브 코딩에서 실제로 쓰는 절차는 무엇인가요?

푸시나 PR마다 테스트를 돌리는 검사, 머지 시 자동 배포, 일정에 따라 도는 작업(리포트, 공고 수집) 세 가지가 대부분입니다. Claude Code GitHub Actions를 더하면 Issue에 @claude를 멘션해 구현까지 저장소 안에서 시킬 수 있습니다.

프리뷰 환경은 꼭 필요한가요?

혼자 쓰는 도구라도 있으면 좋고, 다른 사람에게 보여 주는 순간부터는 필수입니다. 운영을 직접 건드리며 확인하는 습관은 언젠가 운영 데이터를 망가뜨립니다. 화면이 없는 자동화라면 프리뷰 대신 별도 실행 환경과 샘플 데이터로 같은 역할을 만듭니다.

CI/CD 설정 파일은 제가 직접 써야 하나요?

아니요. 검사할 항목과 공개 시점을 Issue에 적어 AI에게 넘깁니다. 대신 돌아온 결과를 "일부러 실패시켜 보기"로 검증하세요. 초록 표시만 보고 통과시키면 검사가 실제로 아무것도 안 하고 있는 경우를 놓칩니다.

자동화를 설정한 뒤 마지막에 docs/deploy.md를 남기라는 이유는 무엇인가요?

설정은 한 번 하면 잊어버립니다. 몇 달 뒤 배포가 실패했을 때, 또는 새 프로젝트에 같은 구조를 옮길 때 이 문서가 AI에게 넘길 재료가 됩니다. 우리 교육에서 작업이 끝날 때마다 목적, 변경, 명령, 결과, 다음 작업을 기록하게 하는 것과 같은 이유입니다.