디버깅: 로그·스택트레이스 함께 읽기 | 클로드 코드 완벽 마스터: AI 개발 워크플로우

디버깅 — 로그와 스택 트레이스를 함께 읽기

개발 시간의 절반 이상이 디버깅에 쓰인다는 통계가 있습니다. Claude Code는 에러 메시지를 받으면 관련 코드를 직접 읽고, 원인을 추론하고, 수정 후 재실행까지 처리합니다. 다만 효과적으로 쓰려면 "에러를 그냥 붙여넣기"보다 조금 더 구조화된 방식이 필요합니다.

디버깅 정보 제공 방법

# 나쁜 방법 — 컨텍스트 없는 에러만 전달
"이 에러 고쳐줘: TypeError: Cannot read properties of undefined"

# 좋은 방법 — 구조화된 디버깅 요청
"다음 에러가 발생했어:

 에러 메시지:
 TypeError: Cannot read properties of undefined (reading 'id')

 스택 트레이스:
 at UserCard (/app/components/UserCard.tsx:23:18)
 at renderWithHooks
 at mountIndeterminateComponent

 발생 조건:
 - /profile 페이지 접속 시
 - 로그인 상태에서만 발생 (비로그인은 정상)
 - 어제까지는 정상이었음

 최근 변경사항:
 - users 테이블에 display_name 컬럼 추가
 - UserCard 컴포넌트에서 user.display_name 사용 추가

 원인 파악하고 수정해줘."

Next.js / React 에러 패턴별 디버깅

Hydration Mismatch

에러: Hydration failed because the initial UI does not match

"이 Hydration 오류 분석해줘.
 의심 파일: components/DateDisplay.tsx
 서버와 클라이언트에서 다른 값을 렌더링하는 부분을 찾아줘.
 수정 방법: suppressHydrationWarning 남용 금지, 근본 원인 수정"

무한 렌더링 루프

에러: Too many re-renders

"useEffect 의존성 배열 문제로 무한 루프가 발생하는 것 같아.
 app/[locale]/dashboard/page.tsx의 useEffect 전부 검토해줘.
 의존성 배열에 객체/함수가 있는 케이스 중심으로."

Supabase RLS 오류

에러: new row violates row-level security policy

"Supabase RLS 오류야.
 테이블: job_applications
 액션: INSERT
 현재 RLS 정책과 실제 INSERT하려는 데이터를 비교해서
 어떤 조건이 충족되지 않는지 분석해줘."

로그 분석 — 패턴 찾기

# 로그 파일을 파이프로 전달
cat server.log | claude -p "
 이 로그에서:
 1. 에러/경고 패턴 분류
 2. 가장 자주 발생하는 에러 Top 3
 3. 시간대별 에러 급증 구간 있는지
 4. 즉시 수정이 필요한 Critical 이슈 목록
"

재현 불가능한 버그 — 체계적 접근

"간헐적으로 결제 완료 후 주문이 DB에 저장되지 않는 버그가 있어.
 항상 재현되지는 않음.

 다음 순서로 원인 찾아줘:
 1. app/api/webhook/payment/route.ts 로직 분석
    - 실패 가능한 지점 모두 표시
    - 에러 처리가 누락된 부분
 2. 비동기 처리 문제 여부 (await 누락, Promise 미처리)
 3. Supabase 트랜잭션 처리 방식 점검
 4. 재현용 테스트 케이스 작성"

디버깅 세션 관리

# 긴 디버깅 세션은 단계별로 분리
# 1단계: 원인 분석 (읽기 전용)
"에러 원인만 분석해줘. 아직 수정하지 마."

# 2단계: 수정 계획
"원인 파악됐어. 수정 방법 제안해줘. 사이드이펙트 있는지도."

# 3단계: 실행
"1번 방법으로 수정해줘. 수정 후 관련 테스트 실행해서 확인."

# 4단계: 재발 방지
"이 버그가 재발하지 않게 테스트 추가하고
 비슷한 패턴의 다른 코드도 점검해줘."

디버깅 도구 활용

# 타입 오류 전체 목록
npx tsc --noEmit 2>&1 | claude -p "이 타입 오류들을 우선순위별로 분류해줘"

# 번들 사이즈 분석
npm run build 2>&1 | claude -p "번들이 큰 이유와 최적화 방법 알려줘"

# 의존성 취약점
npm audit 2>&1 | claude -p "high/critical 취약점만 수정해줘"

효과적인 디버깅 요청의 핵심은 "발생 조건"과 "최근 변경사항"입니다. 에러 메시지 하나보다 "어제까지는 됐는데 오늘부터 안 된다 + 어제 이런 변경을 했다"는 정보가 Claude의 원인 특정 정확도를 크게 높입니다. 버그 리포트를 잘 쓰는 것이 디버깅의 절반입니다.

핵심 정리

에러만 붙여넣지 말고 발생 조건·최근 변경사항·스택 트레이스 함께 제공 — 원인 특정 속도 10배 향상
분석 → 계획 → 수정 → 재발 방지 4단계 분리 — 한 번에 수정하다 꼬이는 것 방지, 단계별 검증
재현 불가 버그는 에러 처리 누락·비동기 await 미처리·트랜잭션 롤백 세 영역 먼저 점검

관련 검색어 · 클로드 코드 디버깅 · AI 버그 수정 · Claude Code 에러 분석 · 클로드 코드 완벽 마스터 · 스택 트레이스 분석 · Next.js 디버깅