ai-coding-mines목차GitHub

이틀 전 사건이 진단을 가로챘다 — 비슷한 증상에 지난번 원인을 재사용한다

Claude Code · 에이전트

증상

한 계정의 알림이 오지 않았다. "API 키가 만료됐다"로 단정했다. 이틀 전에 실제로 그 키가 만료된 적이 있었기 때문이다.

실제

조회 API를 쳐 보니 HTTP 200. 키는 살아 있었다. 진짜 원인은 마이그레이션에서 파일 하나가 빠진 것이었다.

★★★ 증상이 과거 사건과 비슷하면 그 원인을 재사용한다. 최근일수록 강하게 가로챈다.

★★ 경험이 쌓일수록 이 오진이 늘어난다. 후보가 많아져서가 아니라 — 그럴듯한 후보가 너무 빨리 떠올라 탐색이 일찍 멈추기 때문이다. 초보는 모르니까 확인하고, 숙련자는 안다고 느껴서 확인하지 않는다.

★★ 이 컬렉션에는 같은 계열이 이미 셋 있다 — 사유가 비어 있는 반려를 아는 사유로 메운 것, 같은 배치라고 같은 원인으로 본 것, 같은 에러 문구가 네 번 나왔는데 원인이 네 번 다 달랐던 것. 이번은 "지난번 원인의 재사용"이다.

⚠️ ★★★ 그리고 틀린 원인은 틀린 조치를 낳고, 그 조치의 실패가 더 깊은 혼란을 만든다

키를 재발급했다면 알림은 여전히 오지 않았을 것이다. 그 시점에서는 "재발급했는데도 안 되네"가 되어 진짜 원인에서 더 멀어진다.

★★ 조치가 실패하면 사람은 보통 그 조치를 의심하지, 가설을 의심하지 않는다. 재발급을 다시 해 보고, 권한을 보고, 전파 지연을 기다린다 — 전부 틀린 가지 위에서다.

★ 게다가 그 조치에는 비용이 있었다. 당시 환경에서 재발급은 며칠 뒤에나 가능했다. 틀린 진단이 만든 대기가 진짜 문제를 그동안 가린다.

해법

★★★ 단정 전에 한 줄로 확인한다. 조회 API를 직접 쳐 보는 데 10초면 된다.

★★ 10초짜리 확인을 건너뛰는 이유는 시간이 아니라 확신이다."분명 그것"이라는 느낌이 강할수록 확인이 더 필요하다는 쪽으로 규칙을 뒤집어라. 확신은 확인을 면제하는 근거가 아니라 요구하는 신호다.

그리고 확인 결과를 기록에 남겨라. "200을 봤다"는 사실이 다음 진단의 출발점이 된다 — 남기지 않으면 다음 사람이 같은 10초를 다시 쓰거나, 같은 단정을 다시 한다.