디버깅·트러블슈팅 프롬프트 — 에러 메시지를 해결책으로 바꾸는 법

디버깅 — 개발 시간의 50%를 차지하는 작업

여러 조사에 따르면 개발자는 전체 업무 시간의 약 50%를 디버깅에 소비합니다. 새로운 기능을 만드는 시간보다 기존 코드의 문제를 찾고 고치는 시간이 더 많다는 뜻입니다.

AI는 디버깅 프로세스를 근본적으로 변화시킬 수 있습니다. 에러 메시지를 복사해서 붙여넣기만 해도 원인 분석과 해결 방안을 제시받을 수 있습니다. 하지만 "에러 메시지만 던지는 것"과 "체계적인 디버깅 프롬프트를 사용하는 것" 사이에는 큰 품질 차이가 있습니다.

이 챕터에서는 디버깅의 각 단계(에러 분석 → 원인 추론 → 해결 방안 → 재발 방지)에 최적화된 프롬프트 패턴을 다룹니다. 단순히 "이 에러 고쳐줘"가 아니라, AI를 디버깅 파트너로 활용하는 체계적인 방법론을 제시합니다.

에러 메시지 분석 프롬프트

에러 메시지를 AI에게 전달할 때, 메시지만 보내면 일반적인 답변을 받게 됩니다. 맥락 정보를 함께 제공하면 정확도가 비약적으로 높아집니다.

에러 메시지 분석 기본 프롬프트

다음 에러가 발생했습니다. 원인과 해결 방법을 알려주세요:

[에러 메시지]:

[에러 메시지 전체 복사]

[컨텍스트]:

• 언어/프레임워크: [예: Node.js + Express]
• 실행 환경: [예: 로컬 개발 / Docker / AWS Lambda]
• 최근 변경 사항: [예: 새 미들웨어 추가, 패키지 업데이트]
• 재현 빈도: [항상 / 간헐적 / 특정 조건에서만]

[관련 코드]:

[에러가 발생한 파일의 관련 부분]

다음을 포함하여 답변해주세요:

1. 에러의 근본 원인 (root cause)
2. 즉시 해결 방법 (quick fix)
3. 올바른 해결 방법 (proper fix)
4. 이 에러가 재발하지 않도록 하는 예방 조치

알 수 없는 에러 분석 프롬프트

에러 메시지가 불명확하거나 없는 상황에서 문제를 분석해주세요:

[증상]:

• 기대 동작: [어떻게 동작해야 하는지]
• 실제 동작: [실제로 어떻게 동작하는지]
• 에러 메시지: [있으면 기재, 없으면 "에러 메시지 없음 — 잘못된 결과만 반환"]

[재현 조건]:

• 입력 데이터: [문제를 일으키는 입력]
• 실행 순서: [어떤 순서로 작업하면 발생하는지]
• 환경 조건: [특정 브라우저, OS, 네트워크 상태]

[이미 시도한 것]:

1. [시도한 방법 + 결과]
2. [시도한 방법 + 결과]

가능한 원인을 가능성 높은 순서로 나열하고, 각 원인을 검증할 수 있는 디버깅 방법을 제시해주세요.

에러 유형별 분석 프레임워크

에러는 크게 4가지 유형으로 분류할 수 있으며, 유형에 따라 AI에게 제공해야 할 정보가 다릅니다.

컴파일/빌드 에러: 타입 불일치, 임포트 오류, 문법 오류

• 필요 정보: 소스 코드, tsconfig/eslint 설정, 패키지 버전

런타임 에러: NullPointer, TypeError, 범위 초과

• 필요 정보: 스택트레이스, 입력 데이터, 실행 경로

로직 에러: 잘못된 계산, 누락된 조건, 순서 오류

• 필요 정보: 기대 출력 vs 실제 출력, 테스트 케이스

환경 에러: 포트 충돌, 권한 부족, 메모리 부족

• 필요 정보: 실행 환경, 시스템 리소스, 설정 파일

컴파일/빌드 에러 전용 프롬프트

TypeScript/빌드 에러가 발생했습니다:

[에러 메시지]:

[tsc/빌드 도구 에러 출력]

[관련 설정 파일]:

[tsconfig.json / webpack.config.js / vite.config.ts 등]

[관련 소스 코드]:

[에러가 발생한 파일]

[의존성]:

[package.json의 dependencies + devDependencies]

다음을 분석해주세요:

1. 에러 원인 (타입 불일치? 버전 충돌? 설정 오류?)
2. 수정 코드
3. 같은 유형의 에러를 린트 규칙으로 미리 잡을 수 있는지

스택트레이스 해석 프롬프트

스택트레이스는 에러의 여정을 보여주는 지도입니다. 하지만 프레임워크 내부 코드와 실제 문제 코드가 섞여 있어 해석이 어렵습니다. AI에게 스택트레이스의 핵심을 추출하도록 요청할 수 있습니다.

스택트레이스 해석 프롬프트

다음 스택트레이스를 분석해주세요:

[전체 스택트레이스 붙여넣기]

분석 요청:

1. 핵심 프레임 식별: 프레임워크/라이브러리 내부 코드를 제외하고, 내 코드에서 문제가 시작된 정확한 위치를 찾아주세요.

2. 호출 경로 요약: 에러에 도달하기까지의 호출 경로를 내 코드 기준으로 간결하게 요약해주세요. 예: "UserController.create → UserService.save → DB.insert"

3. 원인 추론: 스택트레이스에서 추론할 수 있는 에러 원인

4. 추가 정보 요청: 정확한 진단을 위해 내가 추가로 확인해야 할 것

[프레임워크]: [예: Spring Boot / Express / Django] [내 코드 경로 패턴]: [예: src/main/java/com/myapp/ 또는 src/]

비동기 스택트레이스 분석 프롬프트

비동기 코드에서 발생한 에러의 스택트레이스입니다. 일반 스택트레이스와 달리 비동기 경계에서 컨텍스트가 끊어져 있습니다:

[비동기 스택트레이스]

[관련 비동기 코드]:

[async/await 또는 Promise 체인 코드]

분석 요청:

1. 비동기 경계를 표시하고, 각 단계에서 무슨 일이 일어나는지 설명
2. 에러가 어느 비동기 단계에서 발생했는지 특정
3. unhandled rejection 가능성 검토
4. 에러 전파 경로와 누락된 catch 블록 식별
5. 개선된 에러 처리 코드 제시 (원본 스택트레이스 보존 포함)

성능 병목 진단

코드는 정상적으로 동작하지만 느린 경우, 병목 지점을 찾는 것이 핵심입니다. AI에게 성능 프로파일 결과나 응답 시간 데이터를 제공하면 체계적인 진단을 받을 수 있습니다.

API 응답 시간 진단 프롬프트

API 응답이 느립니다. 병목 지점을 찾아주세요:

[API 엔드포인트]: [예: GET /api/users/dashboard] [현재 응답 시간]: [예: 평균 3.2초, p99 8초] [목표 응답 시간]: [예: 200ms 이내]

[API 핸들러 코드]:

[코드 붙여넣기]

[데이터베이스 쿼리] (실행되는 쿼리 목록):

[쿼리 1 — 실행 시간: Xms]
[쿼리 2 — 실행 시간: Xms]

[인프라 정보]:

• DB: [예: PostgreSQL, 레코드 수 500만]
• 캐시: [예: Redis 사용 여부]
• 서버: [예: 2 vCPU, 4GB RAM]

분석 요청:

1. 응답 시간의 분해 (DB 쿼리, 비즈니스 로직, 네트워크, 직렬화 각각)
2. 가장 큰 병목 지점 식별
3. 각 병목에 대한 최적화 방법 (코드 변경 + 인프라 변경)
4. 최적화 후 예상 응답 시간

데이터베이스 쿼리 최적화 프롬프트

다음 쿼리가 느립니다. 최적화해주세요:

[느린 쿼리]:

[쿼리]

[실행 계획 (EXPLAIN ANALYZE)]:

[EXPLAIN ANALYZE 결과]

[테이블 정보]:

• 테이블명: [이름]
• 레코드 수: [약 N건]
• 현재 인덱스: [인덱스 목록]
• 주요 쿼리 패턴: [이 테이블에 자주 실행되는 쿼리 유형]

최적화 요청:

1. 실행 계획에서 문제점 식별 (Full Table Scan, Nested Loop 등)
2. 필요한 인덱스 추천 (생성 SQL 포함)
3. 쿼리 재작성 (더 효율적인 방법이 있다면)
4. 인덱스 추가 시 쓰기 성능 영향 분석
5. 파티셔닝/샤딩이 필요한 수준인지 판단

프론트엔드 렌더링 성능 진단 프롬프트

웹 페이지 렌더링이 느립니다:

[증상]:

• First Contentful Paint: [예: 4.2초]
• Largest Contentful Paint: [예: 6.8초]
• Total Blocking Time: [예: 800ms]
• Cumulative Layout Shift: [예: 0.35]

[페이지 컴포넌트 구조]:

[컴포넌트 트리 또는 주요 컴포넌트 코드]

[데이터 페칭 방식]:

• [예: useEffect에서 3개 API 순차 호출]
• [예: 이미지 20개 동시 로드]

Core Web Vitals 각 지표를 개선하는 구체적인 방법을 제시해주세요:

1. 코드 레벨 최적화 (React.memo, useMemo, lazy loading 등)
2. 데이터 페칭 최적화 (병렬화, 캐싱, SSR/SSG)
3. 번들 최적화 (코드 스플릿, 트리 쉐이킹)
4. 이미지 최적화 (포맷, 사이즈, lazy loading)
5. 각 최적화의 예상 개선 효과

메모리 누수 탐지

메모리 누수는 발견하기 가장 어려운 버그 중 하나입니다. 점진적으로 메모리가 증가하여 결국 OOM(Out of Memory)으로 서비스가 죽는 경우가 많습니다.

메모리 누수 진단 프롬프트

서비스의 메모리 사용량이 시간이 지남에 따라 증가합니다:

[증상]:

• 시작 시 메모리: [예: 150MB]
• 1시간 후: [예: 350MB]
• 4시간 후: [예: 800MB]
• OOM 발생 시점: [예: 약 6시간 후]

[의심 코드]:

[메모리 누수가 의심되는 코드 영역]

[서비스 특성]:

• 언어/런타임: [예: Node.js]
• 주요 작업: [예: WebSocket 연결 관리, 이미지 처리]
• 사용 중인 캐시: [예: 인메모리 Map, LRU 캐시]
• 이벤트 리스너: [예: EventEmitter, DOM 이벤트]

분석 요청:

1. 일반적인 메모리 누수 패턴 중 이 코드에 해당하는 것
2. 구체적인 누수 지점 식별
3. 수정 코드
4. 메모리 모니터링을 위한 코드/도구 추천
5. CI/CD에서 메모리 누수를 감지하는 방법

이벤트 리스너/구독 누수 탐지 프롬프트

다음 코드에서 이벤트 리스너 또는 구독 해제 누락을 찾아주세요:

[코드 붙여넣기]

검사 항목:

1. addEventListener 에 대응하는 removeEventListener 존재 여부
2. subscribe에 대응하는 unsubscribe/dispose 존재 여부
3. setInterval/setTimeout에 대응하는 clearInterval/clearTimeout 존재 여부
4. WebSocket/SSE 연결의 정리 로직 존재 여부
5. React useEffect의 cleanup 함수 반환 여부

누락된 정리 로직을 모두 추가한 수정 코드를 제공해주세요.

클로저 기반 메모리 누수 분석 프롬프트

다음 코드에서 클로저로 인한 메모리 누수 가능성을 분석해주세요:

[클로저를 사용하는 코드]

분석 기준:

1. 클로저가 외부 스코프의 큰 객체를 캡처하고 있는지
2. 캡처된 변수가 더 이상 필요 없는데도 참조가 유지되는지
3. 클로저의 생명주기가 캡처된 객체보다 긴지
4. WeakRef/WeakMap으로 대체 가능한 참조가 있는지

메모리 누수가 확인되면:

• 문제의 정확한 메커니즘 설명
• 수정된 코드
• 테스트 방법 (힙 스냅샷 비교)

로그 분석

프로덕션 환경에서는 디버거를 붙일 수 없는 경우가 대부분입니다. 로그가 유일한 디버깅 수단인 상황에서 AI를 활용하면 방대한 로그 속에서 패턴을 빠르게 발견할 수 있습니다.

로그 패턴 분석 프롬프트

다음 로그에서 문제의 원인을 분석해주세요:

[로그]:

[관련 로그 라인들 붙여넣기 — 시간순]

[문제 상황]: [예: 특정 시간대에 간헐적으로 500 에러 발생]

분석 요청:

1. 패턴 식별: 에러 발생 전후의 패턴 (특정 요청, 시간대, 순서)
2. 상관관계: 에러와 상관있는 다른 로그 이벤트
3. 시간순 재구성: 문제가 발생하기까지의 이벤트 타임라인
4. 원인 후보: 가능성 높은 순서로 나열
5. 추가 로그 요청: 진단에 필요한데 현재 부족한 로그 정보

로그 레벨 및 구조 개선 프롬프트

다음 코드의 로깅을 개선해주세요:

[코드 붙여넣기]

현재 로깅 문제:

• [예: console.log만 사용, 구조화되지 않은 메시지]

개선 요구사항:

1. 구조화된 로깅 (JSON 형식, 추적 가능한 필드)
2. 적절한 로그 레벨 (ERROR, WARN, INFO, DEBUG)
3. 요청 추적 ID (request ID / correlation ID)
4. 성능에 영향을 주지 않는 로깅 (lazy evaluation)
5. 민감 정보 마스킹 (비밀번호, 토큰, 개인정보)

로깅 라이브러리: [예: Winston / Pino / Python logging] 모니터링 도구: [예: Datadog / ELK Stack]

각 로그 포인트에 왜 그 레벨을 선택했는지 설명해주세요.

분산 시스템 로그 추적 프롬프트

마이크로서비스 환경에서 요청이 여러 서비스를 거치며 실패했습니다:

[서비스 A 로그]:

[로그]

[서비스 B 로그]:

[로그]

[서비스 C 로그]:

[로그]

[서비스 간 통신]: [예: HTTP / gRPC / 메시지 큐] [추적 ID]: [있으면 기재]

분석 요청:

1. 요청의 전체 흐름 재구성 (서비스 A → B → C)
2. 어느 서비스에서 문제가 시작되었는지
3. 서비스 간 통신에서 발생한 타이밍 이슈
4. 타임아웃/재시도 설정의 적절성
5. 개선된 에러 전파 및 폴백 전략

디버깅 체계화 — 가설 기반 접근법

경험 많은 개발자의 디버깅 방식은 "이것저것 바꿔보기"가 아니라 "가설 수립 → 검증 → 반복"입니다. AI를 이 프레임워크에 통합하면 디버깅 효율이 극대화됩니다.

가설 기반 디버깅 프롬프트

다음 버그에 대한 디버깅 계획을 세워주세요:

[버그 설명]: [증상, 재현 조건, 영향 범위]

[이미 알고 있는 사실]:

1. [사실 1: 예) 로컬에서는 발생하지 않고 프로덕션에서만 발생]
2. [사실 2: 예) 특정 사용자에게만 발생]
3. [사실 3: 예) 2일 전부터 시작됨]

다음 형식으로 디버깅 계획을 제시해주세요:

[가설 1]: [예: 환경 변수 차이로 인한 동작 차이]

• 검증 방법: [구체적인 확인 단계]
• 예상 결과: [가설이 맞다면 볼 수 있는 증거]
• 소요 시간: [예: 10분]

[가설 2]: [예: 최근 배포에서 도입된 리그레션]

• 검증 방법: [구체적인 확인 단계]
• 예상 결과: [가설이 맞다면 볼 수 있는 증거]
• 소요 시간: [예: 15분]

가설을 가능성 높은 순서로 정렬하고, 가장 적은 시간으로 가장 많은 가설을 배제할 수 있는 순서를 추천해주세요.

이분법(Binary Search) 디버깅 프롬프트

다음 버그가 언제 도입되었는지 모릅니다. 이분법으로 문제가 시작된 커밋을 찾으려고 합니다:

[정상 작동 확인된 버전]: [예: 커밋 abc123 / v2.1.0] [버그 발생 확인된 버전]: [예: 현재 HEAD / v2.3.0] [두 버전 사이 커밋 수]: [예: 약 150개]

다음을 도와주세요:

1. git bisect 명령어 가이드
2. 버그 존재 여부를 빠르게 확인하는 테스트 스크립트 작성
3. 자동화된 bisect 실행 방법 (git bisect run)
4. bisect 결과 해석 방법

환경별 디버깅 전략

Docker/컨테이너 환경

Docker 환경 디버깅 프롬프트

Docker 컨테이너에서 다음 문제가 발생합니다:

[문제]: [예: 컨테이너가 시작 후 30초 만에 OOM으로 종료]

[Dockerfile]:

[Dockerfile 내용]

[docker-compose.yml] (있는 경우):

[docker-compose 내용]

[컨테이너 로그]:

[docker logs 출력]

[호스트 환경]: [OS, Docker 버전, 리소스 할당]

분석 및 해결 요청:

1. 로컬 직접 실행과 Docker 실행의 차이점 분석
2. 리소스 제한 설정 확인 (메모리, CPU)
3. 네트워크 설정 문제 가능성
4. 볼륨 마운트 권한 문제
5. 멀티스테이지 빌드 최적화

CI/CD 파이프라인

CI/CD 실패 디버깅 프롬프트

CI/CD 파이프라인이 실패합니다. 로컬에서는 정상 동작합니다:

[CI 도구]: [예: GitHub Actions / GitLab CI]

[파이프라인 설정]:

[워크플로우 파일 내용]

[실패 로그]:

[CI 실행 로그]

[로컬 vs CI 차이점]:

• OS: [로컬 OS] vs [CI runner OS]
• Node/Python 버전: [로컬] vs [CI]
• 환경 변수: [로컬에만 있는 변수가 있는지]

분석 요청:

1. 로컬과 CI 환경의 핵심 차이점 식별
2. 환경별 의존성 차이 (OS 패키지, 네이티브 모듈)
3. 타이밍/네트워크 관련 불안정 테스트(flaky test) 여부
4. 캐싱 관련 문제 (node_modules, pip cache)
5. 수정된 파이프라인 설정 제시

재발 방지 프롬프트

버그를 고치는 것도 중요하지만, 같은 유형의 버그가 다시 발생하지 않도록 방지하는 것이 더 중요합니다.

재발 방지 대책 수립 프롬프트

다음 버그를 수정했습니다. 같은 유형의 버그가 재발하지 않도록 방지 대책을 세워주세요:

[버그 설명]: [무엇이 잘못되었는지] [근본 원인]: [왜 발생했는지] [수정 내용]: [어떻게 고쳤는지]

방지 대책 요청:

1. 코드 레벨: 타입 강화, 검증 추가, 방어적 프로그래밍
2. 테스트 레벨: 추가해야 할 테스트 케이스 (이 버그를 잡을 수 있었던)
3. 린트/정적 분석: ESLint/SonarQube 규칙으로 자동 감지
4. 프로세스 레벨: 코드 리뷰 체크리스트에 추가할 항목
5. 모니터링 레벨: 이 유형의 문제를 조기에 감지하는 알림 설정

각 대책의 구현 코드/설정을 포함해주세요.

회귀 테스트(Regression Test) 생성 프롬프트

다음 버그 수정에 대한 회귀 테스트를 작성해주세요:

[수정된 코드]:

[수정된 코드]

회귀 테스트 요구사항:

1. 이 정확한 버그를 재현하는 테스트 (수정 전에는 실패, 수정 후에는 통과)
2. 같은 유형의 유사한 버그를 잡는 일반화된 테스트
3. 엣지 케이스 커버리지 확대
4. 테스트 이름에 버그 트래커 ID 포함 (추적 가능하도록)

테스트 프레임워크: [예: Jest / pytest / JUnit]

디버깅 도구와 AI 활용 통합

효과적인 디버깅을 위해서는 AI 프롬프트와 함께 적절한 도구를 활용하는 것이 중요합니다. Datadog 같은 모니터링 도구에서 수집한 메트릭과 트레이스를 AI에게 전달하면, 단순 로그 분석보다 훨씬 정확한 진단을 받을 수 있습니다.

추천 워크플로우:

1. 모니터링 도구(Datadog 등)에서 이상 징후 감지
2. 관련 로그, 트레이스, 메트릭을 수집
3. AI에게 수집된 데이터와 함께 분석 요청
4. AI의 가설을 바탕으로 코드 레벨에서 검증
5. 수정 후 모니터링 도구로 개선 확인

Snyk와 같은 보안 도구의 취약점 리포트를 AI에게 전달하면, 취약점의 실제 영향도 분석과 수정 코드를 빠르게 얻을 수 있습니다. 이 내용은 7챕터(보안 코드 검증)에서 더 자세히 다룹니다.

핵심 요약

디버깅 영역	핵심 전략	AI에게 제공할 정보
에러 메시지 분석	맥락 정보 함께 제공	에러 + 코드 + 환경 + 최근 변경
스택트레이스 해석	내 코드 프레임 식별 요청	전체 트레이스 + 프레임워크 정보
성능 병목 진단	데이터 규모/빈도 명시	코드 + 쿼리 + 실행계획 + 인프라
메모리 누수 탐지	시간별 메모리 추이 제공	코드 + 메모리 수치 + 서비스 특성
로그 분석	시간순 정렬된 관련 로그	로그 + 문제 상황 + 서비스 구조
재발 방지	5개 레벨 방지 대책	버그 설명 + 원인 + 수정 내용

디버깅에서 AI를 가장 효과적으로 활용하는 비결은 "충분한 맥락 정보 제공" 입니다. 에러 메시지만 던지면 일반적인 답변을, 코드 + 환경 + 재현 조건 + 이미 시도한 것까지 함께 제공하면 정확한 진단을 받을 수 있습니다. 다음 챕터에서는 버그를 사전에 방지하는 가장 효과적인 방법인 테스트 자동화 프롬프트를 다룹니다.

---

다음 챕터 미리보기: 테스트 자동화 프롬프트 — 단위·통합·E2E 테스트 생성