에러 메시지·스택 트레이스·로그를 Claude와 함께 읽고 재현→원인 특정→수정→검증까지 이어지는 체계적 디버깅 방법.
디버깅 — 로그와 스택 트레이스를 함께 읽기
개발 시간의 절반 이상이 디버깅에 쓰인다는 통계가 있습니다. 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 디버깅