클로드코드 /debug — 원인 모를 오류를 로그로 추적하는 법

클로드코드를 쓰다 보면 "왜 자꾸 멈추지?", "방금 뭐가 잘못된 거지?" 하는 순간이 옵니다. 화면에는 별 말이 없어서 답답하죠. 이럴 때 쓰는 게 /debug입니다. 평소엔 숨어 있던 속사정(로그)을 화면에 꺼내 보여줘서, 무엇이 어떻게 동작하고 있는지 들여다볼 수 있게 해줍니다.

정의 (뭐냐면)

/debug는 디버그 로그(debug log, 프로그램이 내부에서 무슨 일을 하는지 적어두는 기록)를 켜고 문제를 분석하는 명령어입니다.

평소 클로드코드는 결과만 깔끔하게 보여주고, 내부 동작은 감춰둡니다. /debug를 켜면 그 감춰진 동작이 화면이나 로그 파일에 자세히 남습니다. 어디서 멈췄는지, 어떤 도구를 호출하다 막혔는지 같은 단서를 얻을 수 있어요.

어떻게 쓰나 (난이도별)

기초 — 그냥 켜기

/debug

이렇게만 입력하면 로그 수집이 시작됩니다. 이후 작업을 하면 평소보다 훨씬 자세한 동작 기록이 쌓입니다.

응용 — 증상 함께 알려주기

/debug 자꾸 멈춰요

지금 겪고 있는 증상을 같이 적어주면, 그 증상에 초점을 맞춰 분석합니다. "어떤 점이 이상한지" 한 줄로 적어주는 것만으로도 추적 방향이 훨씬 또렷해집니다.

흔한 함정 (해당될 때만)

• 디버그 로그에는 작업 경로, 명령 내용 등 꽤 자세한 정보가 담깁니다. 로그를 그대로 다른 사람에게 공유할 때는 민감한 정보(API 키, 비밀번호 등)가 섞여 있지 않은지 한 번 훑어보세요.
• /debug는 "고쳐주는" 명령이 아니라 "원인을 보여주는" 명령입니다. 로그를 켠 뒤 문제 상황을 다시 한 번 재현해야 단서가 잡힙니다.

실전 사례

이상 동작이 가끔씩만 나타날 때가 가장 골치 아픕니다. 이럴 땐 먼저 /debug로 로그를 켜두고, 문제가 났던 작업을 다시 시도해 보세요. 그 순간 쌓인 로그를 보면 "여기서 멈췄구나" 하는 지점을 찾을 수 있습니다.

이렇게 더 씁니다

로그로 원인을 직접 들여다볼 수 있으니, 막연히 "안 돼요"라고 하기보다 "어디서 막혔다"까지 짚을 수 있게 됩니다. 혼자 해결이 안 되면, /debug로 모은 단서를 /feedback(버그 제보) 명령에 함께 담아 보내면 개선에도 도움이 됩니다.

정리

/debug는 클로드코드의 숨은 동작을 화면에 꺼내 보여주는 명령입니다. 원인 모를 멈춤이나 이상 동작을 만났을 때 켜두고 문제를 재현하면, 추적의 단서를 얻을 수 있습니다.

기준: Claude Code v2.1.154 (2026.05)