2026년 9월 8일 화요일

[실과·수학] 3대 에러 디버깅 방탈출 - 코드 속 숨은 사마귀를 잡아라!

코드 속 사마귀(Bug)를 잡아라! — 3대 에러(타입·문법·모듈) 디버깅 방탈출 퀴즈 웹앱

🐛 초등 5~6학년 실과 '소프트웨어로 문제를 해결해요' 및 수학 '규칙 찾기' 융합 — 학생들이 코드 속에 숨은 3대 오류 유형(타입 에러, 문법 오류, 모듈 오류)을 찾아내는 게임 형태의 디버깅 방탈출입니다. 컴파일러처럼 엄격한 에러 코드와 정확한 수정 제안이 정답 카드로 작동하여, SW 개발의 절반을 차지하는 디버깅 과정을 아이들이 재미있게 마스터합니다.

📖 한 줄 정의

심기 모드(데이터 임베딩): API 데이터를 미리 받아 HTML 파일 안 상수로 박아두는 방식(앱 실행 중 외부 통신 0).

학내망 원칙: 학생 개인정보(실명·의견·성적·상담 기록)의 외부 수집·저장·전송 금지(쿼리에 학생 데이터가 담기는 외부 API 호출 포함) — 일반 공개 쿼리의 외부 호출은 허용하며, 학생 배포본은 심기 폴백(EMBED 상수)을 항상 내장한다.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
문법 오류(Syntax) 컴퓨터가 문장을 끝까지 읽지도 못하는 오류 — 괄호 누락, 오타, 세미콜론 미삽입 등입니다. const x = (5 + 3; ← 괄호 하나가 닫히지 않았습니다! (방탈출 1단계)
타입 오류(TypeError) "숫자에 사과를 더하려고 하는 오류" — 문자와 숫자를 섞어 연산하거나 없는 변수를 불러올 때 발생합니다. console.log(studentNames[25]); ← 20명 명단에서 25번을 찾고 있습니다! (방탈출 2단계)
모듈/참조 오류 "없는 사람한테 일을 시키는 오류" — 존재하지 않는 파일이나 함수를 가져오려고 할 때 발생합니다. import { caculate } from 'math'; ← 'calculate'의 오타입니다! (방탈출 3단계)

2. 핵심 아키텍처 해설

① 에러 시나리오 데이터: BUG_STAGES 상수

const BUG_STAGES = [
  {
    stage: 1,
    type: "문법 오류 (Syntax Error)",
    difficulty: "쉬움",
    code: `const x = (5 + 3;\nconsole.log(x);`,
    question: "위 코드에서 어느 부분이 잘못되었나요?",
    options: ["괄호가 닫히지 않았다", "console.log를 사용할 수 없다", "x라는 변수명은 금지된다"],
    answer: 0,
    hint: "코드는 문장을 끝내기 전에 열어둔 괄호를 반드시 닫아야 해요.",
    fix: "const x = (5 + 3);"
  },
  {
    stage: 2,
    type: "타입 오류 (TypeError)",
    difficulty: "보통",
    code: `const scores = [85, 90, 78];\nconst avg = scores[5];\nconsole.log(avg.toFixed(1));`,
    question: "위 코드가 작동하지 않는 이유는 무엇인가요?",
    options: ["toFixed는 존재하지 않는다", "scores[5]는 존재하지 않는(undefined)", "배열은 수정할 수 없다"],
    answer: 1,
    hint: "배열의 인덱스는 0부터 시작합니다. 0,1,2 세 개만 있어요!",
    fix: "const avg = scores[2];"
  },
  {
    stage: 3,
    type: "참조 오류 (Reference/Module Error)",
    difficulty: "도전",
    code: `import { caculateAverage } from './math-tools.js';\nconsole.log(calculateAverage(10, 20));`,
    question: "함수를 불러왔는데도 오류가 납니다. 무엇이 문제일까요?",
    options: ["import는 사용할 수 없다", "이름이 오타(caculate vs calculate)다", "경로가 틀렸다"],
    answer: 1,
    hint: "가져온 이름과 사용하는 이름의 철자를 자세히 비교해 보세요.",
    fix: "import { calculateAverage } from './math-tools.js';"
  }
];

교실에서 바로 사용할 수 있는 3대 오류 유형별 실제 발생 사례와 정답, 수정 코드를 상수로 내장하는 심기 모드(데이터 임베딩) 구조입니다.

② 방탈출 타이머 & 잠금 로직

let timeLeft = 180; // 3분 타이머
const timer = setInterval(() => {
  timeLeft--;
  updateClock(timeLeft);
  if (timeLeft <= 0) {
    clearInterval(timer);
    showFailScreen("3분 내 방을 탈출하지 못했습니다!");
  }
}, 1000);

function checkAnswer(stageId, userChoice) {
  if (userChoice === BUG_STAGES[stageId].answer) {
    soundEffect("correct");
    unlockNextStage(stageId + 1); // 다음 단계 잠금 해제
  } else {
    soundEffect("wrong");
    timeLeft -= 15; // 오답 시 15초 감점!
  }
}

정답 선택 시 잠금 해제로 진행하고, 오답 시 타이머가 15초씩 감소하는 긴장감 넘치는 게이미피케이션 메커니즘으로 몰입도를 높입니다.

③ 코드 에디터 하이라이팅 스타일

.code-block {
  font-family: 'Consolas', 'Courier New', monospace;
  background: #1e1e2e;
  color: #cdd6f4;
  padding: 16px;
  border-radius: 8px;
  font-size: 14px;
  line-height: 1.6;
  white-space: pre-wrap;
}
.bug-highlight {
  background: rgba(243, 139, 168, 0.25);
  border-bottom: 2px solid #f38ba8;
  animation: pulse 1s infinite;
}

VS Code 같은 다크모드 코드 에디터 느낌의 시각적 구현으로 아이들이 실제 개발 환경에 가까운 UI를 경험하게 합니다.

3. 초보자를 위한 바이브 코딩 실전 사용 예시

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트'를 복사합니다.
  2. 역질문 답변 — 제미나이가 묻는 대상 학년과 방탈출 방 개수에 답합니다.
  3. HTML 파일 실행 — 메모장에 붙여넣고 디버깅방탈출.html로 저장 후 더블클릭합니다.

제미나이 전용 에러 제로 프롬프트

[🚨 에러 방지 기본 안전장치]
1. 단일 HTML 파일 완결성: 외부 라이브러리, 코드 에디터 라이브러리(Prism/Highlight.js 등) 없이 순수 바닐라 HTML/CSS/JS로 완성한다.
2. 심기 모드(데이터 임베딩): const BUG_STAGES = [...] 상수에 3대 오류 유형(문법, 타입, 참조)별 시나리오를 3~6개 내장한다.
3. 게이미피케이션 로직: 3분 타이머, 정답 시 다음 문 잠금 해제, 오답 시 15초 감점 방식으로 구현한다.
4. 다크모드 코드 에디터 UI: VS Code 스타일의 다크 배경, 모노스페이스 폰트, 오류 부분 붉은색 하이라이트 효과를 적용한다.
5. 학생 개인정보 0: 학생 실명 입력 없이 조별 번호 및 '디버깅 전문가' 닉네임만 사용한다.
6. // TODO, /* 생략 */ 등의 미완성 코드는 절대 넣지 말고 끝까지 완성한다.

[❓ 역질문 유도]
코드를 즉시 작성하지 말고, 기획을 구체화하기 위한 다음 3가지 질문을 먼저 나에게 던져줘:
1. 방탈출 방 개수는 몇 개로 할까요? (기본: 3단계)
2. 오류 코드 언어는 무엇으로 할까요? (JavaScript / Python 스타일 의사코드)
3. 최종 탈출 성공 시 '버그 제거 마스터' 인증서를 표시할까요?

🎯 에디터 한줄평

"실패를 두려워하기보다 '버그를 잡는 탐정'이 되어보라는 선언입니다. 실무 개발자도 80%의 시간을 디버깅에 씁니다. 오류 코드를 미워하지 않고 규칙적인 퍼즐로 즐겁게 다루는 경험은, 아이들이 SW를 포기하는 가장 큰 이유인 '갑작스러운 붉은 에러 문구 공포'를 완벽하게 이겨내는 훈련입니다."

📚 기술·교육 참고 링크

  • CS 언플러그드 디버깅 개념: 오류 유형별 발생 원인 및 수정 방법
  • 교육과정 연계: 초등 5~6학년 실과(소프트웨어로 문제를 해결해요), 수학(규칙 찾기, 논리와 추론)
By 시간: