재현 없이 가설 없다 — 배포 6섹션 65항목과 디버깅 4 Phase

체크리스트가 65개라는 사실보다 중요한 것은 그 65개를 매번 다 하지 않는다는 것이다. 여섯 섹션의 점검 주기가 각각 다르고, 그 주기를 모르면 체크리스트는 첫 배포에 한 번 쓰이고 버려진다.

이 글은 3계층 통제로 시작한 시리즈의 마지막 편이다. 앞 편이 하나를 만들어 한 번 내보내는 데까지였다면, 이 글은 그 뒤 — 매번 내보낼 때 무엇을 확인하고, 터졌을 때 무엇부터 하는가다.

이 글에서 가장 오래 남는 규율은 원 자료가 "The Iron Law"라 이름 붙인 한 줄이다. 재현 없이 가설 없다. 가설 없이 수정 없다. 수정 후 회귀 테스트 없이 완료 없다.

이 글이 옮긴 원 자료의 작성 기준일은 2026-07-26이다. 성능 지표 이름과 기준값, 플랜별 타임아웃은 그 시점의 것이다.

아래의 65항목·13행 함정 카탈로그·10패턴·MCP 6종은 원 자료가 제시한 예제이며, 이 글이 운영해 얻은 실적이 아니다. 특히 디버깅 절의 시간·성공률 비교는 예시 값이다 — 해당 표 아래에 원 자료의 고지를 옮겨 두었다.

용어 정리

시리즈 첫 편의 용어표 31행 중 이 글이 쓰는 행만 추렸다.

git bisect·auth.uid()·service_role·anon 은 아래 본문이 영문 이름 대신 「이진 탐색」·「인증 함수」·「관리자 키」·「공개 키」라는 한국어로만 쓴다. 그래도 행을 남겼다 — 다른 자료에서는 영문 이름으로 나오기 때문이다.

배포 체크리스트 6섹션 65항목

15 + 10 + 12 + 8 + 10 + 10 = 65. 여섯 행의 항목 수를 더하면 제목의 숫자와 맞는다.

체크리스트를 대하는 태도: "모든 항목을 매 배포마다 한다"는 뜻이 아니다.

13섹션은 매 배포, 4섹션은 사고 시, 56섹션은 정기 점검이다.

자료의 조언은 "외우려 하지 말고 첫 배포 때 출력해 옆에 두고 따라가라. 두세 번 반복하면 몸이 외운다"이다.

「점검 빈도」 열을 흐름으로 옮기면 이렇게 된다.

이 흐름도는 이 글이 새로 그린 것이다. 세 갈래의 근거는 전부 위 표와 아래 롤백 판단 기준 표에 있다 — 1~3섹션의 순서는 「시점」 열의 배포 전·중·후이고, 3에서 4로 가는 조건과 옆으로 빠지는 조건은 롤백 판단 기준 표의 「즉시」 네 행과 「시간 두고 핫픽스」 두 행이며, 5·6섹션이 별도 줄기인 것은 원 자료가 "13섹션은 매 배포, 4섹션은 사고 시, 56섹션은 정기 점검" 이라고 직접 적은 문장이다.

Pre-Deploy 15항목

열다섯 항목 중 열넷은 「통과 기준」이 온전히 판정 가능한 값이다 — 0건 · 차이 없음 · 결과 없음 · 종료코드 0. "확인했다"로 끝나는 칸이 없다는 것이 이 표가 체크리스트로 기능하는 이유다. 예외는 1.3 하나다 — "전부 통과, 커버리지 80% 이상 권장" 에서 앞은 판정 가능하지만 뒤의 「권장」은 통과·실패를 가르지 않는다. 한 칸에 기준과 권고가 함께 들어간 자리는 열다섯 중 이것뿐이다.

Deploy 10항목

2.4가 유일하게 상대 기준을 든다 — "평소의 2배 이상이면 캐시 문제 의심". 절대값(5분)과 추세 비교를 한 칸에 함께 둔 항목은 이 열 개 중 이것뿐이다.

Post-Deploy 12항목

3.11이 이 체크리스트에서 가장 중요한 항목이다. 기술 지표(에러율·응답시간)가 정상인데 전환율만 떨어지는 배포가 존재한다. 원 자료는 여기에 "에러 없이 실패하는 배포를 잡는 유일한 항목이 KPI 비교다" 라고 적는데, 같은 표의 3.12(고객 문의 모니터링)도 에러 없이 걸린다 — "안 된다" 류 문의가 늘었다는 신호에 에러 로그가 필요하지 않기 때문이다. 에러 없이 실패하는 배포를 잡는 항목은 둘이고, 3.11이 그중 자동으로 재는 쪽이다.

열두 항목이 「분류」 열에서 Smoke 5 · 모니터링 3 · 공지 2 · 24h 2로 갈린다. 앞의 여덟은 배포 직후에 끝나고, 뒤의 넷 중 둘(3.11·3.12)만 다음 날까지 열려 있다.

Rollback — 판단 기준과 절차

원칙: 고치는 것보다 되돌리는 게 빠르다. 목표는 5분 내 롤백이다.

장애 중에 원인을 찾겠다는 판단이 장애 시간을 몇 배로 늘린다.

⚠️ 이 섹션은 표가 둘인데 항목 수는 여덟이다

롤백 섹션에는 표가 두 개 있다 — 판단 기준 6행과 절차 8행. 6 + 8 = 14로 세면 안 된다.

위 6섹션 표가 Rollback의 항목 수를 8로 적었고, 번호도 절차 표에만 4.1~4.8로 붙어 있다. 판단 기준 표의 여섯 행에는 번호가 없다 — 그것은 체크할 항목이 아니라 절차에 들어갈지 말지를 가르는 문이다.

검산이 가능하다. 14로 세면 15 + 10 + 12 + 14 + 10 + 10 = 71이 되어 65와 맞지 않는다. 이 검산은 이 글의 정리이며, 원 자료는 6섹션 표에 8을 적어 둘 뿐 두 표의 관계를 따로 설명하지 않는다.

4.4의 「강제 푸시 금지」는 이 시리즈 첫 편의 차단 규칙 7종 중 5번(git push --force + main|master)과 같은 것을 막는다. 한쪽은 사람이 지킬 절차로, 다른 쪽은 훅이 강제하는 규칙으로 적혀 있다.

보안 10항목

시크릿 3 · RLS 3 · 전송 3 · 인가 1로 갈린다. 「인가」 분류에만 항목이 하나인 것은 나머지 인가 판정이 RLS 세 항목으로 DB 쪽에 내려가 있기 때문이다 — 5.4~5.6이 「누가 무엇을 읽을 수 있는가」를 이미 맡고 있고, 5.10은 그것으로 덮이지 않는 화면 단위 접근을 맡는다. 이렇게 갈라 읽는 것은 이 글의 정리이며, 원 자료는 「분류」 열에 네 이름을 붙일 뿐 항목 수가 왜 3·3·3·1인지 적지 않는다.

성능 10항목

⚠️ 6.3의 지표 이름이 이 글 안의 다른 자리와 다르다

이 글 맨 앞의 용어 정리는 Core Web Vitals를 LCP·FID(INP)·CLS 로 적어 INP를 괄호로 병기한다. 위 6.3행은 FID 만 적는다. 같은 원 자료 안의 두 자리다.

Core Web Vitals는 원 자료가 만든 것이 아니라 공개된 웹 표준 지표이므로 지표 이름을 그대로 옮긴다 — 병기된 쪽의 이름이 INP다.

이 글이 확인할 수 있는 것은 원 자료가 용어 풀이에서는 FID(INP)로 병기하고 체크리스트에서는 FID만 적는다는 사실과, 그것이 2026-07-26 기준이라는 것까지다. 어느 이름이 현재 표준의 것인지는 표준 문서를 직접 확인해야 한다.

6.9와 6.10만 분류가 「DB」다. 나머지 여덟이 브라우저에 도착한 뒤의 문제인 반면 이 둘은 응답을 만들기 전의 문제다.

자주 만나는 배포 실패

같은 증상이 클러스터 위에서 나면 원인이 하나 더 붙는다 — 생존 프로브와 준비 프로브를 혼동하면 무한 재시작이나 5xx가 된다.

디버깅 — 절대 원칙과 4 Phase

The Iron Law

재현 없이 가설 없다. 가설 없이 수정 없다. 수정 후 회귀 테스트 없이 완료 없다.

원 자료는 감에 의존한 디버깅과 체계적 디버깅을 다음과 같이 대조한다.

위 표에 대한 원 자료의 고지 — 원 자료는 이 표를 소개하는 문장에 이어 이 수치가 예시 값이며 실측 벤치마크가 아니라고 못 박는다.

이 표는 4행 × 2열 = 여덟 칸이고, 그중 여섯이 그 수치다. 나머지 둘(「흔함」·「거의 없음」)은 수치가 아니라 빈도 서술이다. 여섯 수치 어느 것도 어느 팀이 측정한 결과가 아니라 두 방식을 대조하기 위해 제시된 예시이며, 이 글도 이 수치를 측정한 적이 없다.

Phase 1 — 재현

"재현하지 못하면 고치지 못한다." 가장 흔한 함정은 "가끔 나오는 거라서"라며 추측으로 수정하는 것이다. 결과는 항상 같다 — 수정 후에도 가끔 나온다.

에러 메시지 읽는 법

에러 메시지의 90%는 답을 들고 있는데, 대부분 마지막 줄만 본다. 첫 4줄에서 얻을 수 있는 정보는 다음과 같다.

스택 트레이스는 위에서 아래로 읽되, 본인 코드가 처음 나오는 지점에서 멈춘다. 프레임워크·라이브러리 내부 스택은 건너뛴다. 원인은 거의 항상 그 첫 지점에 있다.

증상·원인·해결·예방 카탈로그

네 개의 스택 구간으로 나뉜 13행이다.

TypeScript

React

프레임워크 (SSR)

DB / 인증

3 + 3 + 3 + 4 = 13행이다. DB / 인증만 네 행이고 나머지 셋은 세 행씩이다.

마지막 행(정책 평가가 느림)이 앞 편의 「정책 작성에서 놓치기 쉬운 4가지」 마지막 행과 같은 문제다. 거기서는 정책을 처음 쓸 때 피하는 방법으로, 여기서는 이미 느려진 뒤 찾는 증상으로 적혀 있다.

⚠️ 이 카테고리의 다른 글이 같은 이름의 4단을 쓴다 — 행을 하나씩 대조했다

3계층으로 좁히고 4단으로 분해한다 편은 "모든 장애를 증상 → 원인 → 해결 → 예방 4단으로 분해한다" 고 쓴다. 네 축의 이름이 위 네 표의 열 이름과 정확히 같다. 이름이 같으니 카탈로그도 겹치는지 세어 봐야 한다.

그 글에는 같은 네 열을 가진 표가 둘 있다 — **공통 문제 10선(10행)**과 현장 장애 5건(5행), 합 15행이다. 위 13행과 대조한 결과를 적는다.

	값
그 글의 4단 표 행 수	10 + 5 = 15
이 글의 카탈로그 행 수	3 + 3 + 3 + 4 = 13
양쪽에서 같은 증상을 다루는 행	0

겹치지 않는 이유는 다루는 대상이 다르기 때문이다. 그 글의 15행은 에이전트를 운영할 때 나는 장애다 — 도구 연동 실패, 컨텍스트 한도 초과, 훅 무한 루프, 권한 거부, 인증 충돌, 경로 확장 오류, 비용 폭주, 검토 없는 자동 커밋, 응답 품질 저하 같은 것들이다. 위 13행은 애플리케이션 코드의 버그다 — 타입 무력화, 리렌더, 하이드레이션 불일치, 정책 오설정.

가장 가까이 붙는 한 쌍이 RLS다. 그런데 그 한 쌍조차 증상이 정반대다. 그 글의 사례는 "행 단위 보안을 켰는데 모든 인증 사용자가 전체 행 접근 가능, 30분간 노출" 이고 원인은 조건식을 USING (true)로 쓴 것이다. 위 표의 첫 DB 행은 "에러는 없는데 빈 배열이 반환됨" 이고 원인은 정책이 아예 없어 전부 차단된 것이다. 전부 열린 것과 전부 막힌 것이라 해결도 반대 방향으로 간다.

따라서 두 자료가 공유하는 것은 「증상→원인→해결→예방」이라는 분해 틀이고, 그 틀에 넣은 목록은 서로 다른 집합이다. 이 대조는 이 글의 정리이며, 두 카탈로그를 행 단위로 맞춰 보고 센 결과다.

MRE — 최소 재현 케이스

MRE의 부가 효과가 본래 효과보다 크다.

• 만드는 도중에 원인을 찾는 경우가 약 60%. 절반씩 지우는 과정 자체가 이진 탐색이다.
• 외부에 질문할 때 그대로 재사용 가능하다.
• Phase 4의 회귀 테스트 기반 코드로 그대로 전환된다.

세 효과 중 마지막 하나 때문에 MRE는 만든 구간에서 끝나지 않고 Phase 4의 입력이 된다. 다만 MRE가 어느 Phase의 것인지는 원 자료가 한 곳에만 적어 두었다 — 뒤에 싣는 디버깅 체크리스트가 「MRE를 50줄 이하로 만들었다」를 Phase 3(검증) 에 배정하고, 위의 4 Phase 흐름도에는 MRE 노드가 아예 없다. 앞뒤를 잇는 산출물도 MRE 하나가 아니다 — Phase 1의 재현 시나리오 역시 Phase 4에서 "재현 시나리오를 테스트로 고정한 뒤 종료" 로 다시 쓰인다. MRE를 Phase 3 → Phase 4의 다리로 읽는 것은 이 글의 정리다.

5-Why — 근본 원인까지

3-Why까지만 가면 표면 수정, 5-Why까지 가야 재발 방지다. 자료의 예시를 구조만 남기면 다음과 같다.

「답변 성격」 열이 증상 → 코드 → 로직 → 관행 → 시스템으로 올라간다. 다섯 단계 중 앞의 셋은 그 파일 안에서 답이 나오고, Q4부터 답이 파일 밖으로 나간다.

Q5에 도달하면 답이 코드가 아니라 규칙·게이트로 바뀐다. 이 전환이 5-Why의 목적이며, 이 시리즈 첫 편의 Rules·Hooks 계층이 존재하는 이유이기도 하다.

회귀 버그 — 이진 탐색

"어제까지 됐는데 오늘 안 된다"에는 이진 탐색이 정답이다. 100개 커밋을 하나씩 확인하면 100회, 절반씩 좁히면 7회다.

범인 커밋을 찾은 뒤에는 "이 커밋의 어느 변경이 원인인가 / 최소 수정은 무엇인가 / 같은 패턴이 다른 곳에도 잠복해 있는가" 세 가지를 함께 확인한다. 세 번째 질문이 재발을 막는다.

디버거 사용 — console.log를 대체하는 3가지

세 기법의 「이점」 열이 공통으로 말하는 것은 코드를 건드리지 않는다는 것이다. 출력문을 박아넣는 방식은 디버깅 흔적이 코드에 남고, 그 흔적을 지우다가 다른 것이 지워진다.

디버깅 프롬프트 10패턴

공통 설계: 10패턴 중 셋이 "무엇을 하지 말 것"을 함께 지시한다 — 5번(우회 캐스팅 금지) · 6번(임시방편 플래그 사용 금지 명시) · 10번(환경변수 값 노출 금지)이다. 급할 때 가장 손이 가는 선택지를 프롬프트 단계에서 미리 봉쇄하는 자리이며, 나머지 일곱 칸은 금지가 아니라 무엇을 함께 넣을 것인가를 요구한다.

그 마지막 금지(환경변수 값 노출)는 이 시리즈 첫 편의 차단 규칙 7번(echo/cat/printf + 시크릿 환경변수명)이 훅으로 강제하는 것과 같은 사고를 막는다. 한쪽은 프롬프트에 적는 지시이고 다른 쪽은 프로세스가 거부하는 게이트다.

디버깅 체크리스트

네 Phase의 소요가 5 + 10 + 15 + 10 = 40분이다. 가장 긴 구간이 Phase 3(검증)이고, Phase 1(재현)이 가장 짧다. 2단계의 「프롬프트 4요소를 채웠다」는 목적·맥락·제약·형식을 말하며, 그 정의는 .claude 디렉터리와 프롬프트 7패턴 편에 있다.

절대 금지 6가지

"수정 3번 실패 = 아키텍처 문제"

같은 가설로 세 번 고쳤는데 다른 곳에서 계속 터진다면, 그것은 버그가 아니라 설계 문제다.

징후는 셋이다. 한 곳을 고치면 다른 곳이 깨진다 / 매번 범위가 커진다 / "대대적인 리팩토링이 필요하겠는데" 생각이 든다.

여섯 금지 중 「에러를 빈 catch로 삼키기」는 이 시리즈 첫 편의 Rules 5종에도 같은 조항으로 있다 — logging.md의 "에러를 잡고 삼키지 말 것. 로깅 후 재throw 또는 명시적 fallback" 이 그것이다. 첫 편의 Rules 두 표에는 타입 무력화를 금하는 조항도, 디버그 출력문을 금하는 조항도 없다.

도구 확장 계층 — MCP 6종

에이전트가 다룰 수 있는 범위를 넓히는 것이 MCP다. 원 자료는 6종을 한 번에 등록하는 설치 스크립트를 두고 있으나 그 코드를 본문에 싣지 않고, 어떤 축으로 6종을 골랐는가만 남긴다. 이 글이 옮기는 것도 그 선정 축이다.

아래 6종과 선정 이유는 원 자료가 제시한 구성이며, 이 글이 6종을 연동해 운영한 기록이 아니다.

운영 관점의 관전 포인트 3가지

• 읽기 전용 기본값: DB MCP를 --read-only로 등록하고, 쓰기가 필요할 때만 옵션을 푼다. 기본값이 안전한 쪽이어야 한다.
• 권한 스코프 최소화: OAuth 스코프를 필요한 것만 나열해 발급한다. 나중에 필요해지면 재인증으로 늘린다.
• 설정 변경 전 자동 백업: 설치 스크립트가 설정 파일을 타임스탬프 백업(권한 600)한 뒤에만 수정한다. 롤백 경로를 먼저 만든다.

여섯 종의 「인증 방식」 열이 OAuth 2 · 토큰 1 · 불필요 2 · 선택적 키 1로 갈린다. 인증 없이 붙는 셋(Context7·Playwright·YouTube Transcript)은 연결 대상이 우리 데이터가 아니라는 공통점이 있고, 그중 Context7만 키가 선택 사항으로 붙는다 — 원 자료가 "익명 사용 가능, 키는 rate limit 상향용" 이라 적었기 때문이다.

MCP를 도구 하나가 점유하는 토큰 예산의 문제로 보는 관점은 이 카테고리의 MCP 도입은 기능 추가가 아니라 예산 배분이다 편이 따로 다뤘다. 그 글은 같은 6종을 다루면서 스코프 계층과 마켓플레이스 선별 기준까지 내려간다.

시리즈를 닫으며

네 편이 다룬 것을 한 줄씩 적으면 이렇게 된다.

마지막 행이 시리즈를 닫는 자리다. 5-Why를 Q5까지 밀면 답이 코드가 아니라 규칙과 게이트로 바뀌고, 그 규칙과 게이트가 첫 편의 Rules와 Hooks다. 디버깅에서 시작한 질문이 통제 계층으로 돌아온다.