AI가 코드를 빠르게 만들수록 장애 대응의 병목은 코딩 속도가 아니라 판단 속도가 됩니다. 배포 직후 결제 버튼이 멈추거나, Q&A 답변이 생성되지 않거나, 특정 브라우저에서 화면이 깨졌을 때 무작정 AI에게 '고쳐줘'라고 말하면 상황은 더 복잡해질 수 있습니다. AI는 로그의 일부만 보고 성급한 원인 가설을 만들고, 운영자는 그럴듯한 패치를 배포하다가 같은 장애를 반복할 수 있습니다.

이 글의 문제는 하나입니다. 'AI가 만든 변경 때문에 운영 문제가 생겼을 때, 사람 운영자는 어떤 순서로 증거를 모으고 AI에게 맡겨야 안전하게 복구할 수 있는가'입니다. 답은 AI를 디버깅 담당자로 쓰되, 장애 지휘관으로 쓰지 않는 것입니다. 사람은 사용자 영향, 롤백 기준, 배포 범위, 검증 조건을 결정하고, AI는 증거 패킷을 바탕으로 재현·원인 가설·수정 후보·회귀 테스트를 빠르게 만드는 역할을 맡아야 합니다.

핵심 결론

AI 장애 디버깅 런북의 핵심은 '수정 요청'보다 먼저 '증거 패킷'을 만드는 것입니다. 증거 패킷은 재현 경로, 사용자 영향, 최근 변경, 로그, 브라우저 콘솔, 네트워크 응답, 관측 지표, 타임라인, 롤백 기준을 한곳에 모은 작은 사건 파일입니다. 이 패킷이 있어야 AI가 상상으로 코드를 고치지 않고 실제 증상에 맞춰 작업합니다.

운영 중에는 다음 순서를 고정하세요.

1. 증상을 한 문장으로 잠급니다.
2. 사용자 영향과 심각도를 먼저 판단합니다.
3. 재현 경로와 실패 조건을 기록합니다.
4. 최근 배포·설정·데이터 변경 타임라인을 만듭니다.
5. 로그, 브라우저 콘솔, HTTP 상태, 관측 지표를 모아 증거 패킷으로 정리합니다.
6. 롤백 기준을 먼저 결정한 뒤 AI에게 원인 가설과 최소 수정안을 요청합니다.
7. 수정은 회귀 테스트와 라이브 스모크를 통과한 뒤에만 배포합니다.
8. 복구 뒤에는 원인, 감지 지연, 예방 테스트를 남깁니다.

초보자에게는 '문제가 생기면 바로 고치려 하지 말고, 의사에게 증상을 설명하듯 기록부터 만든다'고 이해하면 됩니다. 실무자에게는 'AI 에이전트에게 incident commander 권한을 주지 않고, evidence-driven debugging worker로 제한하는 운영 패턴'입니다.

왜 중요한가

AI는 빠르지만 사건의 우선순위를 모른다

AI는 코드와 로그를 읽고 원인 후보를 빠르게 냅니다. 그러나 현재 몇 명의 사용자가 영향을 받는지, 결제나 로그인처럼 사업적으로 중요한 흐름인지, 지금은 롤백이 나은지 핫픽스가 나은지까지 자동으로 알 수 없습니다. 운영자가 이 판단을 넘겨버리면 AI는 '가능한 수정'을 제안하지만 '지금 해야 할 수정'을 보장하지 못합니다.

장애 상황에서 흔한 실패는 다음과 같습니다.

AI 코딩에서 장애 대응은 '프롬프트 실력'보다 '증거 설계'가 중요합니다. 같은 에러라도 증거 패킷이 있으면 AI는 작은 수정과 테스트를 제안하지만, 증거가 없으면 대규모 리팩터링이나 무관한 설정 변경을 제안할 가능성이 커집니다.

운영 장애는 코드 문제가 아니라 시간 문제다

장애 대응에서 가장 비싼 자원은 개발자의 손이 아니라 시간입니다. 사용자는 지금 실패하고 있고, 운영자는 제한된 정보로 결정을 내려야 합니다. 그래서 런북은 완벽한 분석 문서가 아니라 빠른 의사결정 장치여야 합니다. 5분 안에 심각도와 롤백 후보를 잡고, 15분 안에 재현 가능 여부를 확인하고, 30분 안에 롤백 또는 핫픽스 방향을 정하는 식으로 시간을 끊어야 합니다.

AI는 이 시간 압박을 줄일 수 있습니다. 로그 요약, 의심 커밋 후보 정리, 테스트 초안 작성, 재현 스크립트 생성, 변경 diff 리뷰를 빠르게 도와줍니다. 그러나 AI가 시간을 줄이려면 입력이 구조화되어 있어야 합니다. '뭔가 안 돼'가 아니라 '어떤 사용자에게, 어떤 경로에서, 언제부터, 어떤 증거로 실패하는가'가 필요합니다.

실제 작업 순서

1단계: 증상을 한 문장으로 고정한다

장애 대응의 첫 문장은 짧아야 합니다. 예를 들어 '모바일 Safari에서 VIBE 코딩 상세 글 진입 시 본문이 비어 보인다', '배포 후 Q&A 질문 제출은 200이지만 공개 목록에 나타나지 않는다', '로그인한 사용자만 결제 완료 페이지에서 500을 본다'처럼 씁니다. 이 문장이 흔들리면 AI에게 전달하는 작업 범위도 흔들립니다.

좋은 증상 문장은 다음 네 요소를 포함합니다.

• 영향을 받는 사용자 또는 환경
• 실패하는 행동
• 관찰된 결과
• 언제부터 또는 어떤 변경 뒤에 발생했는지

나쁜 문장은 '사이트가 이상함', 'AI가 만든 코드가 깨짐', '배포 후 오류'처럼 넓습니다. 이런 문장은 AI가 원인 후보를 너무 넓게 잡게 만들고, 불필요한 파일까지 수정하게 만듭니다.

2단계: 사용자 영향과 심각도를 먼저 나눈다

모든 장애가 같은 속도로 대응되어야 하는 것은 아닙니다. 결제 실패, 로그인 불가, 데이터 손실, 관리자 기능 노출, 공개 페이지의 민감정보 노출은 즉시 롤백 후보입니다. 반면 특정 카드의 줄바꿈 문제나 낮은 우선순위의 이미지 로딩 실패는 핫픽스 준비 시간을 조금 더 가질 수 있습니다.

간단한 분류 기준은 다음과 같습니다.

AI에게는 이 등급을 반드시 알려야 합니다. P0에서 AI가 장기 리팩터링을 제안하면 틀린 방향입니다. P2에서 즉시 롤백을 제안하는 것도 과할 수 있습니다. 심각도는 기술 문제가 아니라 운영 결정입니다.

3단계: 재현 경로를 최소 단위로 만든다

재현 경로는 AI가 문제를 실제로 좁히는 데 가장 큰 도움을 줍니다. 좋은 재현 경로는 '홈에서 시작 → 검색어 입력 → 결과 카드 클릭 → 상세 진입 → 콘솔 오류 확인'처럼 사용자가 따라 할 수 있는 행동 단위로 적습니다. 가능하면 브라우저, 화면 크기, 로그인 상태, 데이터 조건도 포함합니다.

재현이 항상 가능한 것은 아닙니다. 간헐적 오류라면 재현률을 숫자로 적습니다. 예를 들어 '10회 중 3회 실패', '큰 이미지가 포함된 글에서만 실패', '모바일 네트워크에서 더 자주 실패'처럼 기록합니다. AI에게는 재현률도 중요한 신호입니다. 100% 재현 오류는 단위 테스트나 라우트 테스트로 잡기 쉽지만, 간헐적 오류는 타임아웃, 캐시, 경쟁 조건, 외부 API 지연을 의심해야 합니다.

4단계: 타임라인과 최근 변경을 연결한다

장애는 대부분 최근 변경과 가까이에 있습니다. 타임라인은 다음 항목을 짧게 나열하면 충분합니다.

• 마지막 정상 확인 시각
• 첫 실패 감지 시각
• 최근 배포 커밋 또는 콘텐츠 변경
• 설정 변경 또는 외부 서비스 변경
• 데이터 동기화 또는 배치 실행 시각
• 임시 조치와 그 결과

AI에게 타임라인을 주면 '이 파일을 고쳤기 때문일 수 있다'는 가설을 세우기 쉬워집니다. 반대로 타임라인이 없으면 AI는 전체 코드베이스를 훑으며 넓은 추측을 하게 됩니다. 장애 대응에서는 넓은 추측보다 좁은 가설이 더 안전합니다.

5단계: 증거 패킷을 만든다

증거 패킷은 AI에게 넘길 수 있는 최소 사건 자료입니다. 형식은 복잡할 필요가 없습니다. 다음 순서로 적으면 됩니다.

• 증상 한 문장
• 심각도와 사용자 영향
• 재현 경로와 재현률
• 기대 결과와 실제 결과
• 최근 변경 타임라인
• 관련 로그 요약
• 브라우저 콘솔 오류 요약
• HTTP 상태와 응답 특징
• 관측 지표 변화
• 이미 시도한 조치
• 롤백 기준
• AI에게 맡길 작업 범위

여기서 중요한 것은 민감한 값을 넣지 않는 것입니다. 로그에는 사용자 식별자, 내부 엔드포인트, 인증 정보, 비공개 설정이 섞일 수 있습니다. AI에게 전달하기 전에 값은 마스킹하고, 공개 글이나 이슈에 그대로 붙이지 않습니다. 실무에서는 '값'보다 '패턴'이 더 중요합니다. 예를 들어 실제 토큰 문자열이 아니라 '인증 헤더 누락', 실제 사용자 이메일이 아니라 '특정 역할 사용자'라고 표현합니다.

6단계: AI에게 원인 가설을 3개 이하로 제한한다

장애 상황에서 AI에게 '원인 찾아줘'라고 넓게 요청하면 후보가 너무 많아집니다. 대신 증거 패킷을 주고 '가능성이 높은 원인 가설을 최대 3개로 제한하고, 각 가설마다 확인 방법과 반증 조건을 써라'고 요청합니다. 반증 조건이 중요합니다. 가설이 틀렸을 때 빠르게 버릴 수 있어야 다음 가설로 넘어갑니다.

좋은 가설 형식은 다음과 같습니다.

이 형식은 AI가 단순히 코드를 바꾸는 대신, 확인 가능한 실험을 제안하게 만듭니다.

7단계: 롤백 기준을 먼저 정한다

핫픽스는 매력적입니다. 특히 AI가 즉시 패치를 제안하면 그대로 배포하고 싶어집니다. 그러나 롤백 기준이 없으면 운영자는 계속 패치를 쌓게 됩니다. 기준은 숫자로 정해야 합니다.

예시는 다음과 같습니다.

• P0 장애는 즉시 롤백을 기본값으로 한다.
• P1 장애는 30분 안에 재현과 수정 후보가 확보되지 않으면 롤백한다.
• 핫픽스 배포 뒤 10분 라이브 스모크에서 동일 증상이 재현되면 롤백한다.
• 오류율이 배포 전 기준보다 2배 이상 유지되면 롤백한다.
• 결제, 로그인, 질문 제출 같은 핵심 흐름은 대표 경로 3개 이상이 통과해야 유지한다.

롤백은 실패가 아니라 복구 전략입니다. AI 코딩에서는 빠른 핫픽스가 가능하지만, 빠른 되돌림도 같은 수준으로 준비되어야 합니다.

8단계: 수정은 테스트와 함께 요청한다

AI에게 수정만 요청하지 말고 회귀 테스트를 함께 요청합니다. 테스트는 장애의 재현 경로와 연결되어야 합니다. 예를 들어 브라우저 콘솔 오류가 원인이었다면 렌더링 테스트나 라우트 스모크가 필요하고, 데이터 누락이 원인이었다면 샘플 데이터 기반 단위 테스트가 필요합니다. API 응답 계약 문제라면 상태 코드와 필수 필드를 확인하는 테스트가 필요합니다.

요청 문장은 이렇게 구성할 수 있습니다.

• 이 증거 패킷을 기준으로 가장 작은 수정안을 제안하라.
• 수정 파일 수를 최소화하라.
• 장애를 재현하는 회귀 테스트를 먼저 작성하라.
• 테스트가 실패하는 이유를 설명한 뒤 수정하라.
• 수정 뒤에는 기존 핵심 테스트와 라이브 스모크 목록을 제안하라.

이 방식은 AI가 장황한 리팩터링 대신 장애에 맞는 작은 변경을 만들게 합니다.

상황별 예시

예시 1: 배포 후 상세 페이지가 빈 화면이 된다

증상은 'VIBE 코딩 상세 글 일부가 모바일에서 빈 화면으로 보인다'입니다. 운영자는 먼저 브라우저 콘솔을 확인합니다. 콘솔에 hydration 관련 오류가 있고, 네트워크 응답은 200이며 HTML에는 글 제목이 있습니다. 사용자 영향은 모바일 사용자 일부이므로 P1 또는 P2입니다.

증거 패킷에는 다음을 넣습니다.

• 모바일 Safari에서 재현
• 데스크톱 Chrome에서는 정상
• 최근 변경은 상세 페이지 렌더링 컴포넌트 개선
• HTML 응답 200, 제목 포함
• 브라우저 콘솔에 hydration 오류
• 라이브 스모크에서 목록은 정상, 상세만 실패
• 롤백 기준은 30분 안에 수정 실패 시 이전 렌더링으로 되돌림

AI에게는 'hydration 오류를 기준으로 서버와 클라이언트 렌더링 차이를 찾고, 최소 수정과 회귀 테스트를 제안하라'고 요청합니다. 이때 AI가 데이터베이스나 라우팅 전체를 고치려 하면 범위를 벗어난 것입니다. 증거가 클라이언트 렌더링을 가리키기 때문입니다.

예시 2: 자동화 작업은 성공인데 공개 페이지가 갱신되지 않는다

증상은 '콘텐츠 동기화 작업은 성공으로 보이지만 공개 VIBE 코딩 목록에 새 글이 나타나지 않는다'입니다. 이 경우 운영자는 작업 로그, 데이터 저장소 반영 여부, 배포 상태, 캐시, 정적 생성 여부를 분리해서 확인합니다. AI에게는 '동기화 성공'이라는 말만 주면 안 됩니다. 실제로 어느 계층까지 반영되었는지 증거가 필요합니다.

증거 패킷은 다음처럼 구성합니다.

• 소스 JSON에는 새 글이 있음
• 테스트는 새 slug를 찾음
• 동기화 결과는 성공으로 표시됨
• 공개 목록 HTML에는 새 제목이 없음
• 상세 URL은 404 또는 이전 상태
• 최근 배포 커밋과 라이브 도메인의 빌드 시각 차이
• 캐시 우회 요청 결과

이 증거를 받은 AI는 'DB sync 문제', '정적 빌드 미배포', '목록 서비스가 다른 소스를 읽음', '캐시 만료 지연' 같은 가설을 나눠야 합니다. 운영자는 각 가설의 확인 방법을 실행하고, 가장 작은 조치를 선택합니다.

예시 3: 외부 API 지연 때문에 AI 기능이 간헐적으로 실패한다

증상은 '질문 답변 생성이 가끔 실패하고 재시도하면 성공한다'입니다. 이 경우 단순 코드 버그가 아니라 외부 API 지연, rate limit, 타임아웃, 큐 중복 처리 문제가 섞일 수 있습니다. AI에게는 실패 로그 한 줄보다 빈도와 시간대가 중요합니다.

운영자는 다음 지표를 모읍니다.

• 실패율과 성공률
• 평균 응답 시간과 p95 지연
• 재시도 후 성공 비율
• 실패가 특정 시간대에 몰리는지
• 같은 질문이 중복 처리되는지
• 사용자에게 보이는 메시지가 적절한지

AI에게는 '코드를 바로 고치지 말고 재시도 정책, idempotency, 사용자 안내, 관측 지표를 분리해서 개선안을 제시하라'고 요청합니다. 핫픽스가 필요하다면 타임아웃을 늘리는 것보다 중복 실행 방지와 상태 표시가 더 중요할 수 있습니다.

실수와 주의점

증거 없이 AI 패치를 믿는 실수

AI가 제안한 수정이 그럴듯해도 증거와 연결되지 않으면 위험합니다. 특히 장애 상황에서는 '이 코드가 수상해 보입니다'라는 설명만으로는 부족합니다. 수정 후보는 반드시 관찰된 증상과 연결되어야 합니다. 브라우저 콘솔 오류를 해결하는 수정인지, 서버 로그의 예외를 해결하는 수정인지, 관측 지표의 급증을 낮추는 수정인지가 명확해야 합니다.

여러 가설을 한 번에 고치는 실수

장애를 빨리 끝내고 싶어서 캐시, 데이터, UI, 설정을 한 번에 바꾸면 나중에 무엇이 원인이었는지 모릅니다. 더 나쁜 경우 새 변경이 또 다른 장애를 만듭니다. AI에게도 한 번에 하나의 가설만 수정하게 하세요. 가설이 틀리면 되돌리고 다음 가설로 이동하는 편이 장기적으로 빠릅니다.

로그 원문을 그대로 공유하는 실수

로그에는 민감한 값이 섞일 수 있습니다. 운영자가 공개 채널, 문서, AI 대화에 로그를 그대로 붙이는 습관을 들이면 보안 사고로 이어질 수 있습니다. 필요한 것은 값이 아니라 패턴입니다. 사용자 식별자는 역할이나 케이스 번호로 바꾸고, 인증 관련 값은 '존재함', '누락됨', '만료됨'처럼 상태로만 표현합니다.

성공 기준을 배포 성공으로 착각하는 실수

배포가 성공했다는 것은 빌드와 배포 파이프라인이 끝났다는 뜻이지, 장애가 해결됐다는 뜻이 아닙니다. 장애 해결의 성공 기준은 사용자 경로가 정상으로 돌아왔는지입니다. 그래서 라이브 스모크가 필요합니다. 홈, 목록, 상세, 핵심 제출 흐름, 관련 API, 브라우저 콘솔을 확인해야 합니다.

사후 회고를 생략하는 실수

복구가 끝나면 바로 다음 작업으로 넘어가기 쉽습니다. 그러나 AI 코딩 환경에서는 같은 유형의 실수가 빠르게 반복될 수 있습니다. 회고에는 원인보다 예방 장치를 더 중요하게 적어야 합니다. 어떤 테스트가 없어서 놓쳤는지, 어떤 관측 지표가 늦었는지, 어떤 롤백 기준이 애매했는지를 남겨야 다음 AI 작업의 프롬프트와 테스트가 좋아집니다.

검증 체크리스트

AI 장애 디버깅 런북을 실제 팀에 적용할 때는 다음 체크리스트를 사용하세요.

• 증상 한 문장이 구체적인 사용자 경로를 포함하는가
• 사용자 영향과 심각도 등급이 정해졌는가
• 재현 경로, 재현률, 기대 결과, 실제 결과가 기록되었는가
• 최근 변경 타임라인이 배포·설정·데이터 작업을 포함하는가
• 로그, 브라우저 콘솔, HTTP 상태, 관측 지표가 증거 패킷에 들어갔는가
• 민감한 값은 모두 마스킹되었는가
• AI 원인 가설은 3개 이하이며 확인 방법과 반증 조건이 있는가
• 롤백 기준이 숫자와 시간으로 표현되었는가
• 수정 전 장애를 재현하는 회귀 테스트가 있는가
• 수정 뒤 핵심 경로 라이브 스모크를 실행했는가
• 공개 페이지에 내부 상태, 운영용 문구, 민감한 설정 이름이 노출되지 않았는가
• 복구 뒤 사후 회고와 예방 테스트가 남았는가

이 체크리스트는 완벽한 문서 작성을 위한 것이 아닙니다. 운영자가 AI에게 넘기기 전에 판단해야 할 최소 기준입니다. 한 항목이라도 비어 있으면 AI가 추측으로 채울 가능성이 있습니다.

다음 단계

첫 번째 단계는 팀이나 개인 프로젝트에 맞는 증거 패킷 템플릿을 만드는 것입니다. 템플릿은 길 필요가 없습니다. 증상, 영향, 재현, 타임라인, 증거, 롤백 기준, AI 작업 범위만 있으면 시작할 수 있습니다. 중요한 것은 장애가 생긴 뒤 새로 생각하지 않도록 미리 정해두는 것입니다.

두 번째 단계는 대표 장애 3가지를 골라 회귀 테스트로 바꾸는 것입니다. 예를 들어 상세 페이지 렌더링 실패, 질문 제출 후 목록 미반영, 외부 API 지연 같은 케이스를 테스트와 라이브 스모크 목록으로 고정하세요. AI에게 새 기능을 맡길 때도 이 스모크 목록을 함께 주면 배포 후 실수를 줄일 수 있습니다.

세 번째 단계는 롤백과 핫픽스 판단을 숫자로 정하는 것입니다. '상황을 봐서'는 장애 대응 기준이 아닙니다. 30분, 오류율 2배, 핵심 경로 3개 실패, P0 즉시 롤백처럼 실행 가능한 기준을 써야 합니다.

마지막으로, AI를 장애 대응의 주체가 아니라 속도를 높이는 도구로 두세요. 사람은 사용자 영향과 복구 전략을 결정하고, AI는 증거 기반의 가설·테스트·패치를 빠르게 만듭니다. 이 역할 분리가 지켜질 때 VIBE 코딩은 빠른 개발뿐 아니라 빠른 복구까지 가능해집니다.