Claude Code 버그 리포트 템플릿: 막연한 오류를 재현 가능한 수정 입력으로 바꾸는 방법

Claude Code 디버깅은 bug report 품질에서 시작된다

“안 됩니다”만 전달하면 Claude Code는 추측으로 움직입니다. 좋은 bug report는 증상, 재현 절차, 기대 결과, 실제 결과, 제약, 검증 방법을 짧게 모읍니다.

이 글은 첫 작업 runbook 다음에 쓰는 템플릿입니다. 다음 세션으로 넘겨야 한다면 handoff 템플릿 도 같이 사용하세요.

복사해서 쓰는 bug report 템플릿

목표:
- 고칠 버그:
- 하지 않을 일:

환경:
- OS / browser / runtime:
- branch:
- 관련 명령:

재현 절차:
1.
2.
3.

기대 결과:
-

실제 결과:
-

로그 또는 스크린샷:
-

제약:
- 수정해도 되는 파일:
- 수정하지 않을 파일:
- 외부 서비스로 보내지 않기:

검증:
- 실행할 build/test:
- 눈으로 확인할 URL:

Claude Code 요청:
먼저 원인 후보를 3개로 좁히고, 최소 수정안, 수정 파일, 검증 절차를 써 주세요.
승인 전에는 편집하지 마세요.

좋은 예

고칠 버그:
모바일 폭에서 pricing CTA가 오른쪽으로 넘친다.

재현 절차:
1. /en/products/ 를 390px 폭으로 연다
2. pricing card까지 스크롤한다
3. CTA 오른쪽이 viewport를 넘는다

검증:
npm.cmd run build
Playwright로 390px 스크린샷 확인

나쁜 예

사이트가 이상합니다. 알아서 고쳐 주세요.

범위와 성공 조건이 없으므로 안정적인 작업이 되기 어렵습니다.

보내기 전 체크

• 재현 절차가 3분 안에 가능한가
• 성공 조건을 명령이나 스크린샷으로 확인할 수 있는가
• 건드리지 않을 파일을 썼는가
• 로그, URL, 스크린샷 중 하나가 있는가

다음 단계

명령은 무료 cheatsheet 에 정리하세요. 디버깅 prompt를 표준화하려면 50 Prompt Templates 가 빠릅니다. 팀 프로세스가 필요하면 상담 페이지 를 확인하세요.

실무에서는 조사와 수정을 나눈다

버그 수정의 흔한 실패는 원인이 좁혀지기 전에 patch를 만들게 하는 것입니다. 안정적인 순서는 재현, 원인 후보, 최소 수정입니다. 이렇게 해야 Claude Code의 출력을 리뷰할 수 있습니다.

이 bug report를 바탕으로 아직 수정하지 말고 조사만 해 주세요.
1. 재현 가능한가
2. 원인 후보 3개
3. 가장 가능성이 높은 코드 영역
4. 수정 전 읽어야 할 파일
5. 최소 수정으로 충분한가, 설계 변경이 필요한가

이 단계에서 재현 불가, 로그 부족, 범위 과대가 나오면 수정으로 넘어가지 마세요. 좋은 bug report는 답을 재촉하는 문서가 아니라 검증 가능한 조사 순서를 만드는 문서입니다.