구현 대화에서 테스트가 통과했다고 바로 배포 명령을 이어 쓰면 어떤 변경을 운영에 올리는지 다시 확인하기 어렵습니다. 배포는 새 Claude 세션을 Plan Mode로 열고, 배포 지침과 `git diff`를 처음부터 읽히는 편이 안전합니다. 로컬 검사, 커밋, 푸시, 배포와 운영 확인은 영향이 서로 달라 승인 시점도 나뉘어야 합니다.

핵심 완료는 승인된 변경이 추적 가능한 커밋으로 배포되고, 운영 URL과 핵심 사용자 흐름, 데이터와 관찰 지표를 확인했으며 되돌릴 방법이 준비된 상태입니다. 어느 하나라도 확인되지 않았다면 남은 제약을 명시합니다.

커밋은 단순 저장이 아니라 배포 단위다

관련 없는 사용자 변경을 섞지 않고 기능과 필수 자산만 명시적으로 포함합니다. 커밋 메시지는 무엇을 바꿨는지 설명하고, 배포할 정확한 커밋을 기록합니다. 자동 생성물이 있다면 원본과 재생성 방법도 확인합니다.

푸시 전에 문법, 콘텐츠, 보안과 프로젝트별 검사를 모두 실행합니다. 실패한 검사를 무시하고 운영에서 확인하겠다는 선택은 디버깅 비용을 뒤로 미루는 일입니다.

데이터와 코드의 배포 순서를 맞춘다

스키마 변경은 이전 코드와 새 코드가 전환 중 함께 동작할 수 있는지 확인합니다. 파괴적인 변경은 백필과 호환 단계, 롤백 가능성을 분리합니다. 환경변수는 값 자체를 기록하지 않고 존재 여부와 권한만 검증합니다.

정적 파일과 캐시가 있는 서비스는 새 코드가 배포돼도 이전 자산이 남을 수 있습니다. 버전 키, 캐시 무효화와 실제 응답 헤더를 확인합니다.

운영 검증은 실제 URL에서 한다

HTTPS 상태, 제목과 메타, 핵심 API, 이미지와 사용자 흐름을 운영 도메인에서 확인합니다. 단순 상태 코드뿐 아니라 올바른 내용과 데이터가 표시되는지 봅니다. 검색 노출 페이지라면 대표 주소, 구조화 데이터와 사이트맵도 검증합니다.

배포 직후 오류 로그와 주요 지표를 살피고, 비정상 상태에서 기능을 끄거나 이전 커밋으로 돌아갈 방법을 준비합니다. 오류가 없다는 사실보다 문제가 생겼을 때 안전하게 멈출 수 있는지가 중요합니다.

에이전트에게 맡길 수 있는 부분과 승인 지점

정해진 테스트, 배포 명령과 운영 점검은 자동화할 수 있습니다. 하지만 운영 데이터 변경, 권한 확대, 비용이 큰 인프라와 외부 메시지 발송은 별도 승인을 유지합니다. 자동화 범위는 성공 경로가 아니라 실패 영향으로 결정합니다.

완료 보고에는 커밋, 운영 URL, 통과한 검증, 데이터 변경과 남은 위험을 짧게 남깁니다. 다음 작업자가 대화를 읽지 않아도 현재 상태를 재구성할 수 있어야 합니다.

배포 세션은 구현 대화와 분리합니다

예시 세션은 이미 리뷰가 끝난 웹 변경을 배포 직전 검증합니다. 새 세션에서 배포 지침과 실제 변경 차이를 다시 읽혀 오래된 구현 대화의 가정을 끊습니다. 처음에는 Plan Mode로 시작해 배포 명령을 실행하지 않습니다.

배포 승인 전에 복사할 첫 요청
claude --permission-mode plan

CLAUDE.md, 배포 운영 문서, package.json을 먼저 읽으세요.
git status와 git diff --stat을 확인하세요.
아직 commit, push, deploy는 하지 마세요.
반환 형식:
- 배포 대상 파일과 제외할 사용자 변경
- 필수 검증 명령
- 환경변수 이름과 범위, 값은 제외
- 예상 운영 확인 URL과 사용자 흐름
- 중단·롤백 조건
- 승인이 필요한 명령 목록

검증과 운영 쓰기는 승인 시점을 나눕니다

사람이 변경 파일을 확인한 뒤 “문법, 단위 테스트, 콘텐츠 검사를 실행하고 `git diff --check`와 전체 `git diff`를 요약하세요. 실패하면 수정하지 말고 멈추세요”라고 요청합니다. 예상 결과는 모든 배포 전 검사가 통과하고 배포 대상 밖 차이가 없는 상태입니다.

그 결과를 다시 검토한 다음에만 커밋, 푸시, 배포를 각각 승인합니다. 운영 URL에서는 상태 코드뿐 아니라 로그인이나 저장 같은 핵심 흐름을 확인하게 하고, 배포 ID와 롤백 대상을 반환받습니다. 마이그레이션이 구버전과 호환되지 않거나 환경변수 범위를 확인할 수 없거나 운영 오류가 중단 기준을 넘으면 배포를 진행하지 않습니다. 다음 작업이 장애 분석이라면 배포 세션을 끌고 가지 말고 배포 ID와 로그 위치를 남긴 뒤 새 세션을 엽니다.

상태 코드는 200인데 새 화면은 보이지 않았다

가상의 예시로 가격 안내 문구를 고쳐 배포한 상황에서 빌드와 서버 헬스체크는 통과했습니다. 운영 URL도 200을 반환했습니다. 그런데 실제 브라우저에는 이전 문구가 남았습니다. HTML은 새 버전이었지만 CDN이 오래된 자산을 가리키고 있었기 때문입니다.

팀은 “배포 성공”과 “사용자에게 새 버전 노출”이 충돌한다는 사실을 확인했습니다. 자산 해시와 응답 헤더를 비교해 캐시 무효화가 빠진 것을 찾았고, 새 자산을 배포한 뒤 모바일과 데스크톱에서 문구와 링크를 다시 확인했습니다.

롤백 판단은 오류율과 핵심 흐름으로 미리 정한다

배포 전 오류율을 기준선으로 삼고, 배포 뒤 합의한 허용 범위를 넘거나 결제·로그인 핵심 흐름이 한 번이라도 재현 실패할 때 자동 승격을 멈춥니다. 데이터 호환이 유지된다면 이전 애플리케이션 버전으로 되돌리고, 파괴적 마이그레이션이 포함됐다면 롤백보다 기능 차단을 우선할 수 있습니다.

이 가상 배포는 오류율이 기준선 안에 있고 확인 대상 운영 URL에서 새 자산 해시가 일치할 때 끝납니다. 200 응답 하나가 아니라 커밋, 배포 식별자, 실제 URL, 자산 해시와 확인 시각이 산출물입니다.

완료 보고에서 빈칸이 하나라도 있으면 닫지 않는다

작업 상태는 다음 기록으로 재구성할 수 있어야 합니다.

운영 완료 기록의 최소 항목
commit: 승인된 변경 식별자
deployment: 운영 배포 식별자
url: 실제 확인한 HTTPS 주소
observed: 새 문구·링크·자산 해시
metrics: 배포 전후 오류율과 확인 구간
rollback: 이전 배포 또는 기능 차단 절차
unverified: 확인하지 못한 경로
owner: 이상 시 판단할 담당자

읽고 나서 확인하기

답을 떠올린 뒤 본문의 판단 기준과 비교해 보세요.

  • 코드 생성, 테스트 통과, 운영 배포를 서로 다른 완료 단계로 구분합니다.
  • 운영 URL과 핵심 흐름, 관찰 지표와 롤백 방법까지 확인해야 완료로 판정합니다.
  • 운영 확인이 불가능하면 완료가 아니라 미검증 상태로 보고합니다.

공식 출처