디버깅 지원 기능

코드는 언젠가 깨집니다. 이 글은 오류가 났을 때 Claude Code에게 무엇을 어떻게 넘겨야 원인까지 찾아 주는지를 다룹니다. 앞 글의 황금 문장이 여기서도 핵심이고, 교재 3주차의 "시스템 4구간"이 지시를 정확하게 만드는 도구가 됩니다. 다음 글은 「Git 조작 자동화」입니다.

핵심 요약

• 오류 메시지와 재현 명령을 그대로 넘기는 것이 출발점입니다.
• "고쳐 줘" 대신 원인 분석, 최소 수정, 변경 정리를 순서대로 시킵니다.
• 재현이 안 되면 어느 구간(화면, 서버, 프로그램, 데이터)인지부터 좁힙니다.
• 수정 뒤에는 반드시 재현 명령을 다시 돌려 통과 증거를 남깁니다.

기본 흐름

공식 문서의 버그 수정 레시피는 오류 공유, 수정 방안, 적용의 세 단계이고, 팁으로 "재현 명령과 스택 추적을 알려 주고 간헐적인지 일관적인지 말하라"고 덧붙입니다. 우리 식 지시문은 이렇습니다.

python make_report.py 를 실행하면 아래 오류가 나. 매번 재현돼.
(오류 메시지 전체 붙여넣기)
원인을 먼저 설명하고, 기존 기능은 그대로 두고 최소 수정으로 고친 뒤
같은 명령을 다시 실행해서 통과하는지 보여 줘.

오류 메시지는 요약하지 말고 통째로 붙여넣습니다. 입력창에 ! python make_report.py처럼 !를 붙여 실행하면 출력이 대화에 들어가고 Claude가 바로 반응합니다.

"고쳐줘"보다 강력한 지시

"안 되는데 고쳐 줘"는 교재 5주차가 꼽는 나쁜 요청입니다. 원인을 모른 채 증상만 덮거나 멀쩡한 부분을 갈아엎습니다. 공식 모범 사례도 "근본 원인을 해결하고 오류를 억제하지 말라"를 지시에 넣으라고 권합니다. 강력한 지시는 순서를 정해 줍니다.

1. 원인 분석: "왜 이 오류가 나는지 코드와 데이터 흐름을 따라가며 설명해 줘."
2. 영향 범위: "고치면 어떤 파일과 기능이 영향을 받는지 먼저 알려 줘."
3. 최소 수정: "그 범위 안에서만 고쳐 줘."
4. 변경 정리: "바꾼 파일, 이유, 다시 확인하는 방법을 정리해 줘."

plan 모드로 1번과 2번만 먼저 받으면 편집 없이 진단만 받을 수 있습니다.

재현되지 않는 버그

"어제는 됐는데 오늘은 안 돼요"가 여기 해당합니다. 이때는 코드보다 구간부터 좁힙니다. 교재 3주차의 4구간 점검을 그대로 지시합니다.

지금 이 문제가 화면/서버/프로그램/데이터 중 어느 구간 문제인지 먼저 알려 주고,
구간별로 하나씩 점검해 줘.

교재의 기준은 이렇습니다. 다른 프로그램도 안 되면 내 컴퓨터 문제, 서버 주소로 접속되면 서버는 정상, 프로그램은 재기동으로 복구가 먼저, 데이터베이스는 손실이 되돌릴 수 없으니 함부로 만지지 않기. "특정 시간이나 특정 파일에서만 나는지"도 함께 적습니다.

로그를 활용하기

로그는 사람이 읽기보다 넘기는 편이 빠릅니다.

tail -200 app.log | claude -p "이 로그에서 오류의 첫 발생 지점과 직전 정상 동작을 찾아 줘"

세션 안에서는 @logs/app.log로 지목합니다. 로그가 없다면 로그를 넣게 하는 것이 첫 수정입니다. "각 단계 시작과 끝에 시각과 함께 로그를 남겨 줘." 원구연 강사가 24시간 무인 서버를 운영하며 배운 원칙도 같습니다. 장애는 stderr를 정독하는 데서 풀립니다.

이분 탐색

원인을 전혀 모를 때 절반씩 잘라 확인하는 방법입니다. 데이터라면 앞 절반과 뒤 절반을 따로 돌려 보고, 시간이라면 "어느 커밋부터 깨졌는지"를 찾습니다.

최근 10개 커밋 중 어디서부터 이 오류가 나기 시작했는지 이분 탐색으로 찾아 줘.
찾으면 그 커밋에서 바뀐 내용을 설명해 줘.

커밋을 잘게 남겨 두었을수록 이 탐색이 빨라집니다.

수정 후 반드시 할 것

1. 재현 명령을 다시 실행해 통과 출력을 받습니다. "됐습니다"라는 말은 증거가 아닙니다.
2. 교재 5주차의 QA 관점으로 확인합니다. 기존 기능이 덮어써지지 않았나, 콘솔 에러가 없나, 민감정보가 노출되지 않았나.
3. /diff로 변경 범위를 봅니다. 시키지 않은 파일이 바뀌었으면 되돌립니다.
4. 커밋합니다. "오류 원인과 수정 내용을 담아 커밋해 줘."

흔한 함정

• 오류 메시지를 요약해서 넘기기. 원문의 파일명과 줄 번호가 사라집니다.
• 원인을 듣지 않고 수정부터 승인하기. 증상만 덮여 다시 터집니다.
• 같은 문제를 세 번째 고치게 하기. 두 번 실패했으면 /clear 후 배운 내용을 담아 새로 시작합니다.
• 데이터베이스를 고치라고 하기. "지금 하려는 작업이 DB를 바꾸는 일이야? 바꾸기 전에 백업부터 하고 뭘 바꾸는지 표로 보여 줘"를 먼저 시킵니다.

연습 문제

1. 일부러 파일명을 틀리게 바꿔 오류를 낸 뒤, 오류 전문과 재현 명령을 넘겨 원인 설명을 받아 보세요.
2. 4구간 점검 지시를 그대로 보내고, Claude Code가 어느 구간으로 판단하는지 확인하세요.
3. 수정 후 재현 명령을 다시 돌린 출력을 캡처해 커밋 메시지에 요약을 넣어 보세요.

코스 완료

읽기와 쓰기, 지시문, 디버깅까지 입문 코스의 핵심 조작을 마쳤습니다. 다음 글 「Git 조작 자동화」에서 작업을 안전하게 보관하는 7단계로 마무리합니다.

정리

• 오류 원문과 재현 명령, 발생 빈도를 함께 넘깁니다.
• 원인 분석, 영향 범위, 최소 수정, 변경 정리 순서로 시킵니다.
• 재현이 안 되면 4구간부터, 원인을 모르면 이분 탐색으로 좁힙니다.
• 수정 뒤 재현 명령 재실행과 커밋까지가 한 세트입니다.

자주 묻는 질문