버그와 마주쳤을 때 — AI와 함께 원인을 찾는 법

서비스를 배포하고 나면 반드시 버그를 만납니다. 로컬에서는 잘 됐는데 배포 후에 안 된다거나, 사용자가 “이거 왜 안 되죠?”라고 문의를 보내오는 경우입니다. 바이브코딩으로 만든 서비스에서 버그를 마주했을 때 어떻게 접근하면 좋은지 알아봅니다.

프로덕션 버그를 마주하는 상황

버그는 크게 두 가지 경로로 발견됩니다.

직접 발견 서비스를 직접 사용하다가 특정 동작이 예상대로 안 되는 것을 발견합니다.

사용자 보고 서비스를 공개한 뒤 사용자가 버그를 알려줍니다.

두 경우 모두 버그를 파악하는 순서는 같습니다.

버그를 재현할 수 있는가 (어떤 상황에서 발생하는가)
어느 부분에서 발생하는가 (어떤 코드, 어떤 기능)
왜 발생하는가 (원인)
어떻게 고치는가 (해결)

바이브코딩에서 어려운 점은 3번입니다. 코드 전체를 직접 작성하지 않았기 때문에 어디서 문제가 생기는지 바로 알기 어렵습니다. 이때 AI를 활용합니다.

AI에게 디버깅 요청하는 방법

AI에게 버그 수정을 요청할 때는 정보를 최대한 많이 제공하는 것이 중요합니다.

좋은 버그 보고 형식

[버그 설명]
북마크를 삭제하면 목록에서 사라지는데, 페이지를 새로고침하면 다시 나타남.

[재현 방법]
1. 북마크를 3개 추가
2. 가운데 북마크의 삭제 버튼 클릭
3. 목록에서 사라짐 (정상)
4. F5로 새로고침
5. 삭제된 북마크가 다시 나타남 (비정상)

[예상 동작]
삭제한 북마크는 새로고침 후에도 사라져 있어야 함.

[브라우저 콘솔 에러]
(없음 / 또는 에러 메시지 전체)

[관련될 것 같은 파일]
BookmarkList.jsx, storage.js

이렇게 구체적으로 전달하면 AI가 무엇을 봐야 할지 바로 파악할 수 있습니다.

에러 메시지가 있는 경우

브라우저에서 에러가 나면 콘솔(F12 → Console 탭)에 빨간 글씨로 메시지가 나타납니다. 이것을 전부 복사해서 Claude Code에 붙여넣으면 됩니다.

아래 에러가 나고 있어. 원인과 해결 방법 알려줘.

Uncaught TypeError: Cannot read properties of undefined (reading 'filter')
    at BookmarkList.jsx:23
    at Array.map (<anonymous>)
    at BookmarkList (BookmarkList.jsx:18)

에러 메시지에는 어느 파일의 몇 번째 줄에서 발생했는지가 나옵니다. AI는 이 정보를 바탕으로 해당 코드를 찾아 원인을 파악합니다.

디버깅 과정에서 자주 쓰는 프롬프트 패턴

원인 분석 먼저 요청

아래 버그의 원인을 분석해줘. 수정은 아직 하지 말고 왜 이런 현상이 일어나는지 설명해줘.

[버그 설명]

먼저 원인을 이해하고 수정 방향을 파악한 뒤 고치도록 합니다. 바로 “고쳐줘”라고 하면 표면적 증상만 해결하고 근본 원인이 남는 경우가 있습니다.

단계별 디버깅 요청

이 버그의 원인을 찾기 위해 단계별로 확인해줘.
각 단계에서 어떤 값이 들어오고 나가는지 console.log를 추가해줘.
내가 직접 실행해보고 결과를 알려줄게.

AI가 코드를 직접 실행할 수 없는 경우, 개발자가 실행 결과를 다시 알려주면서 원인을 좁혀가는 방식입니다.

수정 후 검증 요청

수정한 코드가 맞는 방향인지 확인해줘.
다른 기능에 영향을 줄 수 있는 부분이 있는지 같이 봐줘.

”어느 부분에서 났지?” — 영향 범위 파악하기

버그의 원인을 찾았다면 이제 “이 버그가 얼마나 많은 부분에 영향을 주는가”를 파악해야 합니다. 하나의 버그가 여러 기능에 걸쳐 영향을 줄 수 있습니다.

예를 들어 localStorage에 데이터를 저장하는 방식에 문제가 있다면 북마크 저장뿐만 아니라 태그 저장, 설정 저장 등 localStorage를 쓰는 모든 기능에 영향을 줄 수 있습니다.

이때도 AI에게 물어보면 됩니다. CLAUDE.md에 구조가 정리되어 있으면 더 정확합니다.

storage.js와 연결된 컴포넌트가 무엇인지 확인해줘.
localStorage 저장 로직에 버그가 있다면 어느 기능들이 영향을 받는지 파악해줘.

Claude Code가 코드와 구조 설명을 읽어 영향 범위를 파악합니다. 구조가 잘 기록되어 있을수록 더 정확한 분석이 가능합니다.

버그 수정 후 확인사항

버그를 수정한 뒤에는 두 가지를 확인합니다.

1. 버그가 실제로 해결됐는가

재현 방법을 그대로 따라가서 버그가 없어졌는지 확인합니다. 로컬에서 확인 후 배포해서 실제 환경에서도 확인합니다.

2. 다른 기능이 망가지지 않았는가

버그 수정이 다른 기능에 영향을 줄 수 있습니다. 앞에서 파악한 영향 범위에 있는 기능들을 직접 사용해보면서 이상이 없는지 확인합니다.

버그를 방지하는 습관

사후에 버그를 고치는 것보다 버그가 생기지 않도록 예방하는 것이 더 효율적입니다.

습관	방법
기능 추가 후 직접 테스트	새 기능을 추가하면 관련 기능들을 직접 사용해서 확인
범위를 명시한 프롬프트	AI에게 요청할 때 기존 기능에 영향 주지 말 것을 명시
작은 단위로 배포	한 번에 많은 기능을 배포하지 않고 조금씩 배포
변경 이력 기록	무엇을 언제 바꿨는지 기록 (GitHub 커밋 메시지)

바이브코딩에서 완벽하게 버그를 예방할 수는 없습니다. 하지만 발견했을 때 빠르게 원인을 찾고 수정할 수 있는 구조를 갖추는 것이 중요합니다.

다음 편에서

마지막 편에서는 바이브코딩으로 만든 서비스를 장기적으로 유지하는 방법을 다룹니다. 초기의 빠른 속도를 유지하면서도 서비스가 성장해도 관리 가능한 상태로 두는 루틴과 사고방식을 정리합니다.