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