버그 디버깅과 리팩토링

버그 수정은 클로드 코드가 가장 빛나는 영역입니다. 핵심 요령은 단 하나, 에러 메시지를 요약하지 말고 통째로 붙여넣는 것입니다. 에러 메시지는 의사에게 보여주는 X-ray 사진과 같습니다. "어디가 좀 아파요"보다 사진 한 장이 훨씬 정확합니다.

디버깅 루프: 재현 → 원인 → 수정 → 검증

좋은 디버깅은 '고치기'가 아니라 '루프'입니다. 바로 고치라고 시키면 클로드가 증상만 가리는 임시방편을 내놓을 수 있습니다. 아래 순서를 지시에 포함시키세요.

디버깅 루프 따라하기

1. 재현: 에러 메시지 전체와 '어떤 동작을 하면 발생하는지'를 클로드에게 전달합니다.
2. 원인 분석: "바로 고치지 말고, 먼저 원인을 분석해서 설명해 줘"라고 요청합니다.
3. 가설 확인: 클로드의 원인 설명이 납득되는지 읽어 봅니다. 애매하면 "그 가설을 검증할 방법이 있어?"라고 되묻습니다.
4. 수정: 원인이 확실해지면 최소한의 수정을 요청합니다.
5. 검증: 테스트나 실행으로 실제로 고쳐졌는지 확인시킵니다. "고쳤다"는 말만 믿지 마세요.
6. 재발 방지: "이 버그를 잡는 테스트 코드를 추가해 줘"로 마무리합니다.

디버깅 요청 프롬프트 (틀)

버그를 고치고 싶어.

[증상] 상품 목록 페이지에서 스크롤을 내리면 앱이 멈춰.
[재현 방법] 홈 → 상품 목록 → 빠르게 스크롤
[에러 메시지]
TypeError: Cannot read properties of undefined (reading 'map')
    at ProductList (ProductList.tsx:42)

바로 고치지 말고 이 순서로 진행해 줘:
1. 원인을 분석해서 설명
2. 내가 확인하면 최소한의 수정
3. 수정 후 npm test로 검증

말로 설명하기 어려운 UI 버그는 스크린샷을 활용하세요. 스크린샷 이미지를 클립보드에 복사한 뒤 입력창에 붙여넣으면(맥은 Ctrl+V), 클로드가 화면을 직접 보고 문제를 파악합니다.

리팩토링: 안전망 먼저, 작게 나눠서

리팩토링(refactoring)은 동작은 그대로 두고 코드 구조만 개선하는 작업입니다. '동작이 그대로'임을 보장하려면 안전망, 즉 테스트가 필요합니다. 테스트가 없다면 리팩토링 전에 만들게 하세요.

안전한 리팩토링 요청

@src/utils/priceCalculator.ts 이 파일이 300줄이 넘어서 정리하고 싶어.

1. 먼저 현재 동작을 보장하는 테스트가 있는지 확인하고, 없으면 핵심 동작에 대한 테스트부터 작성해 줘.
2. 테스트가 통과하는 것을 확인한 뒤, 함수를 역할별로 작은 파일로 분리해 줘.
3. 분리 후에도 같은 테스트가 전부 통과하는지 검증해 줘.
4. 외부에서 이 파일을 import하는 곳이 깨지지 않게 주의해 줘.

"고쳤습니다"라는 클로드의 보고를 그대로 믿지 마세요. 반드시 테스트 실행, 앱 실행, 화면 확인 같은 '증거'를 요구하세요. 검증 없는 수정 보고는 절반만 끝난 작업입니다.

디버깅과 리팩토링 모두 공통 원칙은 같습니다. 원인 없이 고치지 않기, 검증 없이 믿지 않기, 한 번에 크게 바꾸지 않기. 이 세 가지만 지키면 클로드 코드는 매우 믿음직한 수리공이 됩니다.