클로드가 이상한 코드를 줬을 때

망한 게 아니라, 단서가 생긴 겁니다

버튼을 눌렀는데 아무 일도 일어나지 않습니다.

화면은 그대로입니다. 터미널에는 낯선 영어가 길게 뜹니다. 브라우저 콘솔에는 빨간 글씨가 보입니다.

이 순간 초보자는 보통 이렇게 생각합니다.

망했다.

하지만 Claude Code를 쓸 때는 다르게 생각해도 됩니다.

단서가 생겼다.

에러 메시지는 꾸중이 아닙니다. 고칠 위치를 알려주는 영수증에 가깝습니다. 우리는 그 영수증을 Claude에게 그대로 건네면 됩니다.

오늘 할 일은 간단합니다.

• 터미널 오류를 복사해서 Claude에게 전달합니다.

• 브라우저 콘솔 오류를 복사해서 Claude에게 전달합니다.

• 화면이 이상할 때는 말로 상황을 정리해서 전달합니다.

• Claude가 고친 뒤에도 안 되면 이어서 다시 점검시킵니다.

• 엉뚱한 파일을 고치려 하면 파일명을 직접 지정합니다.

• 해결되면 세 줄 요약을 남깁니다.

디버깅은 어려운 기술처럼 들리지만, 오늘은 이렇게만 기억하면 됩니다.

문제를 본다 → 그대로 복사한다 → Claude에게 다시 준다 → 수정 범위를 확인한다

지금 프로젝트는 세 파일입니다

우리는 지금 my-first-page 폴더 안에 작은 자기소개 페이지를 가지고 있습니다.

my-first-page/
├─ index.html
├─ style.css
└─ script.js

각 파일의 역할은 이제 익숙할 겁니다.

오늘은 이 세 파일 안에서만 문제를 찾습니다.

파일이 적을수록 디버깅은 쉬워집니다. 그래서 Claude에게도 계속 이렇게 말할 겁니다.

현재 index.html, style.css, script.js 세 파일 기준으로 봐줘.

이 한 문장은 Claude의 시야를 좁혀 줍니다. 시야가 좁아지면 엉뚱한 곳을 고칠 확률도 줄어듭니다.

오류는 세 종류로 나눠서 잡습니다

초보자가 만나는 문제는 대부분 세 가지입니다.

중요한 건 원인을 바로 알아맞히는 게 아닙니다.

먼저 증거를 정확히 모으는 것입니다.

Claude에게 이렇게 던지면 약합니다.

안 돼. 고쳐줘.

이렇게 던지면 훨씬 강합니다.

다크모드 버튼을 눌렀는데 화면이 바뀌지 않아.
브라우저 콘솔에는 아래 에러가 나와.

Uncaught TypeError: Cannot read properties of null

현재 index.html, style.css, script.js 세 파일을 보고 원인 후보를 찾고 수정까지 해줘.

차이는 단순합니다.

문제를 말했고, 에러를 붙였고, 볼 파일을 지정했습니다.

1. 터미널 오류 복사하기

터미널 오류는 Claude Code 화면이나 명령어 실행 화면에 뜹니다.

예를 들어 이런 식입니다.

Error: Cannot find module './script.js'

또는 이런 메시지가 나올 수 있습니다.

Permission denied

command not found

No such file or directory

뜻을 전부 해석하려고 하지 마세요. 지금 할 일은 해석이 아니라 복사입니다.

터미널에서 오류 메시지를 마우스로 드래그합니다.

• Windows: 드래그한 뒤 Ctrl + C

• Mac: 드래그한 뒤 Command + C

잘 안 되면 오류가 보이는 부분을 조금 넉넉히 복사해도 됩니다. 위아래 5줄 정도 같이 복사하면 Claude가 더 잘 봅니다.

그리고 Claude Code에 이렇게 붙여 넣습니다.

터미널에 아래 오류가 나왔어.

[여기에 오류 메시지 붙여넣기]

이 에러를 설명하지 말고, 원인 후보를 찾고 수정까지 해줘.
현재 index.html, style.css, script.js 세 파일 기준으로 확인해줘.
새 파일을 만들지 말고 필요한 부분만 수정해줘.

여기서 핵심 문장은 이것입니다.

이 에러를 설명하지 말고, 원인 후보를 찾고 수정까지 해줘.

초보자에게 긴 설명은 가끔 부담입니다. 지금은 강의보다 수리가 먼저입니다.

2. 브라우저 콘솔 오류 복사하기

버튼을 눌렀는데 화면이 반응하지 않는다면, 가장 먼저 볼 곳은 브라우저 콘솔입니다.

브라우저에서 index.html을 열고 개발자 도구를 켭니다.

• Windows: 보통 F12 또는 Ctrl + Shift + J

• Mac: 보통 Command + Option + J

브라우저마다 단축키가 조금 다를 수 있습니다. 단축키가 안 되면 브라우저 메뉴에서 개발자 도구 또는 Developer Tools를 찾아 여세요.

위쪽 탭에서 Console을 누릅니다.

그리고 버튼을 다시 클릭합니다.

빨간 글씨가 뜨면 그게 단서입니다.

자주 보이는 메시지는 이런 모양입니다.

Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')

ReferenceError: darkModeButton is not defined

Failed to load resource: net::ERR_FILE_NOT_FOUND

이 문장을 그대로 복사합니다.

브라우저 콘솔에서는 오류 줄을 클릭하거나 드래그해서 복사할 수 있습니다. 잘 안 되면 오류 문장을 직접 타이핑해도 됩니다. 정확히 복사하면 더 좋지만, 완벽하지 않아도 괜찮습니다.

Claude에게는 이렇게 말합니다.

브라우저에서 다크모드 버튼을 눌렀는데 작동하지 않아.
Console 탭에 아래 오류가 나왔어.

Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')

이 에러를 설명하지 말고, 원인 후보를 찾고 수정까지 해줘.
현재 index.html, style.css, script.js 세 파일을 함께 보고 확인해줘.
큰 구조 변경 없이 필요한 부분만 고쳐줘.

이 요청은 꽤 좋습니다.

Claude가 확인할 수 있는 단서가 충분합니다.

• 어떤 행동을 했는지: 다크모드 버튼 클릭

• 어디에 오류가 나왔는지: Console 탭

• 실제 오류 문장: Cannot read properties of null

• 봐야 할 파일: index.html, style.css, script.js

• 제한 조건: 큰 구조 변경 금지

이 정도면 초보자도 충분히 디버깅을 시작할 수 있습니다.

3. 화면 이상 현상은 말로 캡처하기

모든 문제가 에러 메시지로 나오지는 않습니다.

가끔은 콘솔에 아무 오류도 없는데 화면만 이상합니다.

예를 들면 이런 상황입니다.

• 버튼이 왼쪽 위에 붙어 있다.

• 카드가 화면 밖으로 밀려났다.

• 다크모드가 켜졌는데 글자가 안 보인다.

• 버튼을 눌러도 색이 너무 조금만 바뀐다.

• 모바일 화면에서 글자가 잘린다.

이럴 때는 화면을 말로 캡처하면 됩니다.

Claude는 내 브라우저 화면을 자동으로 보는 것이 아닙니다. 그래서 내가 본 장면을 짧게 설명해 줘야 합니다.

아래 형식을 그대로 쓰세요.

화면에 에러 메시지는 없지만, 보이는 모습이 이상해.

현재 상태:
- 다크모드 버튼을 누르면 배경은 어두워짐
- 그런데 카드 안의 글자도 어두워져서 거의 안 보임
- 버튼 색도 배경과 비슷해서 눈에 잘 안 띔

원하는 상태:
- 다크모드에서 글자는 밝은 회색으로 보이면 좋겠어
- 버튼은 배경보다 조금 더 밝게 보여야 해
- 기존 카드형 디자인은 유지하고 싶어

style.css 중심으로 원인 후보를 찾고 수정까지 해줘.
index.html 구조는 가능하면 건드리지 마.

이 방식은 아주 실용적입니다.

화면 이상은 보통 코드 오류보다 감각의 문제입니다. 그래서 "현재 상태"와 "원하는 상태"를 같이 말해야 합니다.

짧게 줄이면 이렇게도 쓸 수 있습니다.

다크모드는 켜지는데 글자가 배경과 비슷해서 잘 안 보여.
style.css에서 색 대비를 읽기 좋게 조정해줘.
기존 레이아웃과 HTML 구조는 그대로 유지해줘.

오늘의 핵심 템플릿

이 장에서 가장 많이 쓸 문장은 이것입니다.

이 에러를 설명하지 말고, 원인 후보를 찾고 수정까지 해줘.

여기에 상황만 붙이면 됩니다.

터미널 오류용

터미널에 아래 오류가 나왔어.

[오류 메시지 붙여넣기]

이 에러를 설명하지 말고, 원인 후보를 찾고 수정까지 해줘.
현재 프로젝트의 관련 파일을 확인하되, 큰 구조 변경은 하지 마.

브라우저 콘솔 오류용

브라우저 Console 탭에 아래 오류가 나왔어.

[오류 메시지 붙여넣기]

이 에러를 설명하지 말고, 원인 후보를 찾고 수정까지 해줘.
현재 index.html, style.css, script.js 세 파일을 함께 봐줘.

화면 이상 현상용

에러 메시지는 없지만 화면이 이상해.

현재 보이는 모습:
- [지금 화면 설명]

원하는 모습:
- [원하는 화면 설명]

원인 후보를 찾고 수정까지 해줘.
가능하면 [파일명]만 수정해줘.

초보자에게 좋은 프롬프트는 길고 멋진 문장이 아닙니다.

증거가 들어 있는 문장입니다.

실습: 다크모드 버튼이 안 될 때

이제 실제 상황처럼 연습해 봅시다.

브라우저에서 버튼을 눌렀는데 다크모드가 켜지지 않는다고 가정하겠습니다.

먼저 개발자 도구를 엽니다.

Windows: F12 또는 Ctrl + Shift + J
Mac: Command + Option + J

Console 탭을 봅니다.

만약 이런 오류가 보인다면 그대로 복사합니다.

Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')

Claude Code에 이렇게 입력합니다.

다크모드 버튼을 눌러도 화면이 바뀌지 않아.
브라우저 Console 탭에는 아래 오류가 나와.

Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')

이 에러를 설명하지 말고, 원인 후보를 찾고 수정까지 해줘.
현재 index.html, style.css, script.js 세 파일을 함께 확인해줘.
새 파일을 만들지 말고, 기존 세 파일 안에서만 최소 수정으로 해결해줘.

Claude는 보통 이런 원인 후보를 찾습니다.

• JavaScript가 버튼을 찾기 전에 먼저 실행됨

• index.html의 버튼 id와 script.js의 id가 서로 다름

• script.js 연결 위치가 잘못됨

• 버튼 요소가 HTML에 없음

이 내용을 다 이해하지 못해도 괜찮습니다.

중요한 건 Claude가 실제 파일을 보고 수정안을 제안한다는 점입니다.

제안이 나오면 바로 y를 누르지 말고 지난 장에서 배운 세 가지를 봅니다.

1. 어떤 파일을 바꾸는가?
2. 예상한 파일인가?
3. 너무 큰 변경은 아닌가?

이 경우 자연스러운 변경은 보통 이 정도입니다.

Modify index.html
Modify script.js

또는 CSS 문제라면 이렇게 보일 수 있습니다.

Modify style.css

괜찮다면 승인합니다.

y

그리고 브라우저를 새로고침합니다.

• Windows: Ctrl + R

• Mac: Command + R

다시 버튼을 누릅니다.

화면이 바뀌면 성공입니다.

고쳤는데도 안 되면 이어서 말합니다

Claude가 한 번에 고치지 못할 때도 있습니다.

이상한 일이 아닙니다. 실제 작업에서도 디버깅은 한 번에 끝나지 않는 경우가 많습니다.

이때 처음부터 다시 설명하지 않아도 됩니다.

바로 이어서 이렇게 말하세요.

아직 같은 문제가 남아 있어.
방금 수정한 내용 기준으로 다시 점검해줘.
브라우저를 새로고침한 뒤 버튼을 눌렀지만 다크모드가 켜지지 않아.
Console에는 아래 메시지가 보여.

[새 오류 메시지 붙여넣기]

핵심 문장은 이것입니다.

방금 수정한 내용 기준으로 다시 점검해줘.

이 말은 Claude에게 "이전 답을 잊고 새로 시작하지 말고, 방금 바꾼 코드까지 포함해서 다시 봐"라고 알려줍니다.

에러 메시지가 바뀌었다면 새 메시지도 붙여 넣습니다.

처음에는 이런 오류였는데,

Cannot read properties of null

수정 후에는 이렇게 바뀔 수 있습니다.

darkModeButton is not defined

이건 나빠진 게 아닐 수 있습니다. 문제가 한 겹 벗겨지면서 다음 단서가 나온 겁니다.

그럴 때는 이렇게 이어갑니다.

오류 메시지가 바뀌었어.
이전에는 Cannot read properties of null 이었고,
지금은 darkModeButton is not defined 라고 나와.

방금 수정한 내용 기준으로 다시 점검해줘.
index.html의 버튼 이름과 script.js에서 찾는 이름이 서로 맞는지 확인해줘.

디버깅은 대화입니다. 한 번 묻고 끝나는 주문이 아닙니다.

Claude가 엉뚱한 파일을 고치려 할 때

문제는 버튼 하나인데 Claude가 갑자기 여러 파일을 건드리려 할 수 있습니다.

예를 들어 이런 제안이 보일 수 있습니다.

Modify index.html
Modify style.css
Modify script.js
Create theme-manager.js
Modify package.json

지금 우리 프로젝트에는 너무 큽니다.

이럴 때는 승인하지 말고 멈춥니다.

n

그리고 이렇게 말합니다.

수정 범위가 너무 커 보여.
현재 프로젝트는 index.html, style.css, script.js 세 파일만 쓰고 싶어.
새 파일을 만들지 말고, package.json도 건드리지 마.
다크모드 버튼 문제와 직접 관련된 파일만 수정해줘.

더 좁히고 싶다면 파일명을 직접 지정합니다.

이번 문제는 버튼 클릭 동작 문제야.
먼저 script.js만 확인해서 수정해줘.
index.html과 style.css는 건드리지 말고, 필요하면 이유를 먼저 말해줘.

반대로 디자인 문제라면 이렇게 말합니다.

기능은 작동하고 있어.
문제는 다크모드에서 글자가 잘 안 보이는 디자인 문제야.
style.css만 수정해줘.
index.html과 script.js는 건드리지 마.

파일명을 직접 말하면 Claude의 손이 짧아집니다.

초보자에게는 이게 안전합니다.

어디를 고칠지 내가 정해준다.

이 습관이 생기면 Claude가 엉뚱한 방향으로 달려가도 금방 돌려세울 수 있습니다.

화면이 이상할 때 쓰는 빠른 문장들

아래 문장들은 그대로 복사해서 써도 됩니다.

버튼이 안 눌릴 때

버튼을 눌러도 아무 변화가 없어.
Console 오류가 있는지 확인하고, index.html의 버튼과 script.js의 클릭 이벤트 연결을 점검해줘.
필요한 부분만 수정해줘.

다크모드는 되는데 버튼 문구가 안 바뀔 때

다크모드 전환은 되는데 버튼 문구가 바뀌지 않아.
script.js에서 버튼 텍스트를 바꾸는 부분을 확인해줘.
가능하면 script.js만 수정해줘.

색이 이상할 때

다크모드 색이 어색해.
배경, 카드, 글자, 버튼 색이 서로 잘 구분되게 style.css만 조정해줘.
HTML 구조와 JavaScript 기능은 건드리지 마.

레이아웃이 깨졌을 때

화면 가운데 카드 배치가 깨졌어.
기존 카드형 레이아웃을 유지하면서 style.css에서 정렬과 여백만 점검해줘.
index.html 구조는 가능하면 그대로 둬.

갑자기 이전보다 나빠졌을 때

방금 수정 후에 이전보다 화면이 더 깨졌어.
방금 바꾼 내용 기준으로 원인을 다시 점검해줘.
가능하면 가장 최근 수정 중 문제가 된 부분만 되돌리거나 고쳐줘.

이 문장들은 모두 같은 원리입니다.

증상 + 볼 파일 + 건드리지 말 것

이 세 가지가 있으면 Claude가 훨씬 안정적으로 움직입니다.

에러 메시지를 붙일 때의 좋은 모양

에러를 붙여 넣을 때는 아래처럼 블록을 나눠 주면 읽기 쉽습니다.

상황:
다크모드 버튼을 눌렀지만 화면이 바뀌지 않음

오류 메시지:
Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')

확인한 것:
- index.html은 브라우저에서 열림
- 버튼은 화면에 보임
- script.js 파일은 있음

요청:
이 에러를 설명하지 말고, 원인 후보를 찾고 수정까지 해줘.
현재 index.html, style.css, script.js 세 파일만 기준으로 봐줘.

이 정도면 훌륭합니다.

특히 확인한 것을 적으면 Claude가 헛다리를 덜 짚습니다.

예를 들어 버튼이 화면에 보인다면, "버튼이 아예 없는 문제"는 아닐 가능성이 큽니다. 이런 작은 정보가 디버깅 시간을 줄입니다.

수정 후에는 반드시 다시 눌러봅니다

Claude가 코드를 고쳤다고 끝이 아닙니다.

끝은 브라우저에서 확인했을 때입니다.

수정 후에는 이 순서로 확인하세요.

1. 브라우저 새로고침
2. 버튼 클릭
3. 화면 변화 확인
4. 버튼 문구 확인
5. Console 탭에 빨간 오류가 남아 있는지 확인

다크모드 기능이라면 성공 기준은 이렇게 잡습니다.

• 밝은 화면에서 버튼이 보인다.

• 버튼을 누르면 어두운 화면으로 바뀐다.

• 글자가 읽기 좋다.

• 버튼 문구가 상태에 맞게 바뀐다.

• 다시 누르면 밝은 화면으로 돌아온다.

• Console 탭에 새 오류가 없다.

여기까지 확인해야 "고쳐졌다"고 말할 수 있습니다.

Claude의 답변보다 중요한 것은 내 브라우저에서의 결과입니다.

해결되면 세 줄 요약을 남깁니다

문제가 해결되면 바로 다음 작업으로 넘어가고 싶어집니다.

하지만 30초만 더 쓰면 다음 오류가 훨씬 쉬워집니다.

Claude에게 이렇게 물어보세요.

무엇을 바꿨는지 초보자용으로 세 줄 요약해줘.
어떤 파일을 왜 수정했는지도 함께 알려줘.

예상 답변은 이런 느낌이면 충분합니다.

1. index.html의 버튼 id와 script.js에서 찾는 id가 달라서 버튼을 찾지 못했습니다.
2. 두 파일의 버튼 이름을 같게 맞췄습니다.
3. 이제 버튼 클릭 이벤트가 정상 연결되어 다크모드가 켜지고 꺼집니다.

이 요약을 메모장이나 프로젝트 폴더 안에 남겨도 좋습니다.

파일로 남기고 싶다면 Claude에게 이렇게 말합니다.

이번 오류와 해결 내용을 debug-note.md 파일에 짧게 정리해줘.
초보자가 나중에 봐도 이해할 수 있게 작성해줘.

다만 파일을 새로 만들기 싫다면 그냥 대화창에 남겨도 됩니다.

기록의 목적은 멋진 문서가 아닙니다.

나중에 같은 문제가 나왔을 때 덜 놀라기 위한 표시입니다.

오늘의 디버깅 루틴

에러가 나면 이 순서대로 움직이면 됩니다.

1. 멈춘다.
2. 터미널 또는 브라우저 Console에서 오류를 복사한다.
3. 화면 이상이라면 현재 모습과 원하는 모습을 적는다.
4. Claude에게 오류와 관련 파일명을 함께 준다.
5. 수정 제안에서 바뀌는 파일을 확인한다.
6. 승인한다.
7. 브라우저에서 다시 눌러본다.
8. 안 되면 "방금 수정한 내용 기준으로 다시 점검해줘"라고 이어간다.
9. 해결되면 "세 줄 요약"을 받는다.

한 문장으로 줄이면 이렇습니다.

에러를 숨기지 말고, 그대로 Claude에게 먹인다.

초보자는 에러를 보면 지우고 싶어집니다. 하지만 Claude Code와 함께라면 에러는 버릴 것이 아니라 전달할 재료입니다.

마지막 복붙 세트

아래 세 문장만 저장해 두세요.

에러가 떴을 때

아래 에러를 설명하지 말고, 원인 후보를 찾고 수정까지 해줘.
현재 index.html, style.css, script.js 세 파일 기준으로 확인해줘.
큰 구조 변경 없이 필요한 부분만 고쳐줘.

[에러 메시지 붙여넣기]

한 번 고쳤는데도 안 될 때

아직 같은 문제가 남아 있어.
방금 수정한 내용 기준으로 다시 점검해줘.
브라우저를 새로고침하고 다시 확인했지만 문제가 계속돼.

현재 증상:
[지금 보이는 상태 적기]

새 오류 메시지:
[있으면 붙여넣기]

엉뚱한 파일을 고치려 할 때

수정 범위가 너무 커 보여.
이번 문제와 직접 관련된 파일만 수정해줘.
현재는 index.html, style.css, script.js 세 파일만 사용하고 싶어.
새 파일을 만들지 말고, 필요하면 어떤 파일을 왜 수정해야 하는지 먼저 말해줘.

이 세 문장이 있으면 에러 앞에서 덜 흔들립니다.

망했다는 느낌이 드는 순간, 사실은 디버깅 튜토리얼이 시작된 겁니다.

다음 장에서는 파일이 많아졌을 때 Claude가 길을 잃지 않도록, 작업 범위와 맥락을 정리해서 전달하는 법을 배웁니다.