에러 디버깅하는 법

AI에게 에러를 제대로 전달하고, 빠르게 원인을 찾아 고치는 3단계 루틴

에러를 AI에게 잘 전달하는 법

에러 화면 캡처를 보내거나 "왜 안 돼?"라고 묻는 것보다 훨씬 빠른 방법이 있습니다.

필요한 정보 3가지

  1. 에러 메시지 전문 (맨 마지막 줄만 아니라 전체)
  2. 어떤 행동을 했을 때 발생했는지
  3. 시도해본 것 (있다면)

이 에러가 나고 있어:

[에러 메시지 붙여넣기]

npm run dev 했을 때 나와. 어제까지는 됐는데 package.json을 수정한 뒤부터 생겼어.

에러 종류별 대응

빨간 에러 (컴파일·문법 에러)

AI가 파악하기 가장 쉬운 에러입니다. 에러 메시지를 그대로 붙여넣으면 됩니다.

"@src/app/page.tsx 에서 이 에러가 나. 고쳐줘: Type 'string' is not assignable to type 'number'"

화면에 아무것도 안 뜸 (런타임 에러)

브라우저 개발자 도구(F12) → Console 탭의 빨간 메시지를 복사합니다.

브라우저 콘솔에 이 에러가 있어: [콘솔 에러 붙여넣기] 홈페이지 접속하면 흰 화면만 나와.

배포 후에만 나는 에러

Vercel 대시보드 → Deployments → 해당 배포 → Functions 로그 확인.

Vercel 배포 로그에 이 에러가 있어. 로컬에서는 잘 됐는데: [로그 붙여넣기]

API/네트워크 에러

브라우저 개발자 도구 → Network 탭 → 빨간 요청 클릭 → Response 탭 내용 복사.

API 호출이 실패하는데 응답이 이래: Status: 401 [Response 내용]

디버깅 3단계

1단계: 현상 재현

"어떤 조건에서 나는지 먼저 좁혀줘. 특정 페이지에서만 나는지, 로그인한 사람만 나는지."

2단계: 원인 파악

"원인이 뭔지 설명하고, 코드를 고치기 전에 내가 이해할 수 있게 이유를 먼저 알려줘."

3단계: 최소 수정

"다른 부분은 건드리지 말고, 이 에러만 최소한으로 고쳐줘."

Aside Browser로 에러 디버깅

[Aside Browser에 에러 화면을 열고] "지금 Aside에서 보이는 에러 화면을 분석해줘. 콘솔에서 에러를 찾아줘."

Chrome Extension 사이드 패널에서도 동일하게:

  1. F12 개발자 도구 열기
  2. Extension 사이드 패널에 에러 설명
  3. Claude가 Console·Network 탭을 보며 안내

에러가 반복될 때

같은 에러가 세 번 이상 나면 규칙 파일에 추가합니다.

CLAUDE.md에 추가해줘: "API 라우트는 항상 try/catch로 감싸고 에러 발생 시 콘솔에 로그를 남긴다."

앞으로 이 에러가 아예 안 생기게 됩니다.