디버그 모드의 실제 정체

2025년 12월, Cursor는 “디버그 모드(Debug Mode)“라는 새로운 에이전트 모드를 발표했습니다. 일반 에이전트 모드가 코드를 읽고 곧바로 수정안을 제시하는 반면, 디버그 모드는 탐정처럼 먼저 런타임 정보를 수집한 뒤 원인을 정확히 찾아내는 방식을 취합니다.

Debug Mode

구체적인 작동 방식은 다음과 같습니다.

  1. 버그 설명: 증상과 재현 단계를 가능한 한 구체적으로 알려줍니다.
  2. 가설 수립: 에이전트가 코드베이스를 읽고 원인에 대한 여러 가지 가설을 세웁니다.
  3. 로그 인스트루멘테이션 추가: 각 가설을 검증하기 위해 의심되는 위치에 로깅 코드를 일시적으로 삽입합니다.
  4. 버그 재현: 실제로 앱을 사용하여 버그를 유발하고, 에이전트가 런타임 로그를 수집합니다.
  5. 원인 특정 및 수정: 수집된 정보(변수 상태, 실행 경로, 타이밍 등)를 바탕으로 정확한 수정안을 제안합니다.
  6. 수정 검증: 버그를 한 번 더 재현합니다. 버그가 사라졌다면 에이전트가 추가했던 모든 로그 인스트루멘테이션을 자동으로 제거하고, 사라지지 않았다면 로그를 더 추가하여 범위를 계속 좁혀나갑니다.

이러한 “가설 설정 → 인스트루멘테이션 → 재현 → 검증” 루프 덕분에, 수백 줄의 코드를 맹목적으로 다시 작성하는 대신 대개 2~3줄 내외의 정밀한 수정안을 얻을 수 있다고 합니다.

활성화 방법

Shift + Tab를 눌러 모드를 순환하며 “Debug”를 선택하세요. 혹은 모드 버튼을 직접 클릭해서 전환할 수도 있습니다.

어떤 상황에 적합한가?

공식 문서에 따르면 디버그 모드는 다음과 같은 상황에 가장 잘 어울립니다.

  • 재현할 수는 있지만 원인을 파악하기 힘든 버그
  • 성능 문제 및 메모리 누수
  • 코드만 읽어서는 원인이 드러나지 않는 문제

반대로, 명확한 스택 추적(stack trace)이 있는 단순한 에러는 일반 에이전트 모드로 해결하는 편이 보통 더 빠릅니다. 현실적인 요령이라면, 평소 하던 방식대로 먼저 수정을 시도해 보고 효과가 없을 때 디버그 모드로 전환하는 것입니다.

실제로 얼마나 유용한가?

디버그 모드를 정기적으로 사용하는 개발자들은 다음과 같은 장점들을 꼽습니다.

  • 특정 IDE 기능(LSP 등)에 의존하는 대신 HTTP 기반 텍스트 로그를 활용하므로, 로컬 환경은 물론 Remote SSH 환경 등 거의 모든 프로그래밍 언어와 런타임에서 작동합니다.
  • 프론트엔드와 백엔드를 동시에 계측(instrumentation)하여 양쪽에 걸쳐 있는 버그를 추적할 수 있습니다.
  • Datadog이나 Sentry 같은 외부 관측 가능성(observability) 도구를 MCP를 통해 연동하면 결과가 더욱 정교해진다는 개발자들의견해도 있습니다.

한 개발자는 외부 API 연동의 페이지네이션이 조건에 상관없이 무조건 첫 페이지만 반환하는 버그를 겪었습니다. 디버그 모드는 잘못된 JSON 필드명, 누락된 쿼리 파라미터, 제대로 전달되지 않는 토큰 등 세 가지 가설을 세우고 이를 테스트할 로그 인스트루멘테이션을 추가했습니다. 몇 차례의 재현과 로그 수집 과정을 거친 결과, 해당 API가 집계 엔드포인트와 일반 쿼리에서 서로 다른 페이지네이션 방식을 사용하고 있으며 집계 엔드포인트에는 토큰이 완전히 다른 방식으로 전달되어야 한다는 사실이 밝혀졌습니다. 코드만 읽어서는 놓치기 쉬운, 실제 데이터 기반의 이러한 숨겨진 스펙 불일치를 찾아내는 것이 바로 이 기능의 진가가 드러나는 부분입니다.

시나리오별 샘플 프롬프트

디버그 모드는 상황을 구체적으로 묘사할수록 더 정확해집니다. 공식 문서의 사용 패턴을 바탕으로, 시나리오별 프롬프트 예시를 몇 가지 소개합니다.

에러 메시지로부터 조사하기

plaintext
I'm getting "Cannot read property id of undefined" on line 45
of UserService.getProfile. Find the root cause and fix it.

스택 추적이 에러를 발생시키는 위치와 실제 원인이 있는 곳은 서로 다른 경우가 많습니다. 디버그 모드는 “그 코드를 호출한 주체”까지 역추적하여 진짜 원인을 찾아냅니다.

로그에서 원인 좁히기

plaintext
Processing for order ID 12345 is failing. The logs show:
inventory check passed → payment auth started → error here.
Find out exactly where after payment auth this is failing.

타임스탬프가 찍힌 로그를 건네주면, 디버그 모드가 조사를 진행하면서 이벤트의 발생 순서를 상호 참조합니다.

지원 티켓(Support Ticket)을 바탕으로 조사하기

plaintext
A customer reported that exporting their data produced an empty file.
Pro plan, account ID 12345. Check the export feature's code and
work out why the file might come out empty.

“빈 파일”이라는 말 하나에도 0건의 레코드, 타임아웃, 조용한 실패, 다운로드 손상 등 많은 의미가 포함될 수 있습니다. 디버그 모드는 이러한 가능성들을 나열하고 무엇을 먼저 확인해야 할지 파악하는 것을 도와줍니다.

간헐적으로 발생하는(Flaky) 테스트 조사하기

plaintext
This test is flaky — sometimes it passes, sometimes it fails.
Run it 20 times, collect the failures, and find the pattern.

수동으로 테스트를 계속 반복해서 실행하는 것은 지루한 일이지만, 바로 이러한 반복 업무에서 디버그 모드가 진가를 발휘합니다.

프론트엔드 이슈 조사하기

Cursor의 브라우저 도구와 결합하면 실제 렌더링된 화면, 콘솔 에러, 심지어 네트워크 요청까지 확인할 수 있습니다.

plaintext
The "Place order" button on the checkout page doesn't respond when clicked.
Take a screenshot, check the console errors, and find the cause.

동일한 문제의 재발을 막고 조직 지식을 축적하는 팁

비슷한 유형의 이슈를 반복해서 조사하는 일을 피하려면, .cursor/rules/ 경로에 디버깅 규칙 파일을 만들어 두는 것이 좋습니다. 흔한 버그 패턴, 조사 시 사용하는 내부 쿼리, 알려진 flaky 테스트 등을 적어두면 디버그 모드가 향후 조사 과정에서 이를 고려하게 됩니다.

수정이 완료된 후에는 Ask 모드에 버그가 애초에 발생한 이유와 동일한 패턴이 다른 곳에도 잠복해 있지 않은지 설명해 달라고 요청하는 것도 좋습니다. 그것이 바로 실제로 재발을 방지하는 방법입니다.

한 가지 더, 디버그 모드 전용 기능은 아니지만 Cursor가 버그를 잘 고치게 만드는 일반적인 팁이 있습니다. 많은 사람들이 첫 번째 프롬프트로 코드를 직접 작성하게 하는 대신, 접근 방식의 개요만 먼저 짜달라고 요청합니다. 이렇게 하면 코드가 작성되기 전에 에이전트의 오해를 미리 바로잡을 수 있어 재작업을 크게 줄일 수 있습니다.

알려진 제한 사항 및 주의할 점

장점 4

  • 맹목적인 추측으로 코드를 통째로 다시 작성하기보다는, 실제 데이터를 기반으로 작고 대상이 명확한 수정을 지향합니다.

  • 특정 IDE 기능에 묶여 있지 않아 다양한 언어와 환경(Remote SSH 포함)에서 작동합니다.

  • 수정이 확인되면 추가했던 로그 인스트루멘테이션이 자동으로 정리됩니다.

  • 프론트엔드와 백엔드를 아우르는 복잡한 버그에서도 잘 버텨냅니다.

단점 4

  • 프로젝트의 언어이나 라이브러리를 오판하여 잘못된 형식으로 로깅을 삽입하는 경우가 보고됩니다(예: C# 프로젝트에서 자바스크립트 스타일의 로깅을 사용하거나, 프로젝트가 커스텀 JSON 구현을 사용함에도 일반적인 라이브러리로 가정하는 경우 등).

  • 로그 인스트루멘테이션을 추가한 후, 심각한 IDE 수준의 에러를 항상 확인하는 것은 아닙니다.

  • Cursor CLI에서는 변경 승인 확인과 수정 완료 확인이 동시에 나타나 입력을 받지 못하는 현상이 발생할 수 있습니다(2026년 7월 기준으로 팀에서 파악하여 수정 중인 알려진 이슈입니다).

  • 버그를 직접 재현할 수 없거나 검증 단계에 적극적으로 참여할 수 없는 경우에는 효과가 떨어집니다.

.cursor/rules/*.mdc 아래에 규칙을 작성(“이 특정 라이브러리를 사용하세요” 또는 “변경 후 지정된 린트 명령어를 깨끗하게 실행하세요” 같은 내용)함으로써 이러한 제한 사항의 상당 부분을 적어도 부분적으로 우회할 수 있다는 보고가 있습니다. 입력이 멈추는 CLI 이슈의 경우, Esc를 누르면 대개 풀려나며, 허용 목록에 신뢰하는 명령어를 미리 승인하거나 자동 승인을 켜두면 아예 문제를 방지하기가 더 수월해집니다.

마치며

디버그 모드는 에이전트에 탄탄한 디버깅 규율을 심어줍니다. “코드를 읽고 추측하기”가 아니라 “실제로 프로그램을 실행해서 수집한 데이터로부터 원인 찾기”를 수행하는 것입니다. 미스터리하고 끈질긴 버그와 성능 문제에 매우 강하지만, 단순한 에러의 경우에는 일반 에이전트 모드가 때로는 더 빠르기 때문에 언제 어떤 모드를 써야 할지 아는 것이 중요합니다.

아직 사용해 보지 않았다면, 원인이 도무지 명확하지 않은 버그와 마주쳤을 때 Shift+Tab를 통해 디버그 모드를 한 번 시도해 보세요.