15강: 디버깅
에러는 과정이다
PART 4가 시작됩니다
14강까지 이어진 PART 3(본격 개발) 여정이 끝났어요. 화면도 만들고, 데이터베이스도 붙이고, API도 연결하고, 로그인까지 완성했죠. 진짜 서비스의 뼈대가 갖춰진 거예요.
오늘부터는 **PART 4(검증과 배포)**가 시작돼요. 내가 만든 결과물을 다듬고, 마침내 세상(인터넷)에 공개하는 과정이에요.
그런데 지난 강의들을 따라오면서, 화면이 새빨갛게 변하거나 영어 글자들이 폭포수처럼 쏟아지는 무서운 화면을 본 적 있으신가요? 코딩을 전혀 모르는 우리 같은 사람들에게 가장 공포스러운 순간이죠.
걱정하지 마세요. 코딩 한줄 모르는 저도 매일 겪는 일이에요. 오늘은 디버깅(Debugging, 프로그램의 오류나 버그를 찾아 고치는 과정)에 대한 이야기입니다.
이건 뭐예요?
프로 개발자와 우리의 차이는 '에러를 안 내는 것'이 아니에요. 에러를 냈을 때 **'얼마나 빨리 고치느냐'**의 차이일 뿐이에요.
우리는 에러 메시지를 읽고 해석할 필요가 전혀 없어요. 복사해서 AI에게 붙여넣을 줄만 알면 돼요.
에러에도 종류가 있어요. 요리하는 상황에 비유해서 설명해 드릴게요.
1. 빨간 에러: 컴파일/빌드 에러
컴파일/빌드 에러(Compile/Build Error)는 코드를 실행 가능한 프로그램으로 포장할 때 나는 에러예요. 요리를 시작하기도 전에 "재료가 없다"고 알려주는 것과 같아요.
김치찌개를 끓이려는데 김치가 없으면 불을 켤 수도 없겠죠? 이 에러가 나면 프로그램 자체가 아예 켜지지 않아요. 터미널(Terminal, 컴퓨터와 글자로 대화하는 검은 창)에 빨간 글씨가 잔뜩 쏟아지는 게 특징이에요.
실제로는 이런 모습이에요.
2. 노란 경고: 워닝(Warning)
경고(Warning)는 에러는 아니에요. 요리로 치면 "무딘 칼로 양파를 썰고 있는데, 이대로 해도 요리는 되지만 다칠 수도 있어"라고 주의를 주는 거예요.
당장 앱이 멈추지는 않지만, 나중에 문제가 될 수 있어요. 여유가 될 때 AI에게 물어보고 고치면 돼요.
3. 흰 에러: 런타임 에러
런타임 에러(Runtime Error)는 가장 얄미운 녀석이에요. 프로그램이 정상적으로 켜진 후 실행 중에 나는 에러예요.
요리를 무사히 마쳤고 식탁에도 올렸는데, 막상 한 숟갈 먹어보니 소금 대신 설탕을 넣어서 맛이 이상한 상태예요. 프로그램은 잘 돌아가는데, 특정 버튼을 눌렀을 때 아무 반응이 없거나 화면이 하얗게 멈춰버리는 현상이에요.
이 에러는 터미널이 아니라 브라우저 콘솔에서 찾아야 해요. 브라우저에서 F12 키를 누르면 개발자 도구가 열리고, 거기서 Console(콘솔) 탭을 클릭하면 빨간 글씨로 에러가 적혀 있어요.
# 브라우저 콘솔(F12)에서 이렇게 보여요
Uncaught TypeError: Cannot read properties of undefined (reading 'map')
at TodoList (page.tsx:42:25)
우리는 이렇게 쓰고 있어요
저희 AI//STUDY 아카이브 사이트를 만들 때도 수많은 에러와 싸웠어요. 실전 사례를 소개할게요.
사례 1: 터미널 빌드 에러 — 클로드가 알아서 해결해줘요
저희도 AI//STUDY 사이트를 만들면서 터미널에 빨간 글씨가 폭포수처럼 쏟아지는 걸 수없이 봤어요.
그런데 사실 빌드 에러는 걱정할 필요가 없어요. 클로드 코드 안에서 작업하고 있다면, 클로드가 터미널의 에러를 직접 보고 알아서 고쳐줘요. 여러분이 할 일은 없어요. 그냥 클로드가 "고쳤습니다"라고 할 때까지 기다리면 돼요.
만약 클로드 밖에서 에러를 만났다면, 빨간 글씨를 통째로 복사해서 클로드에게 던지기만 하면 됩니다.
사례 2: 웹에서 뭔가 이상할 때 — F12가 정답이에요
진짜 우리가 직접 해야 하는 건 이쪽이에요. 앱이 켜지긴 했는데 버튼이 안 눌린다거나, 데이터가 안 나온다거나, 화면이 하얗게 멈춘다거나 할 때요.
이때는 무조건 F12를 누르세요. 브라우저 개발자 도구가 열리고, Console(콘솔) 탭을 클릭하면 빨간 글씨로 에러가 적혀 있어요.
해결 방법은 아주 간단해요.
- 빨간 글씨 위에서 마우스 오른쪽 버튼 클릭
- Copy message 선택
- 클로드 코드 대화창에 붙여넣기
- "이 페이지에서 이런 에러가 떠" 한 마디만 덧붙이기
에러 메시지를 읽을 줄 몰라도 괜찮아요. 복사해서 건네면 클로드가 알아서 원인을 찾고 고쳐줘요.
한번 써볼까요?
에러를 만났을 때 당황하지 않고 해결하는 마법의 3단계를 알려드릴게요.
1단계: 에러 메시지 찾아서 복사하기
에러가 어디에 뜨는지부터 알아야 해요. 상황에 따라 다릅니다.
프로그램이 아예 안 켜질 때 -- 터미널(검은 창)을 보세요. 보통 가장 마지막 줄에 있는 Error:로 시작하는 문장이 진짜 범인이에요.
# 터미널에서 에러 찾기 -- 가장 아래쪽에 핵심이 있어요
Error: Cannot find module 'react'
Require stack:
- /my-project/node_modules/next/dist/server/require.js
이 전체를 드래그해서 복사하세요. 어디부터 어디까지 복사할지 모르겠으면 그냥 빨간 글씨 전부 복사하면 돼요. AI가 알아서 핵심을 찾아줘요.
화면은 켜졌는데 뭔가 이상할 때 -- 브라우저에서 F12 키를 누르세요. 오른쪽이나 아래에 개발자 도구가 열려요. 거기서 Console(콘솔) 탭을 클릭하면 빨간 글씨가 보일 거예요.
# 브라우저 콘솔(F12 > Console 탭)에서 찾기
TypeError: Cannot read properties of null (reading 'addEventListener')
at Button (Button.tsx:15:22)
2단계: "뭘 하려 했는지" 같이 말하기
가장 안 좋은 프롬프트(질문)는 에러만 덜렁 복사하고 "이거 고쳐줘"라고 하는 거예요. AI도 상황을 알아야 정확한 진단을 내려요.
좋은 프롬프트의 공식이 있어요. "어디에서 + 무엇을 하다가 + 이 에러가 났어" 3가지를 넣어주세요.
나쁜 예시:
이거 고쳐줘.
TypeError: Cannot read properties of undefined (reading 'map')
좋은 예시:
할 일 목록 페이지(/todos)에서 '새 할 일 추가' 버튼을 눌렀을 때,
브라우저 콘솔에 아래 에러가 나면서 화면이 하얗게 변했어.
TypeError: Cannot read properties of undefined (reading 'map')
at TodoList (page.tsx:42:25)
차이가 느껴지시죠? 좋은 예시에는 어디에서(할 일 목록 페이지), 무엇을 하다가(추가 버튼 클릭), 어떻게 됐는지(화면이 하얗게 변함)가 다 들어있어요.
3단계: 확인, 그리고 '마의 3번' 규칙
AI가 짜준 코드를 적용해 봐요. 단번에 고쳐지면 베스트지만, 또 다른 에러가 날 수도 있어요. 그러면 새로운 에러를 다시 복사해서 붙여넣어요.
여기서 가장 중요한 규칙이 있어요.
이 과정을 3 번 반복했는데도 에러가 해결되지 않거나 점점 산으로 간다면, 미련 없이 되돌려야 해요.
우리에겐 깃(Git, 코드의 과거 상태를 저장해 두는 타임머신)이 있으니까요. 망가지기 전의 깨끗한 상태로 돌아가서 처음부터 다시 AI에게 지시하는 것이 훨씬 빨라요.
왜 3번이냐고요? 경험상 AI가 3번 시도해도 못 고치면, 접근 방식 자체가 틀린 경우가 많아요. 그대로 밀고 나가면 코드가 점점 꼬여서 원상복구가 어려워져요.
클로드 코드 터미널에서는 이렇게
이제 실제로 클로드 코드(Claude Code)를 켜서 에러를 해결해 보고, 안 될 때 과거로 돌아가는 방법을 실습해 볼게요.
먼저 일반 터미널(명령 프롬프트)을 열고 우리 프로젝트 폴더로 이동한 뒤 클로드를 깨워주세요.
# 내 프로젝트 폴더로 이동합니다
cd my-vibecoding-project
# 클로드 코드를 실행합니다
claude
클로드 코드 대화창에서
!를 맨 앞에 붙이면 터미널 명령어를 바로 실행할 수 있어요.
실습 A: 에러 메시지로 디버깅 요청하기
클로드 코드 대화창 안에서, 에러를 고치는 프롬프트를 입력해 보세요. 터미널이나 브라우저 콘솔에서 복사한 에러를 그대로 붙여넣으면 돼요.
내가 지금 '로그인' 버튼을 눌러서 메인 페이지로 넘어가려고 했는데,
터미널에 아래와 같은 에러가 나면서 화면이 멈췄어.
어디가 문제인지 찾아서 고쳐줘.
TypeError: Cannot read properties of undefined (reading 'map')
at TodoList (page.tsx:42:25)
at renderWithHooks (react-dom.development.js:16305:18)
클로드가 코드를 분석하고 수정해 줄 거예요. 수정이 끝나면 개발 서버가 자동으로 새로고침돼요.
실습 B: 의도적으로 에러 만들어 보기
에러에 익숙해지는 가장 좋은 방법은 일부러 에러를 내보는 거예요. 클로드에게 이렇게 말해 보세요.
연습 삼아 일부러 에러를 내볼 거야.
src/app/page.tsx 파일에서 import 하나를 일부러 지워서
Module not found 에러를 만들어줘.
에러가 나면 내가 직접 고쳐볼게.
터미널에 빨간 에러가 뜨면 성공이에요. 이제 그 에러를 다시 클로드에게 보여주면서 "이거 고쳐줘"라고 해보세요. 이 과정을 2~3번 반복하면 에러가 훨씬 덜 무서워져요.
실습 C: 브라우저 콘솔 확인하는 법
개발 서버가 돌아가고 있다면, 브라우저에서 콘솔을 열어보세요.
# 개발 서버가 꺼져 있다면 실행합니다
! npm run dev
- 브라우저에서
http://localhost:3000을 열어요 - 키보드에서
F12키를 누르세요 (맥은Cmd + Option + I) - 상단 탭에서 Console 을 클릭하세요
- 빨간 글씨가 있으면 그게 에러예요. 없으면 정상이에요
빨간 글씨가 보이면 마우스로 드래그해서 복사한 다음, 클로드 코드 대화창에 붙여넣으세요.
실습 D: 타임머신 타기 (되돌리기)
만약 AI가 계속 코드를 수정했는데도 화면이 더 망가져서 아예 처음으로 되돌리고 싶다면, 클로드 대화창에 바로 터미널 명령어를 입력하세요.
# 방금까지 수정한(망가진) 코드를 모두 버리고,
# 마지막으로 커밋(저장)했던 깨끗한 상태로 돌아갑니다
! git reset --hard
이 명령어는 마지막 커밋 이후에 바뀐 모든 파일을 원래대로 되돌려요. 그래서 자주 커밋하는 습관이 중요한 거예요. 커밋을 안 하고 잔뜩 수정한 뒤에 이 명령어를 쓰면, 좋은 것까지 다 날아갈 수 있으니까요.
코드가 다시 돌아왔으면, AI에게 이렇게 말해 보세요.
아까 방식은 틀린 것 같아.
완전히 다른 방식으로 다시 접근해줘.
이전에 시도한 코드는 참고하지 마.
이렇게 하면 AI가 새로운 시각으로 문제를 바라봐요.
이번 강에서 기억할 것
핵심만 정리해 볼게요.
-
에러는 코딩의 실패가 아니에요. 완성으로 가는 당연한 과정이에요. 프로 개발자도 매일 에러를 만나요.
-
에러 메시지는 읽는 게 아니에요. 복사해서 AI에게 주는 거예요. 해석은 AI가 해줘요.
-
에러를 찾는 눈만 있으면 돼요. 터미널의 빨간 글씨, 브라우저 콘솔(
F12)의 빨간 글씨. 이 두 곳만 확인하면 돼요. -
상황을 함께 설명하세요. "어디에서 + 무엇을 하다가 + 이 에러가 났어" 공식을 쓰면 AI가 훨씬 정확하게 고쳐줘요.
-
3번 시도해도 안 풀리면 되돌리세요.
! git reset --hard로 타임머신을 타고 깨끗한 상태에서 다시 시작하세요.
이런 분께 추천해요
- 새빨간 에러 화면만 보면 가슴이 덜컥 내려앉는 분 -- 에러는 친절한 안내문이에요. 무섭지 않다는 걸 이 강의에서 체감하게 될 거예요.
- AI가 고쳐준 코드를 넣었는데 다른 에러가 나서 멘붕에 빠진 분 -- '마의 3번' 규칙과 되돌리기를 알면 멘붕이 사라져요.
- 에러를 혼자 해결해보겠다고 영어를 사전에 검색해 본 적 있는 분 -- 이제 그럴 필요 없어요. 복사 + 붙여넣기면 충분해요.
참고 링크
▸개정 이력1건
- v12026-04-13초판
이 글이 도움이 되었나요?