Claude Code로 교구 안 될 때 고치는 법 | 디버깅 기초 — 교사도 할 수 있습니다

만든 교구가 안 돌아가면 당황하죠? 저도 처음엔 그랬습니다.

HTML 파일을 더블클릭했는데 빈 화면이 나오거나, 버튼을 눌러도 아무 반응이 없거나, 글자가 깨져서 나오면... 솔직히 "아, 역시 나한테 코딩은 무리였나" 싶은 생각이 들잖아요.

그런데요, Claude Code한테 "이거 왜 안 돼?" 하면 알아서 고쳐줍니다. 진짜로요.

오늘은 교구가 안 될 때 당황하지 않고 해결하는 3가지 방법을 알려드리겠습니다. 코드를 읽을 줄 몰라도 전혀 상관없습니다.

교구가 안 될 때 흔한 증상 4가지

먼저, "안 된다"는 게 구체적으로 어떤 상황인지 정리해 볼게요. 여러분이 겪는 증상은 대부분 이 네 가지 중 하나입니다.

어떤 증상이든 상관없습니다. 아래 방법을 따라하면 됩니다.

방법 1. Claude Code에게 그냥 물어보기

Claude Code가 실행된 상태에서, 이렇게만 입력하세요.

> 이 파일 실행했는데 빈 화면이야. 뭐가 문제인지 찾아서 고쳐줘

또는 좀 더 구체적으로:

> ox-quiz.html을 브라우저에서 열었는데 버튼을 눌러도 아무 반응이 없어.
  원인 찾아서 고쳐줘

Claude Code는 이렇게 동작합니다:

1. 해당 파일의 코드를 전부 읽습니다
2. 문법 오류, 빠진 코드, 잘못된 로직을 자동으로 찾습니다
3. "여기가 문제입니다"라고 설명해 줍니다
4. 수정된 코드를 바로 파일에 반영합니다

여러분이 할 일은 브라우저에서 새로고침(F5)하는 것뿐입니다.

방법 2. 브라우저 개발자도구 활용하기

따라해 보세요. 정말 간단합니다.

Step 1. 개발자도구 열기

1. 문제가 있는 HTML 파일을 브라우저(크롬)에서 엽니다
2. 키보드에서 F12 키를 누릅니다
   • 또는 Ctrl + Shift + I를 눌러도 됩니다
3. 화면 오른쪽(또는 아래쪽)에 뭔가 복잡한 패널이 열립니다 — 겁먹지 마세요!

Step 2. Console 탭에서 에러 찾기

1. 열린 패널 상단에서 Console 탭을 클릭합니다
2. 빨간색 글자가 보이나요? 그게 에러 메시지입니다!
3. 빨간색 메시지를 드래그해서 선택 → Ctrl+C로 복사합니다

Step 3. Claude Code에 붙여넣기

> 이 교구를 실행하면 아래 에러가 나와. 고쳐줘.

  Uncaught TypeError: Cannot read properties of null
  (reading 'addEventListener')
  at ox-quiz.html:45

이렇게 에러 메시지를 함께 전달하면, Claude Code는 45번째 줄 근처의 문제를 정확히 파악하고 바로 고쳐줍니다.

방법 3. 단계별로 확인하기

Claude Code에게 이렇게 순서대로 요청해 보세요.

# 1단계: HTML 뼈대만 먼저
> 이 교구에서 HTML 구조만 먼저 보여줘. CSS랑 JavaScript는 빼고.

# 2단계: 뼈대가 잘 보이면 CSS 추가
> 좋아, 이제 CSS 스타일을 추가해줘

# 3단계: 스타일도 괜찮으면 JS 추가
> 이제 JavaScript 기능을 추가해줘

이렇게 하면 어느 단계에서 문제가 생기는지 바로 알 수 있습니다.

• 1단계에서 깨지면 → HTML 구조 문제
• 2단계에서 깨지면 → CSS 스타일 문제
• 3단계에서 깨지면 → JavaScript 로직 문제

문제가 생긴 단계를 Claude Code에게 알려주면, 해당 부분만 집중적으로 수정해 줍니다.

실전 예시: 타이머가 안 되는 교구

1단계: 브라우저에서 에러 확인

F12 → Console 탭을 열어봅니다. 이런 메시지가 보입니다:

❌ Uncaught TypeError: Cannot read properties of null
   (reading 'textContent')
   at nextQuestion (ox-quiz.html:87)

2단계: Claude Code에 전달

> ox-quiz.html에서 타이머가 0이 되면 다음 문제로 넘어가야 하는데 안 넘어가.
  Console에 이 에러가 나와:
  Uncaught TypeError: Cannot read properties of null
  (reading 'textContent') at nextQuestion (ox-quiz.html:87)

3단계: Claude Code가 분석하고 수정

Claude Code의 응답 (예시):

🔍 문제를 찾았습니다!

87번째 줄에서 nextQuestion 함수가 다음 문제의 텍스트 요소를
찾으려고 하는데, 마지막 문제 이후에는 더 이상 요소가 없어서
null 에러가 발생하고 있었습니다.

✅ 수정 내용:
- 마지막 문제인지 확인하는 조건문을 추가했습니다
- 마지막 문제 이후에는 결과 화면을 표시하도록 변경했습니다

✅ Updated ox-quiz.html

4단계: 확인

브라우저에서 F5(새로고침)를 누르면 — 타이머가 정상 작동합니다!

전체 과정이 2분도 안 걸렸습니다. 코드를 한 줄도 직접 수정하지 않았고요.

💡 핵심: "왜 안 되는지" 설명 안 해도 됩니다

Claude Code는 여러분이 만든 파일의 코드를 처음부터 끝까지 읽고 분석합니다. 이런 것들을 자동으로 해줘요:

• 문법에 오류가 있는지 (괄호가 빠졌다든지, 오타가 있다든지)
• 로직이 맞는지 (순서가 뒤바뀌었다든지, 조건이 잘못됐다든지)
• 서로 연결이 안 된 부분이 있는지 (HTML에서 버튼 이름은 A인데 JavaScript에서 B를 찾고 있다든지)

그래서 이렇게만 말해도 충분합니다:

> 이 파일이 안 돼. 뭐가 문제야?

물론 에러 메시지를 함께 주면 더 빠르지만, 없어도 괜찮습니다. Claude Code가 알아서 찾아냅니다.

💡 예방 팁: 만들 때부터 테스트 요청하기

사실 가장 좋은 디버깅은 처음부터 에러가 안 나게 만드는 것이죠. 교구를 만들 때 프롬프트 끝에 이 한 줄만 추가해 보세요.

> OX퀴즈 HTML 교구를 만들어줘. 과목은 통합사회,
  문제는 5개, 타이머 30초.

  다 만들면 테스트해보고 문제 있으면 알려줘.

이 한 줄이 추가되면, Claude Code는:

1. 교구를 만들고
2. 스스로 코드를 검토해서
3. 문제가 있으면 알아서 수정한 다음
4. "이런 부분을 수정했습니다"라고 보고까지 해줍니다

자주 발생하는 에러 TOP 5

교구를 만들다 보면 자주 만나게 되는 에러들이 있습니다. 이 표를 참고해서 Claude Code에게 전달해 보세요.

#	에러 메시지 (요약)	무슨 뜻이냐면	Claude Code에게 이렇게 말하세요
1	Cannot read properties of null	HTML에서 특정 요소를 찾지 못했어요. 이름(id)이 틀렸거나, 아직 화면에 안 그려진 상태에서 접근했어요.	"이 에러가 나와. 요소 이름이 안 맞는 것 같은데 확인하고 고쳐줘"
2	Unexpected token	코드에 오타가 있어요. 괄호나 따옴표가 빠졌거나 잘못 닫혔어요.	"문법 오류가 있다고 하는데, 코드 전체 검사해서 고쳐줘"
3	is not a function	존재하지 않는 함수를 호출하고 있어요. 함수 이름에 오타가 있거나, 함수를 정의하지 않았어요.	"함수가 없다는 에러가 나와. 함수 이름이 맞는지 확인하고 수정해줘"
4	한글 깨짐 (����)	파일의 인코딩 설정이 빠졌어요.	"한글이 깨져 나와. <meta charset> 확인하고 수정해줘"
5	모바일에서 레이아웃 깨짐	반응형 디자인 설정이 없어요.	"핸드폰에서 보면 레이아웃이 깨져. 모바일 대응 추가해줘"

오늘 배운 것 정리

1. 방법 1 (가장 쉬움): Claude Code에게 "이 파일 안 돼. 고쳐줘"
2. 방법 2 (더 정확): F12 → Console → 빨간 에러 복사 → Claude Code에 붙여넣기
3. 방법 3 (복잡할 때): HTML → CSS → JS 순서로 단계별 확인
4. 예방법: "테스트해보고 문제 있으면 알려줘" 프롬프트 추가

기억하세요. 코딩을 몰라도 디버깅할 수 있습니다. 여러분은 "안 되는 증상"만 설명하면 됩니다. 원인을 찾고 고치는 건 Claude Code의 몫이에요.

교구 만들다가 막히셨나요? 댓글로 에러 메시지를 남겨주시면 함께 해결해 드리겠습니다! 같은 문제로 고민하는 선생님이 분명 계실 거예요. 😊