Claude Code에 버그 조사를 부탁할 때, 무심코 이 에러 고쳐줘라고 로그만 붙여넣고 끝내버리기 쉽다. 이렇게 해도 그럴싸한 수정안은 돌아오지만, 이런 요청 방식에는 구조적인 약점이 있다.

재현 조건이 공유되지 않기 때문에, Claude가 "아마 이런 케이스겠지"라고 추측해서 고친다. - 고쳐졌는지 확인할 수단이 없어서, 고쳐졌는지 모르는 채로 대화가 진행된다. - 표면적인 에러 메시지만 지우고, 근본 원인이 남는다.

인간인 우수한 엔지니어에게 버그 조사를 부탁할 때도 갑자기 "고쳐줘"라고 말하지 않는다. 재현 절차를 전달하고, 가설을 세우게 한 뒤, 검증을 거쳐 최소한의 수정을 넣는다. Claude Code에 대해서도 마찬가지로, 요청 방법을 체계화하는 것만으로 조사 품질을 안정시키기 쉬워진다 (효과는 대상 코드나 로그의 양에 따라 달라진다).

이 기사에서는 그 "요청 방법의 틀"을 프롬프트 예시와 함께 정리한다.

먼저 지시의 골격을 하나의 프롬프트로 전달하는 것을 추천한다.

다음 버그를 조사해 주길 바란다. 갑자기 수정 코드를 작성하지 말고, 다음 순서로 진행해:
1. 재현: 이 버그가 발생하는 조건을 입력·상태·절차로서 언어화한다
2. 가설: 원인 후보를 여러 개 들고, 각각의 근거(코드의 해당 부분)를 제시한다
...

포인트는 **"갑자기 수정 코드를 작성하지 마"**라고 명시하는 것과, 단계별로 멈추게 하는 것이다. Claude Code는 내버려 두면 단번에 수정까지 달려가는 경우가 있으므로, 조사 페이즈와 수정 페이즈를 말로 구분한다.

로그는 대충 붙여넣기보다, 어떤 로그인지·언제 추출한 것인지를 덧붙이면 분류가 빨라지기 쉽다.

나쁜 예: 에러 메시지 한 줄만 붙여넣기.

좋은 예:

재현했을 때의 스택 트레이스(Stack Trace) 전문(처음부터 끝까지)은 다음과 같아:
TypeError: Cannot read properties of undefined (reading 'id')
at formatUser (src/user/format.ts:42)
at ...

이때의 입력은 user = null 이었어.
직전 로그에서는 fetchUser가 200을 반환했는데 본체가 비어 있었어.

스택 트레이스는 생략하지 말고 처음부터 끝까지 전달한다. 중간을 생략하면 Claude가 프레임을 추측으로 보완해 버릴 수 있다. 내용이 길어서 컨텍스트(Context)를 압박하는 경우에는, 관련 있어 보이는 범위를 직접 잘라내기보다, 이 로그를 파일로 저장했으니 읽어줘라고 하는 편이 낫다.

...

debug.log에 에러 발생 시의 로그를 출력했어. 읽고, 에러와 관련된 행만 추출해서 원인의 실마리를 제시해 줘.

Claude Code는 워크스페이스 내의 파일을 직접 읽을 수 있으므로, 긴 로그는 파일로 전달하는 것이 다루기 쉽다.

...

이 버그의 재현 절차를 내가 직접 재현할 수 있는 수준까지 구체화해 줘.
- 필요한 전제 상태 (DB·환경 변수·로그인 상태 등)
- 조작 절차
- 기대되는 결과와 실제로 발생하는 결과
모르는 전제가 있다면 추측하지 말고 질문해 줘.

모르는 전제가 있다면 질문해 줘

...

이 에러의 근본 원인을 특정해 줘.
- "왜 user가 undefined가 되는지"를 코드를 따라가며 설명해 줘
- 증상(에러 메시지)에 대한 대증요법이 아니라, 원인 그 자체를 지목해 줘
- 원인이 여러 개일 수 있다면, 어떤 것이 이번 케이스인지 구분하는 방법도 알려줘

대증요법이 아니라 원인을

...

수정하기 전에, 이 버그를 재현하는 실패 테스트를 하나 작성해 줘.
- 지금은 실패하는(빨간색이 되는) 것을 확인해 줘
- 그 테스트의 이름과 내용을 보여줘
- 확인이 되면 멈춰줘. 수정은 그 다음에.

테스트가 실패(Red)하는 것을 확인한 뒤에 수정을 진행하면,

...

방금 전의 실패 테스트가 통과하도록 최소한의 수정을 넣어줘.
- 기존의 다른 테스트를 망가뜨리지 않았는지 테스트 전체를 실행해서 확인해 줘
- 관계없는 부분의 리팩토링(Refactoring)은 이번에 하지 마

최소한

...

적용하기 전에, 변경하는 차이점(Diff)과 그 이유를 설명해 줘.
- 어떤 파일의 무엇을, 왜 바꾸는지
- 이 수정으로 재현 테스트가 통과하는 이유
- 부작용(Side Effect)이 나타날 만한 곳은 있는지

차이점의 의도를 언어화하게 하면, 우리 쪽에서도 타당성을 판단하기 쉽고, Claude가 "일단 통과했으니까 OK"라며 진행하는 것을 방지하기 쉽다. 납득이 되면 OK, 적용해로 진행한다.

버그 조사는 매번 처음부터 지시를 생각하기보다 틀을 하나 가지고 있는 것이 편해진다. 요점은 이것뿐이다.

• 갑자기 수정하게 하지 않기 (조사와 수정을 분리하기)
• 로그는 전문(Full text) + 문맥으로 전달, 길다면 파일로 전달하기
• 재현 절차를 언어화하게 하고, 스스로도 재현하기
• 대증요법이 아닌 근본 원인을 말하게 하기
• 실패하는 테스트로 고정한 뒤, 최소 수정하기
• 적용하기 전에 차이(diff)의 의도를 리뷰하기

이 형식을 프로젝트의 CLAUDE.md에 「버그 조사 진행 방식」으로 적어두면, 매번 붙여넣지 않아도 Claude Code가 이를 따르므로 운영하기 편리하다.

이러한 「Claude Code에게 부탁하는 방법」을 재사용 가능한 형태로 만든 것을 무료 GitHub 리포지토리 claude-code-skills-starter를 통해 4가지 Claude Code 스킬로 공개하고 있습니다. Claude Code의 실전적인 사용법은 X @k___n___t_1125에서도 발신 중입니다.