AI에게 '일단 고쳐봐'라고 하지 마라 — systematic-debugging 스킬

버그를 AI에게 던지면 벌어지는 일

버그가 나면 나는 기존에 이렇게 했다. 에러 메시지를 복사해서 AI에게 붙여넣고 "고쳐줘"라고 했다. AI는 그럴듯한 수정안을 내놓는다. 적용한다. 안 고쳐진다. 다시 던진다. 또 다른 수정안이 나온다. 이걸 다섯 번쯤 반복하면, 처음보다 코드가 더 엉망이 되어 있다.

이게 AI 페어 프로그래밍에서 내가 망친 패턴 중 하나다. AI는 근본 원인을 모르는 채로도 수정안을 무한히 만들어낸다. 그리고 나는 그 수정안을 무한히 시도한다. 증상만 건드리는 수정이 쌓이고, 새 버그가 생긴다.

이 습관을 끊어준 게 Superpowers의 systematic-debugging 스킬이다. Superpowers 스킬 전체를 훑은 글에서 한 줄로만 언급했는데, 이 스킬 하나는 따로 깊게 팔 가치가 있다. 오늘은 이걸 심층적으로 뜯어본다.

스킬이 강제하는 단 하나의 규칙

이 스킬의 핵심은 방법론이 아니라 금지다. 첫 줄부터 이렇게 못을 박는다.

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
근본 원인 조사 없이는 어떤 수정도 없다

스킬은 이걸 "Iron Law(철칙)"라고 부른다. 조사 단계(Phase 1)를 끝내기 전에는 수정안을 제안하는 것 자체가 금지다. 재미있는 건 스킬이 이 규칙을 어길 때 AI가 스스로에게 하는 변명까지 미리 적어놨다는 거다.

• "간단한 버그니까 프로세스 필요 없어" → 간단한 버그도 근본 원인이 있다
• "급하니까 일단 이거부터" → 첫 수정이 패턴을 정한다. 처음부터 제대로
• "일단 이거 바꿔보고 되나 보자" → 그게 랜덤 수정의 시작이다

나도 저 변명을 매번 했다. 스킬은 저걸 "Red Flag(위험 신호)"로 규정하고, 저 생각이 들면 멈추고 Phase 1로 돌아가라고 한다. AI가 저런 말을 하면 이제 나도 알아챈다. "아, 지금 조사 안 하고 찍으려는 거구나."

4단계 방법론

Iron Law 다음은 4단계다. 각 단계를 끝내야 다음으로 넘어갈 수 있다.

말로 풀면 뻔해 보인다. 하지만 저 순서를 강제로 지키게 만드는 게 이 스킬의 전부다. 하나씩 실제로 어떻게 쓰이는지 보자.

Phase 1 — 조사가 8할이다

가장 중요한 단계다. 여기서 스킬이 특히 강조하는 건 다중 컴포넌트 시스템에서의 증거 수집이다. CI → 빌드 → 서명, 또는 API → 서비스 → DB처럼 층이 여러 개면, 수정안을 내기 전에 각 경계마다 로그를 심으라고 한다.

# 각 층에서 데이터가 들어오고 나가는 걸 찍는다
echo "=== 워크플로우: IDENTITY ${IDENTITY:+SET}${IDENTITY:-UNSET} ==="
env | grep IDENTITY || echo "빌드 스크립트에 IDENTITY 없음"
security find-identity -v   # 서명 층 상태

한 번 돌리면 어느 층에서 끊기는지 보인다. 워크플로우엔 있는데 빌드 스크립트엔 없다면, 범인은 그 사이 어딘가다. 나는 예전에 이 과정을 건너뛰고 서명 명령어만 계속 고쳤다. 문제는 두 층 위 환경변수 전파에 있었는데 말이다. 증거 없이 찍으면 엉뚱한 층만 판다.

Phase 2 — 동작하는 코드와 비교하라

깨진 코드를 노려보는 대신, 같은 코드베이스에서 잘 되는 비슷한 코드를 찾는다. 그리고 한 줄씩 비교한다. "이건 다르지만 상관없겠지"를 금지한다. 사소한 차이 하나가 원인인 경우가 대부분이다.

Phase 3 — 한 번에 하나만

가설은 하나. 검증도 최소 변경 하나. 스킬은 "여러 개를 한꺼번에 고치면 뭐가 통했는지 알 수 없고 새 버그를 만든다"고 못 박는다. 안 되면 수정을 얹지 말고 새 가설을 세운다. 이게 랜덤 수정과 과학적 방법의 갈림길이다.

Phase 4 — 그리고 3번 규칙

구현 단계에서 스킬이 내놓는 가장 값진 규칙이 이거다. 수정을 3번 시도했는데 안 되면, 4번째를 시도하지 말고 아키텍처를 의심하라.

수정이 실패했다
→ 시도 횟수를 센다
→ 3번 미만이면 Phase 1로 돌아가 재분석
→ 3번 이상이면 STOP. 아키텍처를 질문하라

수정할 때마다 다른 곳에서 새 문제가 튀어나오고, 고치려면 "대대적 리팩터링"이 필요하다면 — 그건 실패한 가설이 아니라 틀린 구조다. 이건 정말 여러 번 경험했다. 3시간을 쏟아붓고 나서야 "애초에 이 설계가 잘못됐구나"를 깨닫는다. 스킬은 그걸 3번째에서 멈추게 한다.

Claude Code에서 어떻게 발동하나

스킬은 두 가지 방식으로 켜진다.

스킬의 description에는 "버그, 테스트 실패, 예상 못 한 동작을 만났을 때, 수정안을 제안하기 전에 사용"이라고 적혀 있다. 이 트리거 조건 덕분에 내가 버그를 언급하면 Claude Code가 스킬을 자동으로 읽는다. 스킬이 왜 이런 식으로 트리거를 쓰는지, 명령어·서브에이전트와 어떻게 다른지는 서브에이전트 vs 스킬 vs 커맨드 글에서 다뤘다.

한 가지 팁. CLAUDE.md에 "버그는 항상 systematic-debugging으로"라고 한 줄 박아두면 발동률이 훨씬 올라간다. 다만 CLAUDE.md 안티패턴 글에서 말했듯 이런 규칙을 너무 많이 넣으면 오히려 묻힌다. 정말 지키고 싶은 것만 넣는다.

실제로 뭐가 달라졌나

스킬 문서 끝에는 디버깅 세션 통계가 붙어 있다.

• 체계적 접근: 버그당 15~30분
• 랜덤 수정: 2~3시간의 헤맴
• 첫 시도 해결률: 95% vs 40%
• 새 버그 유입: 거의 0 vs 흔함

내 체감도 비슷하다. 예전엔 "빠르게 고치려다" 더 오래 걸렸다. 조사 10분이 아까워서 찍기 시작하면, 그 찍기가 2시간이 된다. 조사부터 하면 대개 그 10분 안에 원인이 보인다. 체계적인 게 느린 게 아니라, 헤매는 게 느린 거였다.

또 하나. 이건 사람에게도 그대로 적용되는 방법론이다. AI 없이 나 혼자 디버깅할 때도 "지금 Phase 1을 건너뛰고 있나?"를 스스로 묻게 됐다. 도구가 만든 습관이 도구 밖으로 나온 셈이다. 이런 AI 도구 의존의 좋은 쪽 부작용은 반갑다.

멈춰야 할 신호들

스킬을 안 써도 이 신호들만 외워두면 절반은 온 거다. 이런 생각이 들면 멈추고 조사로 돌아간다.

• "일단 임시로 고쳐놓고 나중에 조사하자"
• "이거 하나 바꿔보고 되나 보자"
• "여러 개 한꺼번에 바꾸고 테스트 돌리자"
• "완전히 이해 못 했지만 이게 될 것 같은데"
• "한 번만 더 고쳐보자" (이미 두 번 실패한 뒤)

마지막 게 특히 위험하다. 두 번 실패한 다음의 "한 번만 더"는 거의 항상 세 번째 실패로 간다. 그 자리가 설계부터 다시 봐야 하는 지점이다.

직접 겪은 일: 이 규칙이 실제로 나를 막은 순간

이 스킬이 정말 값을 한 사례를 하나 적어둔다.

목록 페이지에서 글이 안 보이는 문제가 있었다. 원인 후보가 여럿이었고, 나는 제일 그럴듯한 쪽부터 고치고 싶었다. 데이터 읽는 함수를 손보면 될 것 같았다.

절차를 지켰더니 순서가 달라졌다. 먼저 실패를 정확히 재현할 방법부터 만들었다 — 배포된 주소의 HTML을 받아서 태그를 걷어내고 단어 수를 세는 것. 19단어라는 숫자가 나왔다. 그리고 로컬에서 같은 방법으로 재보니 506단어였다.

이 두 숫자가 나온 순간 원인 후보가 절반으로 줄었다. 데이터를 읽는 쪽 문제가 아니라 렌더링 시점의 문제라는 게 확정됐기 때문이다.

만약 그냥 고쳤다면 어땠을까. 데이터 함수를 손봤을 것이고, 로컬에서는 원래 멀쩡했으니 «고쳤다»고 판단했을 것이다. 그리고 배포한 뒤에 똑같은 화면을 다시 봤을 것이다.

「일단 고쳐봐」가 위험한 이유는 틀린 수정을 하기 때문이 아니라, 고쳤는지 아닌지를 판별할 방법 없이 고치기 때문이다. 이 스킬이 강제하는 건 결국 그 판별 방법을 먼저 만들라는 것이다.

정리

systematic-debugging은 화려한 스킬이 아니다. 하는 일은 단순하다. 찍지 말고 조사부터 하게 만드는 것. 그런데 이 단순한 걸 AI도 사람도 잘 못 지킨다. 급하면 찍고 싶어지니까.

세 줄로 요약하면 이렇다.

1. Iron Law — 근본 원인 조사 전엔 수정 없다
2. 4단계 — 조사 → 패턴 비교 → 단일 가설 → 근본 수정
3. 3번 규칙 — 세 번 실패하면 버그가 아니라 구조를 의심하라

AI에게 버그를 던질 때 "고쳐줘" 대신 "먼저 근본 원인부터 조사해줘"라고 한 단어만 바꿔도 결과가 달라진다. 그 한 단어가 이 스킬의 전부다.