Claude Code 디버깅 완전정리: 버그 잡는 AI 에이전트의 모든 것

"에러 메시지를 복사해서 구글에 검색하고, Stack Overflow를 뒤지고, 여러 파일을 열어가며 원인을 추적하고…" 이제 그럴 필요 없습니다. Claude Code에 에러 메시지를 붙여넣으면 스택 트레이스를 분석하고, 관련 코드를 찾아 읽고, 원인을 진단하고, 수정까지 해줍니다. 이 글에서는 Claude Code를 활용한 디버깅의 모든 기법을 완전 정리합니다.

1. Claude Code가 디버깅에 강한 이유

에러에서 수정까지 원스톱

일반적인 디버깅은 검색 → 이해 → 수정 → 테스트 4단계를 개발자가 직접 수행합니다. Claude Code는 이 전체 과정을 에이전트 루프로 자동화합니다.

[기존 디버깅]
  에러 발생 → 구글 검색 → Stack Overflow 참고
  → 원인 추측 → 코드 수정 → 테스트 → 반복…
  ⏱️ 평균 30분~수시간

[Claude Code 디버깅]
  에러 메시지 붙여넣기
  → 스택 트레이스 자동 분석
  → 관련 파일 검색 및 읽기 (Grep/Read)
  → 원인 진단 + 수정 제안
  → 코드 수정 + 테스트 실행
  ⏱️ 평균 30초~수분

디버깅 에이전트 루프

Claude Code의 디버깅은 단순한 Q&A가 아닙니다. 자율적인 에이전트 루프로 동작합니다.

1. 에러 컨텍스트 수집
   └── 에러 메시지, 스택 트레이스, 로그 분석
        ↓
2. 코드 탐색
   └── Grep/Glob으로 관련 파일 찾기
        ↓
3. 원인 진단
   └── 코드 읽기 → 로직 추적 → 근본 원인 파악
        ↓
4. 수정 적용
   └── Edit 도구로 코드 변경
        ↓
5. 검증
   └── 테스트 실행 → 통과 여부 확인
        ↓
6. 실패 시 → 1단계로 돌아가 재시도

핵심 포인트: Claude Code는 한 번의 수정으로 끝나지 않습니다. 테스트가 실패하면 자동으로 다시 분석하고 수정합니다.

2. 에러 메시지로 디버깅하기

기본 워크플로우

가장 간단하면서도 강력한 디버깅 방법은 에러 메시지를 그대로 붙여넣는 것입니다.

# 1단계: 에러 공유
> npm test를 실행하면 이런 에러가 나와:
  TypeError: Cannot read properties of undefined (reading 'map')
    at UserList (src/components/UserList.tsx:15:23)
    at renderWithHooks (node_modules/react-dom/...)

# 2단계: Claude Code가 자동으로 수행하는 작업
  - src/components/UserList.tsx 파일 읽기
  - 15번째 줄의 .map() 호출 분석
  - users 변수가 undefined가 되는 경로 추적
  - 관련 API 호출 코드 확인

# 3단계: 수정 제안 및 적용
  - 옵셔널 체이닝 또는 기본값 설정
  - 데이터 로딩 상태 처리 추가

효과적인 에러 공유 팁

방법	효과
에러 메시지 전체 복사	스택 트레이스까지 포함하면 정확도 높아짐
재현 명령어 포함	"npm test 실행 시" → Claude가 직접 실행 가능
기대 동작 설명	"로그인 후 대시보드로 이동해야 하는데 404가 나와"
간헐적 여부 언급	"가끔만 발생해" → 타이밍/레이스 컨디션 의심

파이프로 에러 전달하기

터미널 출력을 직접 Claude Code에 전달할 수도 있습니다.

# 빌드 에러를 파이프로 전달
cat build-error.txt | claude -p "이 빌드 에러의 원인을 분석하고 수정해줘"

# 테스트 실패 로그 분석
npm test 2>&1 | claude -p "실패한 테스트의 원인을 분석해줘"

3. 버그 유형별 디버깅 전략

런타임 에러

> src/api/users.ts에서 TypeError가 발생해.
  스택 트레이스는 이거야: [에러 붙여넣기]
  원인을 찾고 수정해줘.

Claude Code는 스택 트레이스의 호출 체인을 역추적하여 null/undefined 참조, 타입 불일치, 범위 초과 등의 원인을 찾습니다.

로직 버그

로직 버그는 에러가 발생하지 않지만 결과가 틀린 경우입니다. 기대 동작과 실제 동작을 함께 알려주는 것이 핵심입니다.

> calculateDiscount 함수에서 20% 할인을 적용하면
  100,000원이 80,000원이 되어야 하는데 98,000원이 나와.
  src/utils/pricing.ts를 확인해줘.

성능 문제

> 대시보드 페이지가 로딩에 5초 이상 걸려.
  프로파일링 결과 src/pages/Dashboard.tsx의
  useEffect에서 API를 반복 호출하고 있는 것 같아.
  원인을 분석하고 최적화해줘.

메모리 누수

> 앱을 오래 사용하면 메모리가 계속 증가해.
  힙 덤프를 보면 EventListener가 해제되지 않는 것 같아.
  src/hooks/ 폴더의 커스텀 훅에서 cleanup이 빠진 곳을 찾아줘.

경쟁 조건 (Race Condition)

> 사용자가 빠르게 버튼을 여러 번 클릭하면
  주문이 중복으로 생성돼.
  src/api/orders.ts의 createOrder 함수를 확인하고
  중복 방지 로직을 추가해줘.

4. Plan 모드로 복잡한 버그 분석하기

읽기 전용으로 안전하게 분석

복잡한 버그는 바로 수정하지 말고 Plan 모드로 먼저 분석하는 것이 효과적입니다.

# Shift+Tab으로 Plan 모드 진입

> [Plan 모드]
  결제 프로세스에서 간헐적으로 금액이 0원이 되는 버그가 있어.
  코드를 분석해서 가능한 원인을 모두 찾아줘.
  수정은 하지 말고 분석만 해줘.

Plan 모드에서 Claude Code는:

코드를 읽기만 하고 수정하지 않음
관련 파일을 탐색하고 진단 보고서 제공
여러 가능한 원인을 우선순위와 함께 나열
각 원인에 대한 수정 전략 제시

Plan → 실행 전환

분석이 끝나면 Tab으로 일반 모드로 돌아와 수정을 실행합니다.

# Tab으로 일반 모드 복귀

> 분석 결과 중 2번 원인(비동기 상태 경쟁)이 맞는 것 같아.
  해당 수정 전략대로 코드를 수정하고 테스트를 작성해줘.

5. 테스트 기반 디버깅

실패하는 테스트로 버그 재현

가장 신뢰할 수 있는 디버깅 방법은 먼저 실패하는 테스트를 작성하는 것입니다.

> calculateTax 함수에 버그가 있어.
  세율 10%에 금액 1000원을 넣으면 100이 나와야 하는데 110이 나와.
  1. 먼저 이 버그를 재현하는 테스트를 작성해줘
  2. 테스트가 실패하는 걸 확인한 다음
  3. 버그를 수정해서 테스트가 통과하게 해줘

디버깅 사이클

[Red]   실패하는 테스트 작성 → 버그 확인
          ↓
[Fix]   원인 분석 → 코드 수정
          ↓
[Green] 테스트 통과 확인
          ↓
[Full]  전체 테스트 스위트 실행 → 회귀 없음 확인

에지 케이스 발견

> 이 함수의 테스트를 실행해서 실패하는 케이스를 찾아줘.
  특히 경계값, null/undefined, 빈 배열, 큰 숫자 등
  에지 케이스를 중심으로 확인해줘.

Claude Code는 기존 테스트를 실행하고, 실패 원인을 분석하며, 놓친 에지 케이스를 추가로 발견합니다.

6. /doctor와 진단 도구 활용

/doctor 명령어

Claude Code 자체의 환경 문제를 진단하는 내장 명령어입니다.

> /doctor

# /doctor가 확인하는 항목
✓ Claude Code 버전 및 업데이트 상태
✓ 설정 파일 유효성 (JSON 형식, 타입 오류)
✓ MCP 서버 연결 상태
✓ 키바인딩 설정
✓ 컨텍스트 사용량 (CLAUDE.md 크기, MCP 토큰)
✓ 플러그인/에이전트 로딩 상태

/debug 명령어

현재 세션의 디버그 로그를 분석합니다.

> /debug 방금 실행한 명령이 왜 실패했는지 확인해줘

# 세션 디버그 로그를 자동으로 읽어서 분석
# Hook 매칭, 도구 실행 결과, 에러 내역 확인

디버그 모드 실행

# 전체 실행 과정을 상세하게 출력
claude --debug

# 확장 사고(Extended Thinking) 보기
# Ctrl+O로 verbose 모드 토글
# Claude의 내부 추론 과정이 회색 이탤릭으로 표시됨

진단 도구 비교

도구	용도	사용 시점
/doctor	환경·설정 진단	Claude Code가 이상 동작할 때
/debug	세션 로그 분석	특정 명령이 실패했을 때
--debug 플래그	상세 실행 로그	Hook·MCP 문제 추적할 때
Ctrl+O verbose	사고 과정 보기	Claude의 판단 이유를 알고 싶을 때

7. 로그 분석과 모니터링 디버깅

로그 파일 분석

Claude Code는 대용량 로그 파일도 효과적으로 분석합니다.

> server.log 파일을 분석해서 ERROR 레벨 로그만 추출하고
  에러 유형별로 그룹화해서 보여줘.
  가장 빈번한 에러부터 정리해줘.

파이프라인으로 로그 분석

# 최근 에러 로그만 추출해서 분석
tail -1000 /var/log/app.log | grep ERROR | claude -p "에러 패턴을 분석해줘"

# JSON 로그 파일 분석
cat app.log | claude -p "응답 시간이 1초를 넘는 요청을 찾아줘"

# 여러 로그 파일 비교 분석
claude -p "server.log와 database.log를 비교해서 타임라인을 맞춰줘"

MCP 서버로 모니터링 연동

# Sentry MCP 서버 연결
claude mcp add sentry -- npx @sentry/mcp-server

# PostgreSQL MCP로 데이터 상태 확인
claude mcp add postgres -- npx @anthropic/pg-mcp-server

# 디버깅 중 MCP 활용
> Sentry에서 최근 24시간 내 인증 관련 에러를 조회해줘
> DB에서 해당 사용자의 세션 레코드를 확인해줘

8. CI/CD 파이프라인 디버깅

헤드리스 모드로 자동 디버깅

CI/CD에서 테스트가 실패하면 Claude Code가 자동으로 디버깅합니다.

# GitHub Actions 예시
name: Auto Debug
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  debug-failures:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Debug with Claude Code
        run: |
          claude -p "CI 테스트가 실패했어.
            테스트를 실행하고 실패 원인을 분석해서 수정해줘" \
            --allowedTools "Bash,Read,Edit,Grep,Glob"

PR 자동 리뷰 + 버그 탐지

# PR에서 잠재적 버그를 자동 탐지
- name: Bug Detection
  run: |
    DIFF=$(git diff origin/main...HEAD)
    claude -p "이 PR의 변경사항에서 잠재적 버그를 찾아줘:
    $DIFF" --output-format json

구조화된 출력으로 처리

# JSON 형식으로 디버깅 결과 받기
claude -p "테스트를 실행하고 실패한 항목을 분석해줘" \
  --output-format json | jq '.result'

# 스트리밍 JSON으로 실시간 모니터링
claude -p "전체 테스트 스위트를 실행하고 결과를 보고해줘" \
  --output-format stream-json

9. 디버깅 프롬프트 베스트 프랙티스

좋은 디버깅 프롬프트의 구조

[증상] 무엇이 잘못되었는가
[위치] 어디서 발생하는가
[재현] 어떻게 재현하는가
[기대] 정상 동작은 무엇인가
[요청] 무엇을 해달라는 것인가

단계별 프롬프트 예시

# 나쁜 프롬프트
> 로그인이 안 돼. 고쳐줘.

# 좋은 프롬프트
> 로그인 페이지에서 올바른 이메일/비밀번호를 입력해도
  "Invalid credentials" 에러가 나와.
  src/auth/login.ts의 validateUser 함수를 확인해줘.
  최근에 bcrypt 버전을 업그레이드한 후부터 발생했어.
  먼저 원인을 분석하고, 수정한 후, 테스트도 작성해줘.

상황별 프롬프트 템플릿

런타임 에러 디버깅:

> [명령어]를 실행하면 [에러 메시지]가 발생해.
  스택 트레이스: [붙여넣기]
  원인을 찾고 수정해줘.

로직 버그 디버깅:

> [함수/기능]에서 [입력값]을 넣으면
  [기대 결과]가 나와야 하는데 [실제 결과]가 나와.
  [관련 파일]을 확인하고 수정해줘.

성능 디버깅:

> [기능]이 [현재 소요 시간]만큼 걸려.
  [프로파일링 정보]를 참고해서
  병목 지점을 찾고 최적화해줘.

회귀 버그 디버깅:

> [기능]이 [특정 커밋/업데이트] 이후 깨졌어.
  git log를 확인해서 어떤 변경이 원인인지 찾아줘.

중요 팁: 되돌리기와 방향 전환

# Claude가 잘못된 방향으로 수정할 때
# Esc를 눌러 즉시 중단

# 이전 상태로 되돌리기
> /rewind

# 새로운 방향 제시
> 아까 분석은 틀렸어. 이건 DB 커넥션 풀 문제야.
  src/db/pool.ts를 확인해줘.

10. 실전 디버깅 시나리오 모음

시나리오 1: API 응답 에러

> /api/users 엔드포인트가 500 에러를 반환해.
  서버 로그: "SequelizeConnectionError: Connection refused"
  최근 DB 마이그레이션을 실행한 후부터 발생해.
  원인을 찾고 수정해줘.

Claude Code의 접근:

DB 연결 설정 파일 확인
마이그레이션 히스토리 분석
스키마 변경으로 인한 불일치 탐지
연결 설정 또는 마이그레이션 수정

시나리오 2: 프론트엔드 상태 버그

> 장바구니에서 상품을 삭제하면 화면에는 사라지지만
  새로고침하면 다시 나타나.
  Redux store와 API 호출을 확인해줘.

Claude Code의 접근:

장바구니 관련 Redux 액션/리듀서 분석
삭제 API 호출 코드 확인
낙관적 업데이트와 실제 API 호출 간 불일치 발견
API 호출 누락 또는 에러 처리 수정

시나리오 3: 배포 환경에서만 발생하는 버그

> 로컬에서는 정상 동작하는데 프로덕션에서만
  이미지 업로드가 실패해.
  환경 변수, CORS 설정, 파일 크기 제한 순서로 확인해줘.

시나리오 4: 서브에이전트를 활용한 병렬 디버깅

복잡한 시스템에서 여러 원인이 의심될 때, 서브에이전트로 병렬 조사합니다.

> 결제 실패가 간헐적으로 발생해.
  서브에이전트를 써서 동시에 확인해줘:
  1. 결제 API 호출 코드 (src/payment/)
  2. 외부 PG사 연동 로그 (logs/pg/)
  3. DB 트랜잭션 처리 (src/db/transactions/)

시나리오 5: Hook으로 디버깅 자동화

반복적인 디버깅 작업은 Hook으로 자동화할 수 있습니다.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_OUTPUT\" | grep -q 'Error\\|FAIL\\|Exception'; then echo '⚠️ 에러가 감지되었습니다. 로그를 확인하세요.'; fi"
          }
        ]
      }
    ]
  }
}

자주 묻는 질문 (FAQ)

Q: 에러 메시지를 어디까지 붙여넣어야 하나요?
A: 전체 스택 트레이스를 포함하세요. Claude Code는 호출 체인 전체를 분석하여 근본 원인을 찾습니다. 에러 메시지만 복사하면 표면적인 수정에 그칠 수 있습니다.

Q: Claude Code가 수정한 코드를 신뢰해도 되나요?
A: 반드시 테스트로 검증하세요. "수정하고 테스트도 실행해줘"라고 요청하면 Claude Code가 자동으로 검증합니다. 중요한 코드는 직접 리뷰하는 것을 권장합니다.

Q: 디버깅 중 Claude Code가 잘못된 방향으로 가면 어떻게 하나요?
A: Esc를 눌러 즉시 중단하고, /rewind로 이전 상태로 돌아갈 수 있습니다. 새로운 힌트를 제공하여 올바른 방향으로 안내하세요.

Q: 프로덕션 로그를 안전하게 분석하려면?
A: 민감한 정보(비밀번호, 토큰 등)가 포함된 로그는 마스킹 후 전달하세요. 또는 Plan 모드에서 분석 전략만 받고 직접 실행하는 방법도 있습니다.

Q: 대용량 로그 파일은 어떻게 분석하나요?
A: tail -1000 app.log | claude -p "분석해줘" 처럼 파이프로 필요한 부분만 전달하세요. 전체 파일을 읽으면 컨텍스트 윈도우를 낭비합니다.

마무리

Claude Code 디버깅의 핵심을 정리합니다.

원칙	설명
에러 전체를 공유	스택 트레이스까지 포함해야 정확한 진단 가능
컨텍스트를 제공	재현 방법, 기대 동작, 최근 변경사항
Plan 모드 먼저	복잡한 버그는 분석 후 수정
테스트로 검증	수정 후 반드시 테스트 실행 요청
되돌리기 활용	잘못된 방향이면 Esc + /rewind
자동화 구축	Hook, CI/CD, MCP로 반복 디버깅 자동화

다음 편 예고: 25편에서는 Claude Code 꿀팁 총정리를 다룹니다. 생산성을 극대화하는 숨은 기능과 워크플로우를 모아서 정리합니다.

이 글은 Claude Code 공식 문서를 기반으로 작성되었습니다. 정확한 정보를 위해 공식 문서를 참고하세요.

저작자표시 비영리 변경금지 (새창열림)

'IT' 카테고리의 다른 글

Claude Code 꿀팁 총정리: 생산성 200% 올리는 숨은 기능 모음 (1)	2026.03.12
Claude Code 리팩토링 완전정리: 코드 구조 개선의 모든 것 (0)	2026.03.12
Claude Code로 웹앱 만들기 실전: 아이디어에서 배포까지 (0)	2026.03.12
Claude Code vs Cursor vs Copilot 완전비교: AI 코딩 도구 어떤 걸 써야 할까? (0)	2026.03.12
Claude Code JetBrains 연동 완전정리: IntelliJ부터 PyCharm까지 AI 코딩 (1)	2026.03.12

Claude Code 디버깅 완전정리: 버그 잡는 AI 에이전트의 모든 것

Claude Code 디버깅 완전정리: 버그 잡는 AI 에이전트의 모든 것

1. Claude Code가 디버깅에 강한 이유

에러에서 수정까지 원스톱

디버깅 에이전트 루프

2. 에러 메시지로 디버깅하기

기본 워크플로우

효과적인 에러 공유 팁

파이프로 에러 전달하기

3. 버그 유형별 디버깅 전략

런타임 에러

로직 버그

성능 문제

메모리 누수

경쟁 조건 (Race Condition)

4. Plan 모드로 복잡한 버그 분석하기

읽기 전용으로 안전하게 분석

Plan → 실행 전환

5. 테스트 기반 디버깅

실패하는 테스트로 버그 재현

디버깅 사이클

에지 케이스 발견

6. /doctor와 진단 도구 활용

/doctor 명령어

/debug 명령어

디버그 모드 실행

진단 도구 비교

7. 로그 분석과 모니터링 디버깅

로그 파일 분석

파이프라인으로 로그 분석

MCP 서버로 모니터링 연동

8. CI/CD 파이프라인 디버깅

헤드리스 모드로 자동 디버깅

PR 자동 리뷰 + 버그 탐지

구조화된 출력으로 처리

9. 디버깅 프롬프트 베스트 프랙티스

좋은 디버깅 프롬프트의 구조

단계별 프롬프트 예시

상황별 프롬프트 템플릿

중요 팁: 되돌리기와 방향 전환

10. 실전 디버깅 시나리오 모음

시나리오 1: API 응답 에러

시나리오 2: 프론트엔드 상태 버그

시나리오 3: 배포 환경에서만 발생하는 버그

시나리오 4: 서브에이전트를 활용한 병렬 디버깅

시나리오 5: Hook으로 디버깅 자동화

자주 묻는 질문 (FAQ)

마무리

'IT' 카테고리의 다른 글

관련글

댓글

티스토리툴바