Claude Code 상세 사용법 11: 디버깅과 테스트 루프를 맡기는 법 | DAKER 커뮤니티

Claude Code 상세 사용법 11: 디버깅과 테스트 루프를 맡기는 법

클로드 코드에게 "이거 고쳐줘"라고 던지면 운이 좋을 때만 빠르다. 공식 Common workflows와 Troubleshooting 문서를 기준으로 보면 안정적인 디버깅은 재현, 범위 격리, 최소 수정, 검증 기록의 순서로 닫아야 한다. 바이브코딩에서도 이 순서를 고정하면 AI 코딩 결과가 감이 아니라 증거가 된다.

아래 Mermaid는 디버깅을 감으로 밀어붙이지 않고, 실패 재현부터 리뷰 증거까지 닫는 흐름을 한눈에 보여준다. SVG 다이어그램과 함께 보면 Claude Code에게 어디까지 맡기고 어디서 사람이 결정을 회수해야 하는지 분명해진다.

flowchart LR
  A[실패 로그 수집] --> B[재현 명령 고정]
  B --> C[읽기 전용 원인 조사]
  C --> D{원인 신뢰도 충분?}
  D -->|아니오| E[가설 3개 이하로 재정리]
  E --> C
  D -->|예| F[가장 작은 패치]
  F --> G[타깃 테스트 재실행]
  G --> H{통과?}
  H -->|아니오| E
  H -->|예| I[관련 테스트와 리뷰 메모]

1. 첫 프롬프트에는 실패 명령을 넣는다

버그 설명보다 중요한 것은 Claude가 직접 반복 실행할 수 있는 명령이다. 실패한 테스트, 에러 로그, 최근 변경 범위를 한 번에 준다.

이 브랜치에서 pnpm test:checkout 이 실패한다.
먼저 실패를 재현하고, 원인 후보를 파일별로 좁힌 뒤,
가장 작은 수정만 제안해. 수정 전에는 관련 파일을 읽고
수정 후에는 같은 테스트를 다시 실행해.

로그가 길면 마지막 80줄과 첫 실패 지점을 준다. "아마 결제 쪽" 같은 추측은 보조 정보로만 둔다. Claude Code는 repo를 읽을 수 있으므로 사람이 결론을 먼저 정해 주면 오히려 오진이 늘어난다.

2. 조사와 수정을 분리한다

실무에서는 한 번에 고치게 하지 말고 먼저 조사 모드로 둔다. 특히 shared utility, auth, billing처럼 영향 반경이 넓은 영역은 read-only로 시작한다.

Do not edit files yet.
Find the smallest set of files related to this failure.
Return the suspected cause, confidence, and exact test commands.

그 다음 "1번 원인만 고쳐"라고 좁힌다. 이 방식은 agentic coding에서 불필요한 리팩터링을 막고 코드 리뷰 시간을 줄인다.

3. 테스트는 계단식으로 실행한다

수정 직후에는 전체 CI보다 가장 작은 재현 테스트가 먼저다. 통과하면 관련 단위 테스트, 마지막으로 lint나 typecheck를 붙인다.

pnpm test:checkout
pnpm test -- --runInBand checkout
pnpm typecheck
pnpm lint

테스트가 오래 걸리면 Claude에게 "짧은 검증과 긴 검증을 나누어 보고하라"고 시킨다. 짧은 검증은 즉시 피드백용, 긴 검증은 PR 전에 돌릴 증거다.

4. 실패하면 원인 목록을 다시 쓰게 한다

첫 수정이 실패했을 때 바로 두 번째 패치를 시키면 코드가 흐려진다. 먼저 실패 로그를 다시 붙이고 원인 목록을 갱신하게 한다.

수정 후에도 같은 테스트가 실패했다.
새 로그를 기준으로 기존 가설 중 무엇이 틀렸는지 표시하고,
새 가설을 최대 3개로 줄여라. 아직 파일은 수정하지 마라.

이 한 박자가 Claude Code troubleshooting의 핵심이다. 컨텍스트가 꼬이면 /clear나 새 세션으로 실패 재현 정보만 다시 넘기는 편이 낫다.

5. 마무리는 사람이 읽을 수 있는 증거로 닫는다

마지막 요청은 구현 설명이 아니라 검증 기록이어야 한다.

Summarize the root cause, files changed, tests run,
remaining risks, and what a reviewer should inspect first.

Senior takeaway: Claude Code 디버깅은 "많이 고치는 능력"보다 "틀린 가설을 빨리 버리는 루프"가 중요하다. 재현 명령, 작은 패치, 테스트 자동화, 짧은 리뷰 메모가 연결될 때 클로드 코드는 개발 생산성을 실제로 올린다.