Claude Code 디버깅 잘 시키는 법: '고쳐줘' 대신 재현·가설·검증을 시키는 프롬프트

버그를 발견하면 “이거 고쳐줘”부터 입력하기 쉽습니다. 하지만 원인을 확인하지 않은 상태에서 수정부터 시작하면 증상만 가리거나, 관련 없는 코드까지 바꾸기 쉽습니다. 특히 1인 개발자는 리뷰어가 없기 때문에 AI가 낸 수정안을 직접 검증하는 절차가 더 중요합니다.

조코헌트에 출시된 프로덕트는 314개입니다. 출시한 뒤 빠르게 반응을 확인해야 하는 상황도 많고, 실제로 출시 첫 24시간 안에 업보트나 댓글을 하나라도 받은 프로덕트는 52%입니다. 이런 환경에서는 “빨리 고치기”보다 “짧은 시간 안에 정확히 원인을 좁히는 흐름”을 만드는 편이 유리합니다.

1. ‘고쳐줘’가 위험한 이유

Claude Code는 주어진 증상과 주변 코드를 바탕으로 가장 그럴듯한 수정안을 찾습니다. 문제는 증상이 곧 원인은 아니라는 점입니다. 로그인 버튼이 반응하지 않아도 원인은 이벤트 핸들러, 인증 상태, API 응답, 환경변수, 권한 처리 중 하나일 수 있습니다.

증상과 원인을 분리하기

먼저 다음 세 가지를 따로 적어 보세요.

기대한 동작: 사용자가 어떤 결과를 봐야 하는가
실제 동작: 현재 무엇이 다르게 나타나는가
발생 조건: 어떤 입력, 계정 상태, 브라우저, 데이터에서 재현되는가

이렇게 나누면 AI가 코드 전체를 추측하기보다 관찰 가능한 사실에서 출발하게 됩니다. 프로젝트 규칙과 실행 방법을 정리해 두고 싶다면 CLAUDE.md 작성법도 함께 참고할 만합니다.

2. 첫 프롬프트는 수정이 아니라 재현 요청으로

첫 단계에서는 코드 변경을 금지하는 것이 좋습니다. Claude Code에 문제를 해결하라고 하기보다, 현재 상태에서 버그를 재현하고 관찰 결과를 보고하게 하세요.

바로 쓸 수 있는 재현 프롬프트

이 버그를 아직 수정하지 말고 먼저 조사해줘.

문제: [증상]
기대한 동작: [기대 결과]
재현 절차:
1. [첫 단계]
2. [두 번째 단계]
3. [문제가 나타나는 단계]

다음 형식으로 답해줘.
- 재현 여부
- 실제로 관찰한 결과
- 관련 로그와 에러
- 조사한 파일과 이유
- 아직 확인하지 못한 부분
코드는 변경하지 마.

재현에 실패했다면 억지로 수정안을 내게 하지 말고, 필요한 로그나 입력값을 추가로 물어보게 하세요. 재현되지 않은 버그의 수정은 대부분 추측에 가깝습니다.

3. 원인은 하나로 단정하지 말고 가설로 좁히기

재현이 확인되면 “원인이 뭐야?”라고 묻기보다 가능한 원인을 몇 가지로 나누고, 각각을 확인할 증거를 요구하세요.

가설 표를 만들게 하기

현재 증상을 설명할 수 있는 원인 가설을 우선순위 순서로 3개 제시해줘.
각 가설마다 다음을 적어줘.
- 근거
- 반대 증거
- 확인에 필요한 로그나 코드 위치
- 가장 작은 확인 방법
아직 코드는 수정하지 말고, 가설을 검증할 조사 계획만 작성해줘.

좋은 가설은 “아마 상태 관리 문제”처럼 넓지 않습니다. “API 응답은 성공이지만 클라이언트가 갱신된 세션을 읽지 못해 보호된 화면으로 돌아간다”처럼 관찰 가능한 흐름으로 표현해야 합니다.

이 단계에서 AI가 파일을 많이 읽는다고 좋은 것은 아닙니다. 각 파일을 왜 확인하는지 설명하게 하고, 관련 없는 리팩터링은 범위에서 제외하세요. 큰 문제를 먼저 계획으로 쪼개는 방식은 Claude Code에 계획 먼저 시키는 워크플로우와도 연결됩니다.

4. 증거를 모은 뒤 최소 수정하기

가설이 좁혀졌다면 이제 로그, 테스트, 재현 명령으로 원인을 입증합니다. “이 코드가 의심된다”와 “이 코드 때문에 실패한다”는 다릅니다.

수정 범위를 제한하는 문장

가설 B가 맞는지 확인하는 테스트 또는 로그를 먼저 추가해줘.
확인 결과를 보고한 뒤에만 수정해.
수정 시에는 원인과 직접 관련된 파일만 변경하고,
동작 변경이 없는 리팩터링과 포맷팅은 하지 마.
변경 전후의 기대 동작도 설명해줘.

최소 수정은 되돌리기 쉽고, 문제가 다시 생겼을 때 원인을 추적하기도 쉽습니다. 여러 파일을 한 번에 정리하고 싶다면 작업을 나눠 별도 브랜치에서 진행하는 git worktree 병렬 개발 방법을 참고하세요.

5. 마지막은 검증 보고서로 닫기

수정이 끝났다는 말만으로는 충분하지 않습니다. 같은 재현 절차를 다시 실행했는지, 관련 테스트가 통과했는지, 새로 생긴 위험은 무엇인지 확인해야 합니다.

검증 프롬프트

수정 후 다음 순서로 검증해줘.
1. 기존 재현 절차를 다시 실행
2. 관련 테스트 실행
3. 정상 케이스와 실패 케이스 비교
4. 변경 파일과 변경 이유 요약
5. 아직 검증하지 못한 위험 보고
검증하지 못한 항목은 통과했다고 말하지 마.

마지막에는 “무엇을 바꿨나”보다 “어떤 증거로 문제가 해결됐다고 판단했나”를 확인하세요. 디버깅은 코드 생성 작업이 아니라 가설을 줄이고 증거를 쌓는 작업입니다. 이 흐름을 반복 프롬프트나 훅으로 고정하면, AI에게 맡기는 작업도 Claude Code 훅 자동화 패턴처럼 일정한 품질로 운영하기 쉬워집니다.