Claude Code에 본번 배포를 맡기기 전, 빈 손 점검 절차

금요일 저녁, 저는 Claude Code에게 “이 글 수정한 거, 본번에 올려놔” 하고 부탁했습니다. 돌아온 건 “게시했습니다”라는 한마디와 초록색 체크 표시. 안심하고 퇴근했더니, 다음 날 아침 사이트 첫 화면이 새하얗게 비어 있었습니다.

원인은 어처구니없는 것이었습니다. 미리보기를 아무도 열어보지 않았던 겁니다. Claude Code는 빌드가 통과한 로그만 보고 “성공”이라고 판단했습니다. 하지만 실제 페이지는 다른 글의 템플릿을 읽어 들이고 있어서 내용이 텅 비어 있었어요. HTTP는 200을 반환하니까 기계적으로는 “게시 성공”처럼 보였던 겁니다.

이때 절감한 건, 빠른 것과 안전한 것은 별개라는 사실입니다. 배포를 통째로 맡기면 한순간에 끝난 것처럼 보입니다. 하지만 무엇을 확인했는지가 남아 있지 않으면, 넘어진 뒤에 무엇을 되돌려야 할지 알 수가 없습니다. 오늘은 그 대책으로, 운영 권한을 넘기기 전에 “빈 손 점검(dry run)“으로 증거를 갖추는 절차를 적습니다.

핵심 요약

• Claude Code에 배포를 맡겼다가 나는 사고 대부분은, 본번에 손대기 전 확인을 건너뛴 것이 원인입니다.
• 운영 권한을 넘기기 전에 빌드·차이·미리보기 URL·롤백 담당·손대지 않은 범위, 이 다섯 가지를 빈 손으로 확인합니다.
• “기계가 판정할 수 있는 확인”과 “사람이 눈으로 보는 판단”을 나누면 한밤중 사고가 줄어듭니다.
• 복사해서 바로 쓸 수 있는 프롬프트 틀과, 확인 결과를 기계로 점검하는 코드를 함께 둡니다.
• 처음부터 완벽한 운영 규칙은 필요 없습니다. 수정 하나로 시험해 보고, 넘어진 자리를 체크리스트에 더해 갑니다.

배포 사고는 “똑똑함”이 아니라 확인 부족에서 생긴다

Claude Code는 똑똑합니다. 하지만 똑똑한 것과 본번에서 안전하게 움직이는 것은 다른 이야기입니다.

시험에서 만점을 받는 학생이 첫 아르바이트에서 계산대를 망가뜨리는 것과 같아서, 능력의 문제가 아니라 발판의 문제예요. 배포로 말하자면 발판이란 “본번에 손대기 전에 무엇을 확인할지”를 가리킵니다.

특히 정적 사이트 배포는 실패가 조용히 진행됩니다. 빌드가 통과하고 HTTP가 200을 반환하면, 겉보기에는 전부 잘된 것처럼 보입니다. 내용이 비어 있어도, 다른 페이지로 바꿔치기되어 있어도, 상태 코드만 보고 있으면 알아챌 수 없습니다. 그래서 “코드가 동작했는가”가 아니라 “올바른 페이지가 올바르게 나오고 있는가”를 사람 눈으로 한 번 봐야 합니다.

본번에 손대기 전, 빈 손 점검 5단계

제가 지금 쓰는 절차는 이게 전부입니다. 순서가 중요하므로 위에서 아래로 배열했습니다.

1. 먼저 로컬에서 빌드를 통과시킨다. 여기서 막히면 본번 이야기는 이르다. 코드 문제인지 환경 문제인지를 본번에 손대기 전에 가려냅니다.
2. 차이를 읽는다. 기밀 정보(API 키, 토큰)나 과금에 관련된 변경이 섞여 있지 않은지 눈으로 확인합니다.
3. 미리보기 URL을 연다. 제목(h1), 정규 URL(canonical), 신청 버튼의 이동 위치가 의도대로인지 실제 화면에서 확인합니다.
4. 롤백 담당과 되돌리는 방법을 정한다. 실패했을 때 누가, 어떤 명령으로 이전 상태로 되돌릴지. 이걸 먼저 정해 두지 않으면 사고가 난 순간 얼어붙습니다.
5. 증거가 갖춰진 뒤에 운영 권한을 부탁한다. 1부터 4까지의 결과가 나와야 비로소 Claude Code에 본번 배포를 의뢰합니다.

이 순서만 지켜도, 첫머리의 “첫 화면이 새하얗게” 사고는 거의 일어나지 않습니다. 왜냐하면 3에서 미리보기를 반드시 열기 때문입니다.

AI에 맡길 범위와, 사람이 판단할 범위

전부를 AI에 맡기는 것도, 전부를 손작업으로 되돌리는 것도 아닙니다. 역할을 나눕니다. 아래 표가 제 현장에서의 경계선입니다.

상황	Claude Code에 맡길 일	사람이 보는 증거
글 게시	dist 빌드와 게시 URL의 자동 점검을 먼저 돌린다	빌드 결과·차이·URL
신청 버튼 변경	링크 대상과 상담 동선을 미리보기에서 맞춰 본다	빌드 결과·차이·URL
Workers 수정	환경 변수를 건드리지 않고 빈 손 로그만 출력한다	빌드 결과·차이·URL

핵심은 읽기·정리하기·기계로 점검하기 같은 작업은 AI에 맡기고, 본번에 되돌릴 수 없는 변경을 가하는 조작은 사람이 승인한다는 구분입니다. 삭제, 운영 데이터베이스에 쓰기, 과금, force push는 처음에는 전부 “사람에게 묻기” 쪽으로 기울여 둡니다. 안전하다고 확인된 조작만 나중에 자동으로 승격하면 됩니다.

권한 경계선을 더 세밀하게 정하고 싶은 분에게는 Claude Code 권한 설정 가이드와 배포 전 권한 감사가 참고가 됩니다.

복사해서 쓰는 프롬프트 틀

의뢰를 통째로 던지지 말고, “아직 본번에는 내보내지 마”라고 명시하는 게 요령입니다. 다음 틀을 그대로 붙여서 쓸 수 있습니다.

이 변경을 본번에 배포하기 전의 "빈 손 점검 체크리스트"로 변환해 주세요.
다음 항목을 표로 돌려주세요.
- 빌드 결과(성공 / 실패와 로그의 요점)
- 차이의 위험(기밀 정보·과금·삭제가 포함되는가)
- 미리보기 URL
- 롤백 담당과 롤백 명령
- 손대지 않은 영역
- 재시도 조건
본번 배포는 아직 실행하지 마세요. 제가 점검을 확인할 때까지 기다려 주세요.

마지막 두 줄이 효과를 냅니다. “아직 실행하지 마”, “내가 확인할 때까지 기다려”라고 적어 두면, Claude Code가 알아서 눈치껏 멋대로 게시해 버리는 사고를 막을 수 있습니다. 프롬프트로 안전한 쪽으로 기울이는 작성법은 상급자용 프롬프트 설계에도 정리해 두었습니다.

복사해서 동작하는 검증 스크립트

확인 결과를 “사람의 감각”이 아니라 기계로 판정하면 놓치는 일이 줄어듭니다. 다음 스크립트는 빈 손 점검의 결과 객체를 받아, 운영 권한을 부탁해도 되는 상태인지를 참/거짓으로 돌려줍니다. Node.js가 있으면 그대로 동작합니다.

// 빈 손 점검의 결과. 실제 확인 내용을 여기에 넣는다
const deployCheck = {
  build: "passed",              // 로컬 빌드가 통과했는가
  diffReviewed: true,           // 차이를 눈으로 확인했는가
  previewUrl: "https://example.pages.dev", // 미리보기 URL
  rollbackOwner: "Masa",        // 롤백 담당
  changedAreas: ["content", "cta-copy"],   // 손댄 범위
};

// 운영 권한을 부탁해도 되는 상태인지 판정하는 문지기
function canRequestProductionAccess(check) {
  return (
    check.build === "passed" &&          // 빌드가 통과했다
    check.diffReviewed &&                // 차이를 봤다
    /^https:\/\//.test(check.previewUrl) && // 미리보기 URL이 https로 존재한다
    check.rollbackOwner.length > 0 &&    // 롤백 담당이 정해져 있다
    !check.changedAreas.includes("secrets") // 기밀 영역을 건드리지 않았다
  );
}

const ready = canRequestProductionAccess(deployCheck);
console.log({ ready });
// ready가 false인 항목을 채울 때까지 본번 배포는 부탁하지 않는다

이 코드의 값어치는 changedAreas에 "secrets"가 들어간 순간 false를 반환하는 데 있습니다. 기밀 정보를 무심코 건드린 상태에서는 절대로 운영 권한 의뢰까지 진행되지 않습니다. 사람이 바빠서 놓쳐도 문지기가 멈춰 줍니다.

실제로 효과를 본 세 가지 장면

첫 번째는 글 게시. “블로그 올려놔”만 던지면 빌드가 통과한 시점에 게시까지 달려갑니다. 빈 손 점검을 끼워 넣으면 게시 URL을 열어 제목과 내용이 일치하는지를 먼저 보기 때문에, 첫머리의 백화면 사고가 멈춥니다.

두 번째는 신청 버튼 교체. 링크 대상을 한 글자 잘못 입력한 것만으로 애써 만든 동선이 404로 떨어집니다. 미리보기에서 버튼을 실제로 눌러 이동 위치를 확인하는 절차를 넣고 나서, 링크 끊김이 0이 됐습니다.

세 번째는 Cloudflare Workers 수정. 여기는 환경 변수를 하나 지우는 것만으로 본번이 죽습니다. 그래서 빈 손 점검에서는 환경 변수를 건드리지 않게 하고 로그만 출력하게 합니다. Workers 특유의 주의점은 Cloudflare Workers 연동 글에도 정리해 두었습니다.

흔히 빠지는 함정과 고치는 법

제가 실제로 저지른 실패와, 그 고치는 법을 셋.

함정 1: 빌드 전에 본번 명령을 친다. 다짜고짜 wrangler deploy를 돌리면, 실패했을 때 코드가 나쁜지 환경이 나쁜지 가려낼 수 없습니다. 고치는 법은 단순합니다. 로컬 빌드를 반드시 먼저 통과시킬 것. 순서 하나만 바꿔도 원인 규명이 단숨에 빨라집니다.

함정 2: 롤백 담당을 정하지 않았다. 실패하고 나서 “누가 되돌려?”를 의논하기 시작하면, 그 몇 분 사이에 접속이 직격을 받습니다. 고치는 법은 빈 손 점검 단계에서 롤백 담당과 롤백 명령을 글자로 적어 두는 것. previousDeployId를 적어 두는 것만으로도 복구가 차분해집니다.

함정 3: 미리보기를 열지 않고 상태 코드만 믿는다. HTTP 200은 “서버가 뭔가 반환했다”일 뿐, “올바른 페이지가 나왔다”가 아닙니다. 고치는 법은 미리보기 URL을 반드시 한 번 브라우저로 열어 제목과 정규 URL과 히어로 이미지를 눈으로 보는 것. 이것이 첫머리의 백화면을 알아채는 유일한 방법이었습니다.

증거를 “다음에도 쓸 수 있는 메모”로 남긴다

빈 손 점검으로 확인한 것은 그 자리에서 지우지 말고 짧은 메모로 정리해 두면, 다음 작업이 한결 빨라집니다.

남기는 건 이 정도면 충분합니다. 처음에 낸 의뢰문, Claude Code가 읽은 범위, 건드리지 않은 범위, 실행한 확인 명령, 게시 URL이나 스크린샷, 판단에 망설인 점. 긴 회의록은 필요 없습니다. 나중에 “왜 이 판단을 했는지”를 따라갈 수 있으면 목적은 달성입니다.

특히 효과적인 것이 “판단의 갈림길”을 한 줄로 적는 것입니다. 예를 들어 “미리보기 URL은 올바르지만 롤백 담당이 미설정이라 본번은 아직”처럼 적어 둡니다. 다음에 같은 작업을 할 때, 나 자신이든 다른 사람이든 같은 확인을 재현할 수 있습니다. 배포 이외의 자동화에도 같은 사고방식을 쓸 수 있으니, 비엔지니어를 위한 Claude Code 입문과 함께 읽으면 맡기는 감각을 잡을 수 있을 겁니다.

자주 묻는 질문

Q. 빈 손 점검이라는 거, 결국 그냥 손이 더 가는 것 아닌가요? 처음에는 그렇게 느껴집니다. 하지만 사고가 한 번 나면 복구와 원인 규명에 몇 시간이 녹습니다. 빈 손 점검은 몇 분. 수지 맞는 보험이라고 생각하고 계속하고 있습니다.

Q. 로컬 빌드가 통과하면 미리보기는 안 봐도 되나요? 안 됩니다. 빌드가 통과해도 템플릿 바꿔치기나 빈 페이지는 일어납니다. HTTP 200과 “올바른 페이지”는 별개이므로, 눈으로 보는 건 생략할 수 없습니다.

Q. 롤백 담당을 혼자라도 정하는 의미가 있나요? 있습니다. 혼자라도 “실패하면 이 명령으로 되돌린다”라고 먼저 글자로 적어 두면, 막상 사고 났을 때 망설이지 않습니다. 정하는 것 자체가 절차가 됩니다.

Q. Claude Code가 “게시했습니다”라고 하면 믿어도 되나요? 답변 그 자체보다 빈 손 점검의 증거를 보세요. 빌드·차이·미리보기·롤백 담당이 갖춰져 있는지로 판단합니다. 말은 분위기, 증거는 사실입니다.

Q. 작은 사이트라도 여기까지 할 필요가 있나요? 규모보다 “되돌릴 수 있는가”로 생각하세요. 작아도 본번이 죽으면 곤란합니다. 우선은 미리보기를 여는 한 단계만이라도 넣으면 효과를 실감할 수 있습니다.

실제로 시험해 본 결과

첫머리의 백화면 사고 이후, 저는 이 빈 손 점검 절차를 제 블로그 운영에 끼워 넣었습니다.

확인한 건 세 가지입니다. 첫째, 미리보기 URL을 반드시 여는 규칙으로 했더니, 템플릿 바꿔치기로 인한 빈 페이지가 0이 됐습니다. 둘째, 위의 검증 스크립트를 게시 전에 돌리게 했더니, 기밀 영역을 건드린 변경이 ready: false에서 멈춰서 운영 권한 의뢰까지 진행되지 않게 됐습니다. 셋째, 롤백 담당과 롤백 명령을 매번 메모하게 했더니, 아찔했던 장면에서도 몇 분이면 이전 상태로 되돌릴 수 있게 됐습니다.

똑똑한 AI에 전부 맡기고 기도하기보다, 넘어져도 다치지 않는 발판을 먼저 만든다. 돌아가는 것처럼 보여도 이게 결국 가장 빠르다, 라는 게 지금의 실감입니다. 우선은 미리보기를 여는 한 단계부터, 자신의 배포에 문지기를 더해 보세요.

팀에서 본번 배포의 경계선이나 리뷰 체제까지 갖추고 싶은 경우에는 연수·상담에서 함께 절차로 만들 수 있습니다. 공식 운영 기준은 Anthropic 공식 Claude Code 문서도 참조해 주세요.