왜 AI에게 디버깅을 맡기면 미궁에 빠지는가

"Claude Code에 에러를 던졌더니, 엉뚱한 수정안을 제안해서 시간을 낭비했다"

이러한 경험은 AI 코딩 툴이 보급된 2024~2025년에 걸쳐 급증하고 있습니다. 원인은 툴의 성능이 아니라, 사용법에 있습니다.

기본 상태의 Claude Code는 "보완 편향 (Completion Bias)"을 가지고 있습니다. 에러 메시지를 받으면, 그럴듯한 답을 빠르게 내놓으려고 합니다. 하지만 시니어 엔지니어가 디버깅 시 실제로 밟고 있는 것은 전혀 다른 사고 프로세스입니다.

본 기사에서는 시니어 엔지니어가 무의식적으로 실행하고 있는 「가설 → 분리 → 검증 → 좁히기」의 루프를 언어화하고, Claude Code에 이식하는 구체적인 방법을 해설합니다.

시니어 엔지니어의 디버깅 사고를 해부하다

「무턱대고 조사하기」와 「분리해서 조사하기」의 차이

같은 에러에 직면했을 때, 주니어와 시니어의 접근 방식은 근본적으로 다릅니다.

주니어 엔지니어의 경우:

에러 메시지를 복사
→ Google에서 검색
→ Stack Overflow의 상위 답변을 시도
...

시니어 엔지니어의 경우:

에러 메시지를 읽음
→ "이것은 어느 레이어(Layer)에서 일어나고 있는가"를 특정함
→ "언제부터, 어떤 조건에서 발생하는가"를 확인함
...

이 차이를 한마디로 표현하자면, 가설을 가지고 움직이는가, 가설 없이 움직이는가 입니다.

가설 주도형 디버깅의 5단계 (5 Phases)

시니어 엔지니어의 사고를 분해하면 5가지 단계로 정리할 수 있습니다.

이 프레임워크 자체는 "알고 있는" 사람이 많지만, 실제 디버깅 세션에서 의식적으로 실행하고 있는 사람은 적습니다. 그리고 AI는 이 프레임을 가지고 있지 않은 상태로 사용되는 경우가 대부분입니다.

「분리 (Isolation)」의 구체적 기법

Phase 4의 분리에는 몇 가지 정석적인 패턴이 있습니다.

환경의 분리

운영 환경에서만 발생? → 환경 차이를 조사 (env 변수, 인프라 설정)
스테이징에서도 발생? → 코드 문제
로컬에서도 발생? → 환경 비의존적 버그

시계열의 분리

언제부터 발생했는지 특정할 수 있는가?
→ git log / git bisect로 커밋 차분을 좁힘

레이어의 분리

DB → API → 프론트 → 인프라
어느 레이어까지는 정상적으로 동작하고 있는가?

데이터의 분리

모든 사용자에게 발생? → 보편적인 버그
특정 사용자에게만 발생? → 데이터 기인 혹은 역할/권한 문제
특정 입력값에서만 발생? → 유효성 검사(Validation)・형 변환(Type Conversion) 문제

Claude Code에 「사고의 틀」을 이식하기

왜 기본 Claude Code는 디버깅을 잘 못하는가

Claude Code가 디버깅에서 미궁에 빠지기 쉬운 이유는 3가지가 있습니다.

1. 보완 편향 (Completion Bias)

LLM은 "그럴듯한 답을 생성하는 것"에 최적화되어 있습니다. 디버깅에 필요한 "모르겠다, 정보가 더 필요하다"라는 멈춤에 서툽니다.

2. 컨텍스트(Context) 부족

AI는 당신의 시스템 아키텍처, 배포 구성, 과거 장애 이력을 모릅니다. 에러 메시지만 전달하고 "왜?"라고 물어도 엉뚱한 추측이 됩니다.

3. 검증 없는 추론

"이 에러는 〇〇가 원인이라고 생각합니다"라고 즉답하지만, 그 가설을 검증하는 명령어를 실행하여 확인하는 단계가 빠지기 쉽습니다.

이러한 문제를 해결하기 위해, 「사고의 틀」을 프롬프트(Prompt)로 전달하는 설계가 유효합니다.

CLAUDE.md를 통한 사고 프레임의 고정

프로젝트 루트의 CLAUDE.md에 디버깅 원칙을 기술해 둠으로써, 모든 세션에 사고의 틀을 적용할 수 있습니다.

## 디버깅 조사의 기본 원칙
디버깅을 의뢰받았을 때, 다음 절차를 반드시 지킬 것.
1. ** 추측으로 답변하기 전에 가설 리스트를 제시할 것 **
...

디버깅 전용 커스텀 명령어 설계

.claude/commands/ 디렉토리에 커스텀 명령어를 작성함으로써, 매번 프롬프트를 쓰는 수고를 덜 수 있습니다.

# 디렉토리 구성
.claude/
└── commands/
...

debug-investigate.md

의 설계 예시:

# 디버그 조사 명령어
인수로 전달된 에러 정보 및 증상에 대해, 다음 절차에 따라 조사를 실행해 주세요.
## Step 1: 증상 정리
...

이 명령어는 /debug-investigate [에러 메시지]

형식으로 호출할 수 있습니다.

실전: 실제 버그에 적용해 보기

케이스 스터디 ① 「운영 환경에서만 느림」 퍼포먼스 문제

증상: 운영 환경(Production)에서 API 응답이 간혹 10초를 초과함. 로컬 환경에서는 재현되지 않음.

형식(Type) 없이 던졌을 경우 (NG 예시):

사용자: 운영 환경에서 API가 느립니다. 응답에 10초가 걸릴 때가 있습니다.
Claude: 데이터베이스 쿼리가 최적화되지 않았을 가능성이 있습니다.
INDEX를 추가해 보세요. 또한, N+1 문제가 발생하고 있지 않은지
...

문제는 "가능성이 있습니다"로 끝난다는 점입니다. 확인도 하지 않았고, 다른 원인을 검토하려는 자세도 없습니다.

형식(Type)을 전달했을 경우 (OK 예시):

사용자: /debug-investigate 운영 환경에서 API 응답이 간혹 10초를 초과함.
스테이징(Staging)과 로컬에서는 재현되지 않음.
Claude: 【증상 정리】
...

답변의 질이 근본적으로 달라집니다. "확인됨"과 "추측"이 분리되어 있으며, 다음 액션이 구체적입니다.

케이스 스터디 ② 「특정 사용자만 에러」 인증 문제

증상: 일부 사용자에게만 403 에러가 발생함.

이런 종류의 문제에는 "데이터 격리 (Data Isolation)" 프롬프트가 유효합니다.

# 던질 프롬프트 설계
다음 격리 작업을 순서대로 실시해 주세요.
【데이터 격리】
...

Claude Code는 이 지시에 따라 실제로 확인용 SQL을 생성해 줍니다.

-- Claude Code가 생성한 격리 쿼리 예시
SELECT
u.id,
...

케이스 스터디 ③ 「어제까지는 작동했음」 디그레션(Regression) 문제

디그레션에는 git bisect와의 조합이 강력합니다.

# Claude Code에 대한 지시 패턴
"최근 50개 커밋의 변경 사항 요약을 작성하고,
인증·권한·미들웨어와 관련된 변경 사항을 특정해 주세요.
...

Claude Code가 생성하는 절차 예시:

# git bisect 실행 절차 (Claude Code 생성)
git bisect start
git bisect bad HEAD # 현재 커밋 (버그 있음)
...

디버그 자동화 파이프라인 설계

전체 아키텍처

개별적인 디버깅을 넘어, 팀 차원에서 재현 가능한 조사 프로세스를 구축하려면 자동화 파이프라인 설계가 필요합니다.

[에러 발생]
↓
[로그 수집·정제 스크립트]
...

로그 수집 스크립트 예시 (Node.js):

// scripts/collect-debug-context.ts
import { execSync } from "child_process";
import * as fs from "fs";
...

Human-in-the-Loop 설계 원칙

자동화에서 가장 중요한 것은, 어디에서 인간이 판단할 것인가를 설계하는 것입니다.

AI에게 맡겨도 좋은 판단:

• 로그 분석 및 가설 나열
• 검증용 명령어·SQL 생성
• 원인 후보의 우선순위 지정
• 문서 조사 및 참조

인간의 리뷰가 필수적인 판단:

• 운영 DB에 대한 쿼리 실행
• 설정 변경·배포 승인
• "이것이 원인입니다"라는 최종 판단
• 수정 코드의 리뷰 및 머지 (Merge)

"AI가 제안하고, 인간이 승인하여 실행한다"라는 흐름을 깨뜨리지 않는 것이 디버그 자동화의 안전한 운용에 필수적입니다.

팀으로의 전개

CLAUDE.md와 커스텀 명령어를 Git으로 관리함으로써, 팀 전체에 사고의 형식을 전개할 수 있습니다.

# 리포지토리 구성
project/
├── .claude/
...

신규 멤버의 온보딩(Onboarding)에 포함할 때는, "이 명령어를 사용하면 됩니다"가 아니라, 왜 이렇게 설계했는지에 대한 배경을 공유하는 것이 중요합니다. 형식을 모른 채 사용하면 다시 개인의 역량에 의존하는(Siloed) 문제가 발생합니다.

함정과 한계를 솔직하게 말하기

Claude Code가 어려워하는 디버깅 패턴

1. 환경 고유의 문제

운영 서버에 대한 SSH 접속이나 클라우드 콘솔 조작이 필요한 케이스에서 Claude Code는 정보를 가져올 수 없습니다. 로그를 복사하여 붙여넣거나, MCP (Model Context Protocol)를 통해 도구와 연결해야 합니다.

2. 휴리스틱 (Heuristic)이 필요한 문제

"뭔가 동작이 이상하다", "응답이 매끄럽지 않다"와 같은 정성적인 증상은 AI가 다루기 어렵습니다. 증상을 수치화 또는 언어화하여 전달하는 것이 전제 조건이 됩니다.

3. 깊은 도메인 지식 (Domain Knowledge)이 필요한 문제

비즈니스 로직의 깊은 부분("왜 이 계산식인가", "이 업무 규칙의 의도는 무엇인가")은 컨텍스트 (Context)를 대량으로 전달하더라도 정확도가 떨어집니다.

컨텍스트 오염 (Context Contamination) 문제

긴 디버깅 세션에서는 중간에 제시한 잘못된 가설이 이후의 답변에 영향을 미칠 수 있습니다.

대책:

# 새로운 가설을 세울 때는 새로운 세션을 시작한다
# 또는, 명시적으로 컨텍스트를 리셋한다
"방금 전까지의 가설은 일단 내려놓고, 처음부터 다시 생각해 주세요.
...

비용 설계

디버깅 자동화를 본격적으로 운용하기 전에 토큰 (Token) 소비량을 예측해 두어야 합니다.

Extended Thinking 모드는 디버깅의 질을 향상시키지만, 토큰 소비가 몇 배로 늘어납니다. 중요도가 높은 버그에만 적용하는 운용이 현실적입니다.

요약: 사고의 형식을 언어화하는 것이 시니어 엔지니어의 일이 된다

AI 코딩 도구가 보급된 지금, 시니어 엔지니어의 가치는 코드를 작성하는 속도가 아니라, 사고의 형식을 언어화하여 팀과 AI에게 전달하는 설계 능력으로 이동하고 있습니다.

본 기사의 요점을 정리합니다:

AI 디버깅 미궁의 원인은 보완 편향 (Completion Bias)과 컨텍스트 부족이다. 도구의 문제가 아니라 사용법의 문제다 -
가설 주도형 디버깅의 5단계 (증상 기술 → 재현 조건 → 원인 공간 매핑 → 격리 → 수정 및 방지)를 의식한다 -
CLAUDE.md로 디버깅 원칙을 고정함으로써 모든 세션에 사고의 형식이 적용되도록 한다 -
커스텀 커맨드 (Custom Command)로 프롬프트 템플릿화하여 팀원 모두가 동일한 품질의 조사를 수행할 수 있게 한다 -
Human-in-the-Loop 설계를 생략하지 않는다. AI는 가설과 검증 코드를 생성하고, 실행과 판단은 인간이 수행한다

오늘부터 바로 사용할 수 있는 체크리스트

□ CLAUDE.md에 디버깅 원칙을 추가했는가?
□ .claude/commands/ 에 debug-investigate 커맨드를 생성했는가?
□ 에러를 던지기 전에 "환경·재현 조건·시계열"을 정리했는가?
...

암묵지를 언어화하여 AI에게 전달하는 것──이러한 설계의 축적이 팀의 디버깅 효율을 끌어올립니다.

관련 기사

Discussion