AI 드리븐

지도 위치 : 3일차 · 신뢰와 운영 · 공개 이후 | 이전: 22차시 배포 ② 서비스 완성 | 다음: 24차시 완성 데모와 실무 확장 키워드 : 사실 기반 장애 추적, 근본 원인과 재발 방지, 사후 기록

이 차시를 다 읽으면

1. 로그 · 지표 · 추적 을 같은 범주(관측 신호) 안에서 유와 종차로 가르고, 장애 때 각각 어떤 질문에 답하는지 말할 수 있다.
2. 사실 기반 장애 추적의 여섯 단계 를 대고, "영향 차단(롤백)"이 "원인 분석"보다 앞에 오는 이유를 설명할 수 있다.
3. AI에게 장애 분석을 맡길 때 사실과 추측을 나누게 하는 지시를 쓰고, AI가 추측으로 고치려 들 때 멈추는 기준을 댈 수 있다.
4. 5 Whys 로 증상에서 근본 원인까지 내려가고, 재발 방지를 "조심하자"가 아니라 장치 로 적을 수 있다.
5. 포스트모템 과 런북 을 유와 종차로 가르고, 둘 중 무엇을 장애 전에 · 후에 쓰는지 말할 수 있다.

---

0. 이 차시의 판별 축

이 차시가 답하는 질문은 서비스가 공개된 뒤 문제가 생기면, 추측이 아니라 무엇으로 움직이는가 입니다. 앞에서 배운 "증거 ↔ 주장" (1차시)이 과정의 첫 축이었다면, 장애는 그 축이 가장 비싸게 시험받는 순간입니다. AI에게 "에러 나는데 고쳐줘"라고 하면 그럴듯한 원인을 추측하고 바로 코드를 고칩니다. 맞으면 다행이지만, 틀리면 원래 문제는 그대로이고 새 변경까지 생깁니다.

---

1. 관측 — 무엇을 볼 수 있어야 하나

1.1 정의

장애 (incident) — [운영 사건]인데, [ 사용자가 서비스를 정상적으로 쓰지 못하게 된 상태 ]라는 점에서 개발 중에 발견한 버그와 구별된다. 장애에서는 피해가 지금 진행 중 입니다.

관측 신호 — 장애를 추적하려면 평소에 쌓이고 있어야 하는 기록들입니다. 세 가지가 같은 범주의 형제입니다.

여기에 둘이 더 붙습니다.

⭐ 변경 이력 이 장애 원인의 가장 빠른 단서인 경우가 많습니다. "14시부터 에러"와 "14:02 배포"가 나란히 있으면, 첫 가설은 거의 정해집니다. 18차시의 작은 커밋과 22차시의 자동 배포 기록이 여기서 값을 합니다.

1.2 로그의 두 원칙

1.3 반례 — 이건 관측이 아닙니다

---

2. ⭐ 사실 기반 장애 추적

2.1 여섯 단계

① 증상 확정     무엇이 안 되나? 언제부터? 누구에게? (전부? 일부?)
② 영향 차단     필요하면 먼저 롤백 (원인 분석보다 사용자 피해 중단이 우선)
③ 증거 수집     로그, 지표, 변경 이력
④ 가설 세우기   증거로 뒷받침되는 가설만
⑤ 검증         가설이 맞다면 보일 증거를 확인. 재현해 봄
⑥ 수정         원인이 확인된 뒤에

🔍 읽는 포인트 : ②가 ③보다 앞 에 있다는 것, 그리고 ⑥이 맨 끝 이라는 것만 보면 됩니다.

2.2 ⭐ 고치기 전에 롤백

0절 축 2입니다. 최근 배포 이후 문제가 생겼다면, 원인을 찾기 전에 먼저 이전 배포로 되돌립니다.

코드를 읽지 않는 사람에게 이 원칙은 특히 중요합니다. AI와 함께 원인을 찾는 데는 시간이 걸리고, 그동안 피해가 계속됩니다. 반면 롤백은 코드 지식이 필요 없습니다.

⚠️ 단, 앞에서 배운 대로 (21차시) DB 마이그레이션은 롤백으로 돌아오지 않습니다. 장애 직전 배포에 마이그레이션이 있었다면, 롤백 전에 "이 롤백이 DB와 맞는가"를 확인해야 합니다. 이 판단이 런북(4.2절)에 미리 적혀 있어야 하는 이유입니다.

2.3 AI에게 장애 분석을 맡기는 지시

14시부터 예약 API에서 500 에러가 늘었다. 로그와 배포 이력은 아래와 같다.
아직 코드를 고치지 마.
1. 관찰된 사실과 추측을 구분해서 정리해줘. 사실에는 근거가 된 로그 줄 원문을 붙여.
2. 가능한 원인 가설을 근거와 함께 나열하고, 각 가설을 확인할 방법을 제안해줘.
3. 어떤 증거가 있으면 그 가설이 틀렸다고 볼 수 있는지도 써줘.

🔍 읽는 포인트 : 둘째 줄 "아직 코드를 고치지 마" 와 1번의 "사실과 추측을 구분" 이 핵심입니다. 3번은 가설을 반박할 수 있는 형태 로 만들게 하는 장치입니다.

2.4 AI가 고치려 들 때의 판단 기준

README 9.4의 위험 신호 중 "같은 에러를 세 번 이상 다른 방법으로 고친다"가 장애 중에 가장 자주 나옵니다.

---

3. 근본 원인과 재발 방지

3.1 5 Whys

근본 원인 (root cause) — [장애 원인]인데, [ 그것을 고치면 같은 종류의 장애가 다시 일어나지 않는 지점 ]이라는 점에서 고쳐도 다른 모습으로 반복되는 증상 · 직접 원인과 구별된다.

5 Whys — [원인 분석 방법]인데, [ "왜?"를 반복해 직접 원인에서 장치 · 절차의 빈틈까지 내려간다 ]는 점에서 첫 번째 원인에서 멈추는 분석과 구별된다. 다섯은 정해진 숫자가 아니라 "충분히 내려가라"는 뜻입니다.

증상: 인기 클래스에 정원보다 예약이 2개 많다
왜? → 동시 예약 요청에서 자리 차감이 겹쳤다
왜? → 이번 배포에서 예약 로직을 고치며 조건부 차감이 "조회 후 저장"으로 바뀌었다
왜? → 리팩터링한 에이전트가 동시성 의도를 몰랐고, 리뷰도 놓쳤다
왜? → 동시 예약 테스트가 CI에 없었다 (로컬에서만 수동으로 했다)
왜? → "자리는 0 아래로 내려갈 수 없다"는 DB 제약도 마이그레이션에서 빠져 있었다

🔍 읽는 포인트 : 위로 갈수록 코드 , 아래로 갈수록 장치 · 절차 의 이야기가 됩니다. 0절 축 3에서 오른쪽(근본 원인)으로 이동하는 모습입니다.

3.2 재발 방지는 "조심하자"가 아니라 장치로

0절 축 4입니다. "앞으로 주의한다"는 다음 세션의 AI가 기억하지 못합니다(앞에서 배운 무상태, 2차시).

⭐ 오른쪽 열을 보세요. 장애에서 배운 것은 결국 기억 · 강제 · 검증 장치로 돌아갑니다. 이것이 과정 전체의 순환이고, 24차시에서 정산합니다.

---

4. 포스트모템과 런북

4.1 경계

둘 다 0절 축 5의 오른쪽(파일)입니다. 기록이 없으면 다음 사람과 다음 세션의 AI 가 같은 조사를 처음부터 다시 합니다.

4.2 ⭐ 런북 — 장애 전에 준비한다

장애는 AI에게 맡기는 방식의 약점이 가장 크게 드러나는 순간입니다. 평소에는 AI에게 맡기면 되지만, 장애 중에는 AI가 틀린 원인을 붙잡고 엉뚱한 곳을 고칠 수 있고, 그것을 판단하기 어렵습니다. 그래서 장애가 나기 전에 런북을 AI와 함께 만듭니다(6절 실습).

런북에 들어갈 것:

• 증상별(사이트 안 열림 / 예약 실패 / 결제 실패 / 느림) 첫 번째로 볼 화면과 순서
• 롤백하는 방법 (플랫폼 화면 기준, 버튼 위치까지) + 마이그레이션이 있었을 때의 주의
• 결제 장애 시 PG사 대시보드에서 확인할 것
• 내가 판단할 수 없을 때 연락할 곳 — 특히 보안 사고는 피해 범위 판단에 코드 이해가 필요하므로, 도와줄 사람을 미리 정해 둡니다 (README 9.6)

4.3 포스트모템 — 비난 없이

누구 탓인지가 아니라 무엇이 이걸 가능하게 했는지 를 씁니다(비난 없는 사후 기록). 사람이든 AI 에이전트든 "누가 실수했다"로 끝나면 3.2절의 장치가 나오지 않습니다.

# docs/postmortems/2026-11-01-overbooking.md
## 요약
11/1 14:02~15:10, 인기 클래스 3개에서 초과 예약 5건 발생.

## 영향
수강생 5명이 예약 확정 후 취소 안내를 받음. 전액 환불 처리.

## 타임라인
14:02 배포 / 14:30 운영자 문의 / 14:41 확인 / 14:50 롤백 / 15:10 정상화 확인

## 근본 원인
(5 Whys 결과)

## 잘된 점 / 아쉬운 점
- 롤백이 10분 안에 됐다
- 알림이 아니라 운영자 문의로 알게 됐다

## 재발 방지 조치
| 조치 | 담당 | 상태 |

🔍 읽는 포인트 : 제목들(요약 · 영향 · 타임라인 · 근본 원인 · 잘된 점 / 아쉬운 점 · 재발 방지)만 보면 됩니다. "아쉬운 점"의 둘째 줄("운영자 문의로 알게 됐다")이 곧 알림 설정 이라는 다음 조치가 됩니다.

💡 포스트모템은 코드를 몰라도 직접 쓸 수 있는 문서 입니다. 타임라인, 영향, 잘된 점과 아쉬운 점은 내가 쓰고, 근본 원인과 기술적 조치만 AI에게 채우게 합니다.

4.4 이해 부채를 줄이는 기록

이해 부채 — 코드는 계속 늘어나는데 그 코드를 이해하는 사람이 아무도 없는 상태가 쌓이는 것입니다. 평소에는 보이지 않다가 장애 때 한꺼번에 드러납니다. 포스트모템을 docs/postmortems/에 쌓아 두면, 다음 세션의 에이전트가 "이 프로젝트에서 과거에 무슨 일이 있었는지"를 맥락으로 읽을 수 있고, 나도 다음 장애 때 같은 곳을 다시 헤매지 않습니다.

💡 비유는 마지막에 — 런북은 소방 대피 안내도 (불나기 전에 붙여 둠), 포스트모템은 화재 조사 보고서 (불난 뒤에 씀), 롤백은 일단 대피 입니다. 불이 왜 났는지는 대피한 다음에 조사합니다.

---

5. 클래스온에 적용하면

---

6. 실습 — 맡기고 검수하기

이 차시의 실습은 장애가 나기 전에 합니다. 장애 훈련입니다.

지시

[1단계 — 런북]
docs/runbook.md를 만들어줘. 코드를 모르는 내가 혼자 따라 할 수 있는 수준으로.
- 증상별(사이트 안 열림 / 예약 실패 / 결제 실패 / 느림) 첫 번째로 확인할 화면과 순서
- 롤백하는 방법 (우리 배포 플랫폼 화면 기준, 버튼 위치까지), 직전 배포에 마이그레이션이 있었을 때의 주의
- 결제 장애 시 PG사 대시보드에서 확인할 것
- 내가 판단할 수 없을 때 연락할 곳 (빈칸으로 두면 내가 채움)
확실하지 않은 화면 위치는 "확인 필요"로 표시해. 추측으로 채우지 마.

[2단계 — 분석 훈련]
스테이징 로그와 배포 이력에서 최근 에러 하나를 골라 2.3절 형식으로 분석해줘.
보고 형식: | 구분(사실/추측) | 내용 | 근거(로그 줄 원문 또는 "없음") |
그다음 가설 표: | 가설 | 맞다면 보일 증거 | 틀렸다고 볼 증거 | 확인 방법 |
코드와 설정은 어떤 것도 고치지 마. 스테이징이든 운영이든 DB와 설정에 직접 손대지 마.

받을 증거

• docs/runbook.md (증상 네 가지, "확인 필요" 표시 포함)
• 사실 / 추측 표 — 사실 칸마다 로그 줄 원문
• 가설 표 — 가설마다 "틀렸다고 볼 증거" 칸이 채워져 있는가

내가 직접 확인할 것

💡 장애 훈련 뒤에 연습용 포스트모템을 하나 써 보세요. 타임라인과 아쉬운 점은 내가, 근본 원인은 AI가. "알림이 아니라 내가 우연히 알았다"가 아쉬운 점에 나오면, 그것이 다음에 설정할 알림입니다.

---

부록 A. 스스로 확인하기

부록 B. 자주 하는 실수

부록 C. NotebookLM 복습 프롬프트

이 23차시 노트만 근거로 5문제를 내줘. 비전공자 기준으로.
"고치기 전에 롤백하는 이유", "AI에게 장애 분석을 맡길 때 사실과 추측을 나누게 하는 이유", "포스트모템과 런북의 차이"는 반드시 포함해줘.
답은 내가 답한 다음에 채점하고, 틀린 이유를 노트의 절 번호를 근거로 설명해줘.