디버깅 펜팔: 상상의 팀원에게 편지를 쓰면 어려운 문제를 더 빨리 푸는 이유

한 번이라도 고집 센 버그나 이해 안 되는 에러 메시지 때문에 몇 시간을 모니터만 바라보며 버텨본 적이 있다면, ‘막혀 있는 상태’가 얼마나 답답한지 잘 알 겁니다. 로그를 더 찍어 보고, 검색도 해 보고, 이것저것 코드를 바꿔 보지만… 아무것도 나아지지 않을 때가 있죠.

이 막힌 상황을 풀어 주는 건, 꼭 새로운 툴이나 더 똑똑한 IDE가 아닙니다. 훨씬 단순한 것, 바로 문제를 말로 풀어서 설명해 보는 것입니다.

이미 러버덕 디버깅(rubber duck debugging) 을 들어본 분도 있을 겁니다. 내 책상 위의 오리 인형 같은 물건을 앞에 두고, 코드 한 줄 한 줄을 설명해 가며 디버깅하는 방법이죠. 여기서 한 발 더 나아간 변형이 있는데, 이 글에서는 이를 디버깅 펜팔(debugging pen pal) 이라고 부르겠습니다. 상상의 팀원에게 메시지를 보내듯이, 글로 디버깅 상황을 써 내려가는 방식입니다.

너무 단순해 보일 수 있습니다. 하지만 이 “펜팔”에게 글을 쓰는 습관을 들이면, 숨어 있던 실수를 끌어내고 디버깅 속도를 높이며, 동시에 커뮤니케이션 능력까지 함께 키울 수 있습니다.

왜 ‘설명하기’가 그렇게 잘 먹히는가

펜팔 이야기로 들어가기 전에, 왜 ‘설명하는 행위’ 자체가 그렇게 강력한지부터 짚고 넘어가겠습니다.

문제를 자연어로, 한 단계씩 설명하기 시작하면 다음과 같은 일들이 벌어집니다.

생각이 선형(linear) 구조로 정리된다.
코드와 시스템은 복잡하고 가지를 많이 칩니다. 글을 쓰면 그 복잡함을 ‘먼저 이것, 그다음 저것, 그리고 이것은 저것에 의존한다’처럼 순서가 있는 이야기 구조로 펴야 합니다. 이 과정을 거치면서, 앞뒤가 안 맞는 부분이나 비어 있는 구멍이 눈에 띄기 시작합니다.
숨겨진 가정을 드러낸다.
머릿속에서만 생각할 때는, “이 함수는 당연히 리스트를 반환하지”, “이 변수는 여기쯤이면 정의돼 있을 거야” 같은 걸 쉽게 지나칩니다. 그런데 글로 쓰다 보면, ‘정말 그런가?’라는 질문을 하게 됩니다. 그리고 자주, 바로 그 “당연한” 가정이 버그의 근원이라는 걸 발견하게 됩니다.
속도를 살짝 늦춰 준다.
답답할 때일수록 우리는 코드를 대충 훑어보고, 찍어 보고, 여기저기 점프하면서 건드리게 됩니다. 글을 쓰면 자연스럽게 속도가 조금 느려집니다. 이 ‘아주 작은 감속’이 조건 하나 빠진 부분이나 off-by-one 오류 같은 걸 발견하는 데 놀랄 만큼 큰 도움이 됩니다.

여기서 중요한 건 ‘누구에게 설명하느냐’가 아닙니다. 진짜 핵심은 설명하는 행위 그 자체입니다.

러버덕에서 디버깅 펜팔로

러버덕 디버깅은 이런 통찰에 기반합니다. 문제를 설명하는 행위 자체가, 설령 그 대상이 말이 통하지 않는 물건일지라도, 종종 문제를 스스로 해결하게 해 준다는 거죠.

디버깅 펜팔은 여기서 살짝 비틀린 버전입니다.

책상 위 오리 인형에게 말로 설명하는 대신, 도움을 주는 상상의 팀원에게 메시지를 쓰듯이 글로 문제를 풀어 씁니다.

왜 이게 도움이 될까요?

말하기보다 쓰기가 자연스럽게 더 구조적이기 때문입니다.
글을 쓰면 어쩔 수 없이 문장과 문단 단위로 생각을 묶게 됩니다. 그 과정에서 논리와 세부 내용을 더 또렷하게 정리하게 되죠.
‘팀원’은 물건보다 훨씬 실제감 있게 느껴집니다.
어떤 사람은 오리 인형이나 화분을 보고 말을 거는 게 참 어색합니다. 반면 상상의 팀원에게 메시지를 쓴다고 생각하면, 평소에 하던 업무 커뮤니케이션과 크게 다르지 않게 느껴집니다.
자동으로 더 명확한 커뮤니케이션 스타일을 쓰게 됩니다.
이 글을 ‘다른 사람이 읽는다’고 가정하는 순간, 더 일관되고 빠짐없이, 구체적으로 쓰려고 노력하게 됩니다.

결과적으로, 러버덕 디버깅이 주는 장점은 그대로 가져가면서도, 훨씬 자연스럽고 실천하기 쉬운 방식으로 연습하게 됩니다.

디버깅 펜팔 쓰는 방법 (단계별 가이드)

특별한 도구는 필요 없습니다. 글을 쓸 수 있는 공간이면 충분합니다. 메모 앱, scratch 파일, 개인용 문서, 심지어 종이 노트도 괜찮습니다.

아래처럼 해 보면 됩니다.

1. 상황(context)부터 설명하기

상상의 팀원이 지금 막 프로젝트에 합류했다고 생각하고, 배경 설명을 해 준다고 상상해 보세요.

지금 무엇을 하려고 하나요?
이 기능이나 스크립트는 원래 무엇을 해야 하나요?
그런데 지금은 실제로 어떤 일이 벌어지고 있나요?

예시 시작 문장은 이렇게 쓸 수 있습니다.

"지금 generateReport 엔드포인트 작업을 하고 있어. 날짜 범위를 받아서, DB에서 해당 기간에 맞는 레코드를 조회하고, 그걸 CSV 파일로 반환해야 해. 현재는 엔드포인트가 200을 응답하긴 하는데, CSV 내용이 비어 있어."

2. 기대 동작 vs 실제 동작을 분리해서 적기

사람 말로, 아주 분명하게 둘의 차이를 써 줍니다.

기대 동작: “1월 1일부터 1월 31일까지의 데이터를 주면, 기간에 해당하는 모든 행이 포함된 CSV가 나와야 한다.”
실제 동작: “헤더만 있고, 데이터 행은 하나도 없는 CSV가 나온다.”

이렇게 정리하는 것만으로도, 정확히 무엇이 문제인지 선명해지고, “애초에 내가 테스트하고 있는 게 맞는 건가?”라는 의문이 들 수도 있습니다.

3. 시스템이 어떻게 동작하는지 한 단계씩 따라가기

펜팔이 코드를 직접 볼 수 없다고 가정해 보세요. 당신은 ‘무슨 일이 일어나는지’를 말로 설명해야 합니다.

어떤 함수들이 어떤 순서로 실행되나요?
어떤 조건들이 참이어야 하나요?
각 단계에서 어떤 자료구조가 사용되나요?

가능한 구체적으로 적습니다.

"먼저 컨트롤러에서 query parameter에서 startDate, endDate를 파싱해. 그다음 ReportService.fetchData(start, end)를 호출해서 레코드 리스트를 받아와야 해. 그 리스트를 CsvFormatter.toCsv(records)에 넘겨서 문자열로 변환하고, 마지막에 그 문자열을 HTTP 응답으로 내려보내."

이렇게 쓰다 보면 중간에 문득 이런 생각이 들 수 있습니다. “잠깐, 날짜 유효성 검사를 했나?” 혹은 “fetchData가 null을 반환하면 어떻게 되지?”

4. 내가 하고 있는 ‘가정’을 적어 보기

이 단계가 아주 중요합니다. 머릿속에서 “당연히…”, “원래…”라고 넘어가는 부분을 전부 글로 끌어내야 합니다.

가정은 이런 식으로 드러납니다.

“입력 값 검증은 이미 끝난 상태다.”
“이 함수는 항상 빈 리스트가 아닌 리스트를 반환한다.”
“dev 환경과 prod 환경의 설정은 동일하다.”

한 번 글로 써 놓으면, 이런 가정은 실제로 검증해 볼 수 있는 대상이 됩니다. 많은 버그가, 결국 현실이 거부해 버린 가정일 뿐인 경우가 상당히 많습니다.

5. 이미 시도해 본 것들을 정리하기

상상의 팀원도 같은 걸 반복해서 보길 원치 않을 겁니다. 이미 해 본 것들을 정리해서 써 둡니다.

추가로 넣어 본 로그들
실행해 본 명령어들
시도해 본 실험이나 코드 수정들

이렇게 써 두면 같은 시도를 빙빙 반복하는 일을 줄일 수 있고, 내가 문제의 아주 좁은 한 지점만 계속 건드리고 있었던 건 아닌지도 돌아보게 됩니다.

6. 펜팔에게 ‘구체적인 질문’ 던지기

실제 팀원에게 메시지를 보내듯이, 글의 끝을 구체적인 질문으로 마무리합니다.

“레코드가 실제로 존재하는데도 fetchData가 빈 리스트를 반환할 수 있는 경우가 있을까?”
“CsvFormatter.toCsv가 null 값을 어떻게 처리하는지 내가 잘못 이해하고 있을 가능성이 있을까?”
“내가 보내는 날짜 범위가 실제 DB에 저장된 레코드의 날짜와 잘 매칭되는지 더 확실하게 확인할 방법이 있을까?”

이렇게 질문을 구체적으로 만들다 보면, 그 순간에 스스로 답을 떠올리는 경우도 꽤 많습니다.

왜 펜팔 방식이 특히 잘 먹히는가

이제 이 방식을 조금 더 큰 그림에서 보겠습니다.

1. 내가 몰랐던 ‘오해’를 드러내 준다

막혀 있을 때, 우리는 보통 아무것도 모르는 상태라서 막힌 게 아닙니다. 사실은 거의 다 알고 있는데, 그중 어딘가에서 작은 오해 하나가 끼어 있기 때문인 경우가 많습니다.

글을 쓰면 다음을 전부 말로 풀어야 합니다.

각 부분이 무엇을 하는지
그 부분들이 어떻게 연결되는지
각 단계에서 무엇이 사실이라고 믿고 있는지

이 믿음들은 글로 써지는 순간 자동으로 검증을 당합니다. 여기저기서 이런 모순들이 튀어나오기 시작합니다.

“항상 리스트를 반환한다고 써 놓고, 실패하면 null을 반환한다고도 써 놨네?”
“데이터가 정렬돼 있다고 가정했는데, 정렬하는 코드는 어디에도 없네?”

2. 디버깅이 곧 커뮤니케이션 연습이 된다

디버깅을 할 때마다, 동시에 ‘설명하는 연습’을 하고 있는 셈이 됩니다.

문제를 짧고 명확하게 요약하는 능력이 좋아집니다.
중요한 정보와 불필요한 정보를 가려내는 감각이 생깁니다.
구체적이고 타깃이 분명한 질문을 하는 법을 익힙니다.

시간이 지나면 이 능력은 실제 협업에서도 드러납니다. 더 좋은 버그 리포트, 더 이해하기 쉬운 문서, 더 효과적인 팀 내 메시지를 만들어 내게 됩니다.

3. 물건에게 말하는 것보다 꾸준히 하기 쉽다

어떤 사람은 러버덕 디버깅이 잘 맞지만, 어떤 사람은 아무리 생각해도 물건에 말 거는 게 어색해서 손이 안 가기도 합니다.

디버깅 펜팔은 훨씬 자연스럽습니다. 이유는 간단합니다.

평소에 하던 업무 커뮤니케이션(메신저, 이메일, 티켓 코멘트 등)과 비슷한 형태입니다.
이 ‘편지들’을 저장해 두고, 검색하고, 나중에 다시 찾아볼 수 있습니다.
별도 소품이 필요 없습니다. 텍스트를 쓸 수 있는 공간이면 끝입니다.

어색함이 적기 때문에, 특히 난이도 높은 문제나 시간이 오래 걸리는 버그일수록 이 방식을 실제로 사용할 확률이 높아집니다.

습관으로 만들기 (그리고 속도 향상 효과 누리기)

디버깅 펜팔의 진짜 힘은, 아주 막다른 골목에 몰렸을 때만 쓰는 비장의 카드가 아니라 평소에 자주 사용하는 습관이 됐을 때 드러납니다.

실천 팁 몇 가지를 정리해 보면:

전용 공간을 만들어 두기.
"debugging-pen-pal" 같은 이름의 문서나 폴더를 하나 만들어, 이런 글들을 모아 두세요. 시간이 지나면 나만의 ‘과거 문제/해결’ 지식 베이스가 됩니다.
프롬프트(템플릿)를 활용하기.
처음엔 뭘 써야 할지 막막할 수 있으니, 간단한 틀을 만들어 두면 좋습니다.
- 내가 하려는 것…
- 실제로 벌어지는 일…
- 내가 생각하는 원인…
- 지금까지 시도해 본 것…
- 도움을 받고 싶은 부분은…
시간 제한 두고 써 보기.
‘막혔다’는 느낌이 들면, 코드만 붙잡고 있기보다 10~15분 정도만 펜팔에게 편지를 쓴다는 마음으로 정리해 보세요. 그 짧은 쉬는 시간이 문제를 풀어 주는 경우가 정말 많습니다.
필요할 때 실제로 공유하기.
상상의 펜팔에게 쓴 글이지만, 때로는 진짜 팀원에게 그대로 보여줄 수 있습니다. 글이 충분히 정리돼 있다면, 그대로 팀 채팅방이나 티켓에 붙여넣어도 됩니다. 이미 설명의 ‘어려운 부분’을 끝낸 상태니까요.

이런 습관을 들인 개발자들은 대체로:

막연한 혼란 상태로 보내는 시간이 줄어들고,
실제로 도움을 구할 때 질문의 질이 좋아지며,
무작정 찍어 보는 실험을 줄이고, 더 빠르고 체계적으로 문제를 해결하게 됩니다.

결론: 펜팔은 결국 ‘미래의 나’다

디버깅 펜팔은 상상의 존재일 수 있지만, 그로부터 얻는 효과는 매우 현실적입니다. 디버깅을 하나의 커뮤니케이션 연습으로 바꾸면, 다음과 같은 일이 벌어집니다.

생각을 명확하고 논리적인 구조로 재배열하게 됩니다.
숨어 있던 가정과 오해를 끄집어낼 수 있습니다.
복잡한 기술적인 내용을 단순한 언어로 설명하는 연습을 하게 됩니다.
어려운 문제에 막혀 있는 시간을 줄일 수 있습니다.

어떻게 보면, 이 펜팔은 결국 미래의 나 자신입니다. 문제를 명확하게 이해하고 있는 ‘미래의 나’에게 지금의 내가 다가가는 과정이 곧 글쓰기인 셈입니다.

다음에 문제가 막힌다고 느껴지면, 새 문서를 열고 이렇게 시작해 보세요.

“지금 이 기능을 작업 중인데, 상황이 이렇습니다…”

어쩌면, 상상의 팀원이 진짜 버그를 찾아 주는 데 생각보다 훨씬 빨리 도움을 줄지도 모릅니다.