2026년 9월 6일 일요일

[학급 경영] 등굣길 안전 런 게임 챌린지 - 교통안전 주간 창체 상시 플레이존



[학급 경영] '우리 반 안전 등굣길 런' — 교통안전 주간 창체 수업 완전 정복

🚸 교통안전 주간, 교실 전자칠판을 '상시 플레이존'으로 바꿔보겠습니다. 불법 주정차 차량은 점프로 피하고, 신호등이 녹색불일 때만 횡단보도를 건너는 '안전 등굣길 런 게임' — 학생들이 직접 만들고, 아침 자율 시간에는 전자칠판에서 랭킹 챌린지를 운영합니다.

창의적 체험활동(안전교육)의 핵심인 보행 안전 수칙을 게임 규칙으로 체화합니다. 개인정보 수집 0 설계(닉네임도 저장하지 않는 세션 메모리)와 학내망 '외부 호출 0' 원칙 — 학급 경영 도구로도 안전한 설계를 담았습니다.

📖 한 줄 정의

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

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
수업 시나리오 교통안전 주간 창체 시간에 게임 제작 → 완성 게임을 전자칠판 '상시 플레이존'으로 → 아침 자율 시간 랭킹 챌린지. 게임 제작 자체가 안전교육 수업이 됩니다. 주간 스케줄: 월(기획)→화·수(제작)→목(완성)→금(챌린지 시작).
안전 수칙 → 게임 규칙 불법 주정차 차량 = 피하는 장애물, 녹색불 = 건널 수 있는 창, 빨간불 위 횡단 = 감점 100점. 수칙이 곧 게임 규칙이라 학습 효과가 게임 플레이에 붙어 나옵니다. 신호등 상태 머신으로 규칙을 코드로 옮기기.
배경 아트 횡단보도 줄무늬와 스쿨존 표지판은 이미지 파일 없이 순수 CSS·캔버스 도트로. 외부 이미지가 없어야 학내망 원칙이 자동으로 지켜집니다. CSS 반복 그라디언트로 얼룩말 무늬 횡단보도 그리기.
랭킹 챌린지 닉네임+점수를 세션 메모리(변수)로만 관리 — 브라우저 저장도, 서버 전송도 하지 않습니다. '재미는 남기고, 개인정보는 남기지 않는' 학급 경영용 설계입니다. 전자칠판 TOP 5 랭킹판 + '오늘의 챔피언' 축하 화면.
학내망 배포 대응 단일 파일·통신 0이니 전자칠판 브라우저에 바로 풀스크린으로 띄우면 끝입니다. EMBED_DATA에 안전 규칙 데이터를 심어 완결성을 높입니다. 교사 PC 서버 파일 공유 → 크롬북 학생 단말도 동일 게임.

2. 핵심 아키텍처 해설 — 신호등과 랭킹판

① 게임 루프는 그대로 재활용

update()와 draw()가 번갈아 도는 표준 무대(게임 루프)는 건강 런 게임과 동일합니다. 이번 글에서 바뀌는 것은 두 가지 — 규칙(신호등)아트(등굣길)입니다. '같은 무대에 새 규칙 얹기'가 이 방법의 핵심입니다.

② 신호등 상태 머신: 규칙을 코드로 옮기기

const LIGHTS = ["green", "yellow", "red"];
let lightIndex = 0;

function nextLight() {
  lightIndex = (lightIndex + 1) % 3;
  drawLight(LIGHTS[lightIndex]);
}
setInterval(nextLight, 3000);   // 3초마다 신호 변경

if (LIGHTS[lightIndex] === "red" && runner.onCrosswalk) {
  score -= 100;      // 빨간불 건너기 감점
  sound("siren");    // Web Audio 합성 사이렌
}

신호등은 '정해진 순서로 도는 상태' — 상태 머신(state machine)의 가장 쉬운 예입니다. 교통 안전 수칙이 이 한 덩어리의 코드로 완전히 표현됩니다.

③ 장애물 설계: 등굣길의 위험 요소

const OBSTACLES = [
  { kind: "parkedCar",   w: 60, h: 34 },   // 불법 주정차 차량 (정지)
  { kind: "movingBike",  w: 30, h: 30, speed: 2 }  // 갑자기 나오는 오토바이 (이동)
];

학생들이 우리 등굣길의 위험 요소를 직접 회의에서 정하고 그 목록을 장애물로 만듭니다 — 게임 기획 회의 자체가 안전교육입니다.

④ '저장하지 않는' 랭킹판

const ranks = [];   // 세션 메모리 — 파일을 닫으면 사라짐(저장 0)

function addRank(nick, score) {
  ranks.push({ nick: nick, score: score });
  ranks.sort(function (a, b) { return b.score - a.score; });
  return ranks.slice(0, 5);   // TOP 5만 표시
}

닉네임은 임시로 입력받되 어디에도 저장하지 않습니다. 학내망 원칙(개인정보 수집·저장 0)의 가장 작은 실천이자, 어린이 개인정보 소양 수업의 살아있는 예제입니다.

⑤ 학내망 전략: 전자칠판 상시 플레이존

배경·캐릭터·사운드·규칙이 모두 상수로 심겨 있으니(EMBED_DATA) 파일 하나를 교사 PC 서버에 올리면 전자칠판과 크롬북이 같은 게임을 플레이합니다. 심기 모드(데이터 임베딩)가 무엇인지는 앞의 '📖 한 줄 정의' 박스를 참고하세요.

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

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 답변 — Gemini가 던지는 질문 3가지(위험 요소, 신호 주기, 랭킹 표시)에 답하면 설계가 확정됩니다.
  3. HTML 파일 실행 — 완성 코드를 '등굣길런.html'로 저장 후 전자칠판 브라우저로 열기.

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

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·프레임워크·웹폰트·이미지 파일 없이 단일 HTML 파일로 완성한다. 횡단보도·스쿨존 배경은 순수 CSS, 캐릭터·차량은 캔버스 도트 맵으로 그린다.
2. 안전 수칙 데이터(장애물 2종, 신호등 규칙, 감점 규칙)는 파일 상단 EMBED_DATA 상수로 완전히 심는다(학내망 배포용 외부 호출 0 모드).
3. 사운드는 Web Audio API로 직접 합성한다: 점프 '펑', 신호 전환 '딩', 빨간불 위반 '사이렌', 신기록 '팡파르'. 오디오 파일 사용 금지.
4. 모바일 터치 대응: 화면 탭=점프, 크롬북 스페이스바=점프, 360px 가로 스크롤 금지.
5. 신호등은 녹색→노란색→빨간색으로 3~5초 간격 순환하고, 빨간불 동안 횡단보도 구역에 서 있으면 감점 100점.
6. 랭킹은 닉네임+점수를 세션 메모리(변수)로만 관리한다 — 브라우저 저장(localStorage)·서버 전송 금지(개인정보 수집·저장·전송 0).
7. // TODO, /* 생략 */ 같은 미완성 코드는 절대 넣지 말고 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 장애물은 우리 등굣길의 어떤 위험 요소로 할까요? (불법 주정차 차량 / 오토바이 / 빗물 고인 구간 등 학급 회의 결정)
Q2. 신호등 주기는 몇 초로 할까요? (교실 난이도에 맞춰 3~5초 권장)
Q3. 랭킹 표시는 몇 위까지? (전자칠판 가독성 기준 TOP 5 권장)

🎯 에디터 한줄평

안전교육의 늪은 '외우게 하기'입니다. 이 설계는 빨간불 위 횡단이 감점이 되는 순간, 수칙을 몸으로 기억하게 만듭니다. 게임 기획 회의에서 '우리 등굣길의 위험 요소'를 직접 뽑아 장애물로 만드는 과정은 창체 시간 그 자체가 되고, '닉네임도 저장하지 않는 랭킹판'은 어린이 개인정보 소양의 첫 실천이 됩니다. 전자칠판 상시 플레이존은 일회성 수업이 아니라 학급 문화로 남는다는 점 — 학급 경영 관점에서 가장 현명한 리소스 활용입니다.

📚 기술·교육 참고 링크

  • 교육과정 연계: 창의적 체험활동(안전·교통안전), 실과·정보(절차 지향 프로그래밍), 보건(안전한 생활)과 함께 활용
  • 도로교통공단 교통안전 자료: https://www.kotsa.or.kr/ — 스쿨존·보행 안전 수칙의 공식 자료
  • MDN Web Docs: setInterval — 신호등 주기를 만드는 표준 함수

[교과 연계] 학급 도서관 대출·반납 시스템 - 4단계 개발 절차(기획-DB-API-UI)로 20분 완성



표 만들기가 스키마(schema)가 되는 20분 — 4단계 절차로 만드는 학급 도서관 대출·반납 시스템

📚 5~6학년 실과 SW 단원과 수학 데이터 관리 단원에서, 학생들이 4단계 개발 절차(기획 → DB 설계 → API 구축 → UI 완성)를 따라 학급 도서관 대출·반납 시스템을 만듭니다. 도서 목록의 DB 스키마(schema)를 설계하고, CRUD REST API를 구축한 뒤, H2 콘솔에서 데이터가 실시간으로 오가는 모습을 눈으로 확인하는 — 소프트웨어 엔지니어링의 첫 전체 지도입니다.

'수학 시간의 표 만들기'가 곧 '데이터베이스 설계'가 되는 순간, 학생들은 데이터가 어디에 살고 어떻게 움직이는지 배웁니다. 서버와 DB는 모두 학내망(교사 PC) 안에서만 동작하고, 데이터는 학교 밖으로 한 걸음도 나가지 않습니다.

📖 한 줄 정의

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

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
4단계 절차 ① 기획(대출 규칙 정하기) ② DB 설계(데이터 표의 칸 정하기) ③ API 구축(창고 직원 부르기) ④ UI 완성(화면 붙이기). 각 단계 5분이면 20분 만에 완성됩니다. 제미나이에서 4단계 프롬프트를 순서대로 입력.
DB 스키마 설계 스키마(schema)는 '데이터 표의 칸 설계도'입니다. 도서 표: 번호·제목·대출여부·대출자·반납기한 — 수학 데이터 관리 단원의 표 만들기가 그대로 스키마가 됩니다. CREATE TABLE 문으로 도서 표 만들기.
CRUD REST API CRUD는 생성(Create)·조회(Read)·수정(Update)·삭제(Delete) 네 동작. REST API는 '창고 직원에게 정해진 말로 요청하는 방식'입니다(예: GET /books = 목록 보여줘). 대출(borrow)·반납(return) 엔드포인트(endpoint) 2개로 시작.
H2 콘솔 실시간 확인 H2 콘솔은 DB 내부를 보는 관리자 창입니다. 화면에서 '대출' 버튼을 누르면 콘솔 표의 값이 바로 바뀌는 것을 학생들이 실시간으로 확인합니다 — 데이터의 실체를 눈으로 배우는 시간. 대출 버튼 클릭 → 콘솔의 대출여부 칸 변화 확인.
학내망 정합 설계 서버·DB·화면 모두 교사 PC(학내망) 안. UI는 fetch로 '내부 API'만 부릅니다 — 외부 CDN·API 호출 0, 데이터 외부 전송 0이라 학내망 원칙과 정확히 맞습니다. 지금까지의 심기 모드(데이터 임베딩)는 '데이터가 안 바뀔 때'의 최선, 매일 바뀌는 대출 현황에는 진짜 데이터베이스가 답입니다. UI 파일은 단일 HTML 유지 + localhost API 호출만.

2. 핵심 아키텍처 해설 — 4단계가 하나로 이어지는 흐름

① 1단계 기획: 규칙이 곧 요구사항(requirement)

  • 한 사람은 책 2권까지만 대출
  • 대출 기간은 7일, 반납일은 자동 계산
  • 대출 중인 책은 목록에서 '대출 중' 표시

'무엇을 만들지'를 문장 3개로 정하는 것 — 이 문장들이 다음 단계의 설계도가 됩니다.

② 2단계 DB 설계: 수학의 표 만들기가 스키마가 된다

CREATE TABLE BOOK (
  ID      INT PRIMARY KEY AUTO_INCREMENT,
  TITLE   VARCHAR(100),
  BORROWED BOOLEAN DEFAULT FALSE,
  BORROWER VARCHAR(20),
  DUE_DATE DATE
);

BORROWER 칸은 닉네임만 쓰고, 인메모리 DB라 서버를 끄면 표가 통째로 사라집니다 — 대출 기록을 영구 보관하지 않는 설계로 개인정보 관리 리스크를 낮춥니다. 학급 대출 장부의 공식 기록은 아날로그 대장과 병행합니다.

③ 3단계 API 구축: 창고 직원의 4가지 말

GET  /books        — 도서 목록 보여줘      (Read)
POST /books/1/borrow — 1번 책 대출 처리해줘 (Create/Update)
POST /books/1/return — 1번 책 반납 처리해줘 (Update)
DELETE /books/1    — 1번 책 목록에서 빼줘   (Delete)

④ 4단계 UI 완성: 단일 HTML 화면 + 내부 API 호출

async function borrow(id) {
  await fetch("/books/" + id + "/borrow", { method: "POST" });
  loadBooks();   // 목록 다시 불러오기
}

⑤ H2 콘솔 확인: 데이터의 실체를 눈으로

화면의 '대출' 버튼 → API → DB 순서로 움직입니다. H2 콘솔에서 SELECT * FROM BOOK을 실행해 두면, 버튼을 누를 때마다 표의 값이 바뀌는 것을 실시간으로 볼 수 있습니다. 'UI-백엔드-데이터베이스'의 3층 구조가 이 한 장의 표에서 완성됩니다.

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

  1. 1단계 프롬프트 입력 — 제미나이에 기획 프롬프트를 넣어 요구사항과 스키마 초안을 받습니다.
  2. 2·3단계 프롬프트 입력 — DB 생성 코드와 CRUD REST API 코드를 받아 실행하고, H2 콘솔에서 데이터 입출력을 확인합니다.
  3. 4단계 프롬프트 입력 — 단일 HTML UI를 받아 브라우저에서 대출·반납을 시험합니다. 총 20분.

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

[1단계 — 기획]
우리 학급 도서관 대출·반납 시스템의 요구사항을 정리해줘.
[🚨 에러 방지 안전장치]
- 대출 규칙(1인 2권, 7일 반납)을 표로 정리한다.
- BORROWER 칸은 실명이 아닌 닉네임만 사용한다(개인정보 최소 수집).
- 구현 환경은 교사 PC 학내망 내부로 한정하고 외부 통신을 포함하지 않는다.

[2단계 — DB 설계]
위 요구사항에 맞는 H2 데이터베이스 스키마(CREATE TABLE)와 초기 도서 10권 입력 SQL을 만들어줘.
[🚨 에러 방지 안전장치]
- 데이터베이스는 H2 인메모리(in-memory) 모드로 설정한다(서버 종료 시 데이터 소멸 — 영구 보관 없음).
- 반납기한(DUE_DATE)은 대출일 + 7일로 자동 계산한다.

[3단계 — API 구축]
CRUD REST API를 만들어줘: 목록 조회(GET /books), 대출 처리(POST /books/{id}/borrow), 반납 처리(POST /books/{id}/return), 삭제(DELETE /books/{id}).
[🚨 에러 방지 안전장치]
- 이미 대출 중인 책을 다시 대출하려 하면 409 충돌 응답과 안내 메시지를 돌려준다.
- 요청 처리 결과를 H2 콘솔에서 확인할 수 있도록 SQL 로그를 남긴다.

[4단계 — UI 완성]
단일 HTML 파일로 대출·반납 화면을 만들어줘.
[🚨 에러 방지 안전장치]
- 외부 CDN·웹폰트·라이브러리 없이 순수 HTML·CSS·JS로만 작성한다.
- fetch는 교사 PC의 localhost 내부 API만 호출한다(외부 통신 0).
- 사운드는 Web Audio API로 합성(대출 성공 '똑', 중복 대출 '삑').
- 모바일·태블릿 터치 대응(버튼 44px 이상, 가로 스크롤 금지).
- // TODO, /* 생략 */ 금지.

[❓ 역질문 유도]
1단계에서 코드를 바로 만들지 말고 아래 3가지를 먼저 질문한다.
Q1. 대출 규칙은 무엇으로 할까? (권수·기간·연장 규칙)
Q2. 도서 데이터는 어디에 둘까? (초기 10권 목록 / 학생이 직접 입력)
Q3. 화면에는 무엇을 보여줄까? (전체 목록 / 대출 중만 / 반납 예정순)

🎯 에디터 한줄평

이 글의 진짜 커리큘럼은 20분이 아니라 '4단계의 순서'입니다. 기획 없이 만들면 곧 흩어지고, 스키마 없이 만들면 데이터가 흩어지고, API 없이 만들면 화면과 데이터가 흩어집니다. '수학 표 만들기 → 스키마'라는 연결은 데이터 문해력의 가장 자연스러운 교량입니다. 그리고 H2 콘솔 앞에서 학생들이 '버튼 하나가 데이터 표를 바꾼다'를 목격하는 순간, 백엔드는 더 이상 보이지 않는 마법이 아닙니다.

📚 기술·교육 참고 링크

  • H2 Database 공식 사이트 : 경량 DB 실행·콘솔 사용법
  • MDN fetch : UI에서 내부 API를 부르는 방법
  • 교육과정 연계: 실과·정보(SW 개발 절차), 수학(데이터 관리·표), 국어(요구사항 문장화)와 함께 활용

[행정/연구] 학교 표준 UI 디자인 시스템 - 토큰으로 교무 웹앱 일괄 표준화



우리 학교 웹앱이 한 브랜드처럼 보이는 법 — 학교 표준 UI 디자인 시스템 & 토큰 표준화

🎨 시설물 예약, 방과후 신청, 설문 조사 — 교무실에서 만드는 교내 웹 도구가 앱마다 색·폰트·버튼이 제각각이라면? 디자인 토큰(design token)(색·폰트·간격·버튼 규격의 이름표)으로 학교 표준을 정하고, 피그마(Figma)에서 시스템으로 구축한 뒤, 모든 교무 웹앱 파일 상단에 같은 토큰 CSS를 심는 심기 모드로 일원화합니다.

AI 코딩 도구와 MCP(모델 컨텍스트 프로토콜 — AI와 도구·문서를 잇는 연결 규약)에 토큰 규칙을 함께 제공하면, 새 앱도 처음부터 표준대로 태어납니다. 학생·학부모가 어느 도구를 열어도 같은 감각 — 브랜드 신뢰의 기술.

📖 한 줄 정의

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

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
해결 문제 교내 웹 도구마다 디자인이 다르면 사용자가 매번 적응해야 합니다 — 파편화(fragmentation)가 UX 부담이자 브랜드 혼란의 원인. 기존 도구 3개의 버튼 스크린샷 나란히 놓고 비교.
디자인 토큰 색·폰트·간격·버튼 규격에 이름표를 붙인 최소 단위 — --school-color처럼. 이름표가 곧 학교의 디자인 맞춤법. 토큰 5종(컬러 3·폰트 1·버튼 규격 1) 정하기.
피그마 시스템 피그마의 스타일 가이드 페이지에 컬러·폰트·버튼 컴포넌트를 정리 — 교무실 안에서 눈으로 공유되는 표준. 무료 커뮤니티 가이드 양식으로 시작.
토큰 CSS 심기 표준 토큰 20줄을 각 웹앱 파일 상단 :root에 심는 심기 모드 — 외부 CDN 없이 모든 도구가 같은 토큰을 씁니다. 토큰 CSS를 3개 기존 앱에 붙여넣기.
AI·MCP 적용 AI 코딩 도구에 '토큰 파일의 변수만 사용' 규칙을 함께 제공(AI Rules의 확장) — 새 앱도 처음부터 표준대로. 프롬프트 안전장치에 토큰 문구 한 줄.

2. 핵심 아키텍처 해설 — 토큰이 맞춤법이다

① 토큰 정의: :root 변수

:root {
  --school-color: #1e5aa8;    /* 학교 대표 색 — 교화·상징색으로 교체 */
  --school-accent: #f4b400;   /* 강조 색 — 알림·포인트 */
  --school-font: "맑은 고딕", sans-serif;
  --btn-radius: 8px;
  --btn-padding: 12px 20px;
}

② 버튼 표준: 토큰만 참조

.btn {
  background: var(--school-color);
  color: #fff;
  font-family: var(--school-font);
  border-radius: var(--btn-radius);
  padding: var(--btn-padding);
}

앱마다 직접 색상 코드를 쓰지 않고 토큰 이름만 씁니다 — 학교 색이 바뀌면 토큰 파일 한 곳만 고치면 됩니다.

③ 피그마(Figma) 워크플로

  • 스타일 가이드 페이지: 컬러 3종(대표·강조·배경), 폰트 2종(제목·본문), 버튼 규격(기본·눌림)을 한 페이지로.
  • 컴포넌트: 버튼·입력칸·카드를 컴포넌트로 등록 — 교무실 누구나 화면에서 표준을 확인.
  • 무료 시작: 커뮤니티의 무료 UI 킷 양식을 학교색으로 바꾸는 것부터.

④ AI·MCP 적용: 규칙을 함께 제공한다

MCP(모델 컨텍스트 프로토콜)는 AI와 도구·문서를 잇는 연결 규약입니다. 교무실 실무 기준은 단순합니다 — AI 코딩 도구의 규칙 파일(AI Rules)에 토큰 파일을 함께 제공하고 프롬프트에 다음 한 줄을 심는 것.

6. 색상·폰트·버튼 스타일은 반드시 토큰 파일(school_tokens.css)의 변수만 참조한다.
   임의의 새 색상 코드·폰트를 직접 쓰지 않는다.

⑤ 배포 루틴: 교무실 표준 절차 3단계

  1. 심기: 표준 토큰 CSS 20줄을 신규·기존 웹앱 상단에 붙여넣는다(외부 CDN 없음 — 학내망 원칙 정합).
  2. 점검: 각 앱에서 버튼·제목·배경이 토큰대로 나오는지 눈으로 확인.
  3. 갱신: 학교 브랜드가 바뀌면 토큰 파일을 고치고 전 앱에 재심기 — 1년 1회 정도의 리듬.

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

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 Gemini에 붙여넣습니다.
  2. 역질문 답변 — 학교 상징색, 도구 종류, 화면 톤에 답합니다.
  3. 표준 배포 — 만들어진 앱에 토큰 CSS를 심고 기존 앱에도 순서대로 적용.

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

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·프레임워크·웹폰트·외부 CDN 없이 단일 HTML 파일로 완성한다(학내망 원칙).
2. 파일 상단에 school_tokens 토큰 블록(:root 변수 5종 이상)을 반드시 포함한다.
3. 모든 색상·폰트·버튼 스타일은 토큰 변수만 참조한다 — 새 색상 코드 직접 입력 금지.
4. 모바일 터치 대응: 뷰포트 메타 태그, 버튼 최소 44×44px, 360px 화면 가로 스크롤 금지.
5. 알림·완료 피드백은 Web Audio API로 직접 합성한다(오디오 파일·CDN 사운드 금지).
6. 교사·학생 실명·학교명을 코드나 화면에 노출하지 않는다(가명·일반명사).
7. // TODO, /* 생략 */ 금지 — 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 어떤 교무 도구인가? (시설물 예약 / 방과후 신청 / 설문 조사 등)
Q2. 학교 상징색은? (교화·로고 색 — 토큰의 뼈대)
Q3. 화면 톤은? (심플 목록 / 카드 격자)

🎯 에디터 한줄평

'앱마다 다른 버튼'이 '우리 학교 서명'처럼 보이는 순간 — 토큰은 디자인의 맞춤법입니다. 학생·학부모가 어느 도구를 열어도 같은 감각을 느끼는 것이 신뢰이고, 그 신뢰는 색상 코드 5개의 이름표에서 시작합니다. 심기 모드가 데이터에서 디자인까지 확장되는 설계입니다.

📚 기술·교육 참고 링크

  • 피그마(Figma) : 실측으로 정상 응답 확인(2026-09-05) — 무료 플랜으로 시작
  • MDN CSS 사용자 정의 변수 : 토큰의 표준 기술
  • 행정·교육 연계: 교내 디지털 서비스 표준화, 정보 소양(디자인 시스템 개념)과 함께 활용

[행정/연구] 교구 대여 관리 시스템 - REST API CRUD로 교육 기자재 대여 전산화



수기 대장을 은퇴시키는 교구 대여 관리 시스템 — REST API로 중복 대여 원천 차단

🖨️ 3D 프린터, 드론, VR 기기 등 고가 교구의 대여·반납 일정을 4단계 절차(기획 → DB → API → UI)로 설계된 경량 CRUD 시스템으로 전산화합니다. 서버 재료는 스프링부트(Spring Boot) 또는 파이썬(Python) 경량 서버 중 선택 — 중복 대여는 상태(status) 칸과 409 충돌 응답으로 원천 차단하고, 분실 애매함은 대출 이력으로 투명하게 남깁니다.

관리자 웹 인터페이스에서 대여 현황이 실시간으로 갱신됩니다. 서버·DB는 모두 교내(학내망) 안에서만 동작하고, 대출자 칸은 부서·닉네임만 쓰며, 데이터가 학교 밖으로 전송되는 구조는 없습니다.

📖 한 줄 정의

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

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
해결 문제 수기 대장의 3대 리스크 — ① 중복 대여(이미 나간 교구를 또 빌려줌) ② 분실 시 책임 애매(기록 불완전) ③ 현황 불명(지금 어디에 있는지 모름). 상태 관리 전산화로 세 가지가 한 번에 해결됩니다. STATUS 칸 하나로 시작하기.
4단계 절차 재활용 4단계(기획→DB→API→UI) 절차를 그대로 씁니다. 규칙만 바꾸면 도구가 달라지는 — 절차의 재사용성이 이 설계의 핵심 교훈입니다. 요구사항 3줄(대여 규칙)부터 쓰기.
중복 대여 원천 차단 AVAILABLE(대여 가능)·LOANED(대여 중) 상태를 먼저 확인하고, 대여 중이면 409 충돌 응답으로 거절합니다. 사람의 주의가 아니라 시스템이 실수를 막습니다. GET /equipments/available 만들어보기.
서버 재료 선택 스프링부트(Spring Boot) — 표준적·견실한 Java 서버. 파이썬(Python) Flask — 적은 코드로 빠르게 만드는 경량 서버. 초등 교내용은 어느 쪽이든 4단계 절차가 동일하니 익숙한 재료를 고릅니다. 한 가지를 골라 3단계 API 코드 요청.
백업·정합성 인메모리·경량 DB를 쓰더라도 하루 한 번 CSV 내보내기로 대여 이력을 백업합니다. '기술 도구가 대장을 대체'가 아니라 '도구가 대장을 보조'하는 운영 원칙입니다. 퇴근 전 CSV 백업 1회 루틴.

2. 핵심 아키텍처 해설 — 교구 관리의 5개 층

① 1단계 기획: 대여 규칙 3줄

  • 최대 대여 기간 5일 (반납 예정일 자동 계산)
  • 동시 대여는 교구당 1팀
  • 반납 시 상태 점검 후 AVAILABLE로 전환

② 2단계 DB 설계: 교구 표의 칸

CREATE TABLE EQUIPMENT (
  ID     INT PRIMARY KEY,
  NAME   VARCHAR(50),    -- 3D 프린터-1, 드론-A 등
  STATUS VARCHAR(10),    -- AVAILABLE / LOANED
  DEPT   VARCHAR(20),    -- 대여 부서·닉네임 (실명 최소 수집)
  DUE    DATE            -- 반납 예정일
);

③ 3단계 CRUD REST API

GET  /equipments/available   — 대여 가능 목록 (Read)
POST /equipments/{id}/loan   — 대여 처리 (중복 체크)
POST /equipments/{id}/return — 반납 처리
GET  /equipments/overdue     — 연체 목록 (Read)

④ 중복 대여 차단 로직: 상태가 지키는 규칙

function loan(id) {
  const e = findEquipment(id);
  if (e.STATUS === "LOANED") {
    return { status: 409, message: "이미 대여 중인 교구입니다" };
  }
  e.STATUS = "LOANED";
  e.DUE = addDays(today(), 5);
  save(e);
  return { status: 200 };
}

⑤ 파이썬(Python) Flask 슬림 예시

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/equipments/available")
def available():
    rows = [e for e in EQUIPMENTS if e["STATUS"] == "AVAILABLE"]
    return jsonify(rows)

하루 한 번 CSV 내보내기를 붙이면 대여 이력 백업이 완성됩니다 — 인메모리·경량 DB의 안전장치입니다.

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

  1. 1·2단계 프롬프트 — 대여 규칙 정리 + 스키마 설계 코드를 받아 요구사항을 확정합니다.
  2. 3단계 프롬프트 — CRUD REST API 코드를 받아 교내 서버에서 실행하고, 중복 대여 거절(409)을 직접 시험합니다.
  3. 4단계 프롬프트 — 관리자 대시보드(단일 HTML)를 받아 교내망 브라우저에서 대여·반납을 운영합니다.

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

[🚨 에러 방지 기본 안전장치]
1. 4단계(기획-DB-API-UI) 순서를 지켜 답변하되, 최종 결과물은 교내 서버 + 단일 HTML 관리 화면으로 완성한다.
2. 데이터베이스는 경량(H2 인메모리 또는 파이썬 메모리 구조)으로 하되, 하루 한 번 CSV 내보내기 기능을 포함한다.
3. 대여 중인 교구에 대한 대여 요청은 409 충돌 응답과 한국어 안내 메시지로 거절한다(중복 대여 원천 차단).
4. 대여자 칸은 부서·닉네임만 허용한다 — 실명 칸을 만들지 않는다(개인정보 최소 수집).
5. UI의 fetch는 교내 localhost 내부 API만 호출한다 — 외부 CDN·API·전송 0.
6. 대여·반납 완료 시 Web Audio 알림음('똑'), 중복 대여 거절 시 '삑'을 합성한다.
7. 반납 예정일(DUE)은 대여일 + 5일로 자동 계산하고, 연체 목록 화면을 별도로 제공한다.
8. // TODO, /* 생략 */ 같은 미완성 코드는 절대 넣지 말고 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 서버 재료는 무엇으로 할까? (스프링부트 / 파이썬 Flask)
Q2. 대여 규칙은 무엇으로 할까? (기간·팀 수·연장 규칙)
Q3. 관리 화면의 첫 화면은 무엇으로 할까? (대여 가능 목록 / 연체 목록 / 전체 현황)

🎯 에디터 한줄평

'누가 가져갔지?'라는 한숨이 API 쿼리 한 줄로 바뀌는 것 — 관리 투명성은 결국 신뢰의 기술입니다. 409 충돌 응답 하나로 '잊고 또 빌려주는 실수'가 구조적으로 사라지고, 반납 예정일 자동 계산이 독촉의 마찰을 줄입니다. 4단계 절차를 행정에 그대로 쓸 수 있다는 점은 '절차의 재사용'이 작동한다는 증거입니다. 고가 교구는 아이들의 희망이자 학교의 재산 — 데이터가 그 둘을 함께 지켜줍니다.

📚 기술·교육 참고 링크

  • Spring Boot 공식 사이트 : Java 경량 백엔드 표준
  • Flask 공식 문서 : 파이썬 경량 서버 프레임워크
  • H2 Database : 교탁 PC 도구용 경량 DB
  • 활용 팁: 과학실·도서실·체육창고의 관리 규칙만 바꾸면 같은 4단계로 또 하나의 도구가 완성됩니다

[학급 경영] AI Rules 기반 독서록 취합 봇 - 파일 정렬·병합·미제출 명단 1초 완성



30개 독서록 파일이 1초에 하나로 — AI Rules 기반 파이썬 취합 봇 완전 정복

📚 학급 드라이브에 모인 개별 독서록·일기장 텍스트 파일을 파이썬 봇이 1초 만에 학생 번호순으로 정렬·병합하고, 미제출자 명단까지 자동 추출합니다. 교탁 PC에서 배치 파일(batch file) 더블클릭 한 번으로 끝납니다.

비결은 AI Rules(에이전트 규칙 파일) — 파일명 규칙·출력 서식·원칙을 규칙 문서에 심어두면, AI로 코드를 고칠 때마다 같은 규칙을 지킵니다. 규칙의 재현성(reproducibility)입니다. 독서록은 학생 저작물이므로, 취합은 교탁 PC에서 로컬로만 처리하고 외부 전송은 0입니다.

📖 한 줄 정의

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

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
운영 시나리오 금요일 독서록 취합 10~30분 수작업 → 더블클릭 1초. 남은 시간은 학생 피드백에 씁니다. 배치 파일 더블클릭 → 취합 파일 열기.
AI Rules 규칙판 파일명 규칙(예: 03_김이레_독서록.txt)·출력 서식·원칙을 규칙 문서 5줄로 정리. AI에게 함께 제공하면 수정할 때마다 규칙을 지킵니다. 규칙 5줄을 학급 회의에서 확정.
번호 추출 정규식(regular expression)으로 파일명 앞 두 자리를 번호로 읽어 정렬합니다 — 이름 오탈자와 무관하게 번호로 묶습니다. 정규식 한 줄로 30개 파일 분류.
병합·미제출 명단 1~30번 중 파일이 없는 번호를 '미제출'로 자동 추출 — 점검이 문답이 아닌 목록으로 끝납니다. '미제출: 07, 19' 한 줄 확인.
원칙·안전 로컬 처리 전용(읽기·합치기·저장), 외부 전송 0. 학생 저작물은 교사 피드백용으로만. 규칙 문서에 원칙 한 줄 상시 기록.

2. 핵심 아키텍처 해설 — 규칙판이 먼저, 코드는 나중에

① AI Rules 규칙 파일 양식

# AI Rules — 우리 반 독서록 취합 봇
1. 파일명 규칙: 번호 2자리_이름_독서록.txt (예: 03_김이레_독서록.txt)
2. 출력: 취합_독서록_YYYY-MM-DD.txt, 첫 줄에 날짜·총 인원·미제출 수
3. 미제출자는 마지막에 '미제출: 번호, 번호' 목록으로 붙인다
4. 원칙: 이 봇은 파일을 읽고 합칠 뿐 — 외부로 전송하지 않는다
5. AI와 함께 수정할 때는 이 규칙 파일을 먼저 제공한다

이 규칙 파일은 두 가지 역할을 합니다: 학생·교사에게는 약속 문서, AI에게는 설계 명세. AI Rules의 본질은 '규칙을 글로 남겨 코드와 함께 두는 것'입니다.

② 번호 추출: 정규식(regular expression)

import os, re, glob

pattern = re.compile(r"^(\d{2})_")   # 파일명 앞의 두 자리 번호
records = {}
for path in glob.glob("독서록/*.txt"):
    m = pattern.match(os.path.basename(path))
    if m:
        records[int(m.group(1))] = path

③ 병합과 미제출 명단

missing = []
merged_lines = ["취합 일시: " + today, "총 인원: 30"]
for n in range(1, 31):
    if n in records:
        merged_lines.append("=== " + str(n) + "번 ===")
        merged_lines.append(open(records[n], encoding="utf-8").read())
    else:
        missing.append(n)

merged_lines.append("미제출: " + (", ".join(str(n) for n in missing) or "없음"))

파일명 규칙이 지켜지지 않은 파일은 '규칙 불일치' 경고 목록에 담아 알려줍니다 — 조용히 건너뛰지 않습니다.

④ 배치 파일(batch file): 더블클릭 실행

@echo off
python 취합봇.py
pause

메모장에 3줄을 저장하고 취합봇.bat로 저장하면, 교탁 PC에서 더블클릭 한 번이 됩니다.

⑤ 운영 원칙

  • 로컬 전용: 파일을 읽고 합치고 저장 — 외부 전송 0(학내망 원칙 정합).
  • 파일명 규칙 교육: 규칙을 학급 회의에서 정하고 학생과 약속 — 학급자치와 자연 연결.
  • 규칙 갱신: 출력 서식을 바꾸려면 규칙 파일을 먼저 고친다 — 코드는 규칙을 따른다.

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

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 Gemini에 붙여넣습니다.
  2. 역질문 답변 — 인원수, 파일명 규칙, 출력 서식 세 질문에 답합니다.
  3. 배치 실행 — 규칙 파일과 봇 코드, 배치 파일을 받아 교탁 PC에서 더블클릭.

제미나이 전용 에러 제로 프롬프트 (파이썬판)

[🚨 에러 방지 기본 안전장치]
1. 표준 라이브러리만 사용한다(os, re, glob, datetime) — pip 설치가 필요한 것은 없다.
2. 모든 파일은 encoding="utf-8"으로 읽고 쓴다(한글 깨짐 방지).
3. 파일명 규칙에 맞지 않는 파일은 건너뛰지 말고 '규칙 불일치' 경고 목록에 담아 마지막에 보여준다.
4. AI Rules 규칙 파일(rules.txt)까지 함께 생성해 준다 — 코드는 규칙을 따라 쓴다.
5. 결과 파일이 이미 존재하면 날짜를 붙여 새 파일로 저장한다(덮어쓰기 금지).
6. 이 봇은 외부로 데이터를 전송하는 기능을 만들지 않는다(학내망 원칙).
7. // TODO, pass 등 미완성 코드 금지 — 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 총 인원은 몇 명으로 볼까? (미제출 판정 기준)
Q2. 파일명 규칙은 어떻게 할까? (번호 2자리_이름_독서록.txt 기본)
Q3. 출력 서식은? (첫 줄 날짜·총 인원·미제출 수 + 번호별 구분선)

🎯 에디터 한줄평

'취합 시간'이 '피드백 시간'으로 — 교사의 1시간이 아이들에게 그대로 돌아갑니다. 규칙을 문서로 심는 AI Rules는 '약속을 글로 남기는 것'의 기술 버전입니다. 파일명 규칙을 학급 회의에서 정하는 것부터 자치이고, '규칙 불일치' 목록을 조용히 넘기지 않는 설계가 교육적 신뢰를 만듭니다.

📚 기술·교육 참고 링크

[교과 연계] 교과서 PDF → Blooket 퀴즈 배틀 - 산과 염기·정치 발전 복습 & 메타인지 오답 정복



교과서 정리 PDF가 배틀 게임이 되는 1분 — Blooket 퀴즈 배틀 & 메타인지 오답 정복 완전 정복

⚔️ 단원 학습이 끝난 교과서 단원 정리 PDF를 제미나이 프롬프트에 넣으면 문제은행이 나오고, 그 서식(엑셀·CSV)을 Blooket에 올리면 타워 디펜스 퀴즈 배틀이 1분 만에 시작됩니다. 과학 '산과 염기', 사회 '우리나라의 정치 발전' 단원 복습 수업이 경기장처럼 바뀝니다.

배틀의 잔해(틀린 문제)가 다시 학습지가 됩니다 — 오답만 모아 오답 정복 학습지로 만들어 인쇄하면, '나는 무엇을 모르는가'를 스스로 찾는 메타인지(meta-cognition — 자기 사고를 알아보는 능력) 수업이 완성됩니다. 학생은 닉네임으로 참가하고, 오답 데이터는 로컬 문서·종이로 정리합니다.

📖 한 줄 정의

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

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
수업 워크플로 단원 마무리 → 정리 PDF 텍스트 복사 → 제미나이 문제은행 생성 → Blooket 서식 붙여넣기 → 학급 대항전 → 오답 정복 학습지. 6단계가 1차시 안에 답긴다. 오늘 수업에 바로 적용 — 워크플로 4단 순서표.
PDF → 문제은행 PDF 텍스트를 제미나이에 넣고 서식 프롬프트로 객관식 15문항 생성. 보기 균형과 정답 배분은 프롬프트 규칙이 검증한다. 아래 제미나이 전용 프롬프트 복사 → 텍스트 붙여넣기.
Blooket 서식 CSV 여섯 칸 — question, answer1, answer2, answer3, answer4, correctAnswerNum(공식 템플릿 기준). 문제은행을 이 열 구조에 맞춰 붙여넣고 업로드하면 타워 디펜스 모드로 학급 대항전 시작. 문제은행 CSV → Blooket 문제집 만들기 → 업로드 → 게임 코드 공유.
메타인지 오답 정복 배틀 결과 화면에서 틀린 문항만 추려 '오답 카드'로 — 문제·내 답·정답·한 줄 정리 네 칸으로 구성하고 짝·모둠 토크로 원인을 말로 풀어낸 뒤 형성평가 학습지로 인쇄합니다. 오답 목록 → 오답 카드 프롬프트 → 학습지 HTML 생성 → 인쇄.
원칙·정합 학생 참가는 닉네임만(이름 저장 0), 오답 데이터는 로컬 문서·종이로 정리 — 외부 플랫폼에 학생 개인정보를 두지 않는 반 규칙. 외부 플랫폼 사용은 학교·교육청 정책 기준을 따릅니다. 반 규칙 3줄(닉네임 / 로컬 정리 / 정책 확인) — 학급 회의에서 확정.

2. 핵심 아키텍처 해설 — 배틀은 어떻게 만들어지나

① 워크플로 4단 해설

1단 정리(PDF 텍스트 확보) → 2단 제미나이 문제은행 → 3단 Blooket 서식 변환·업로드 → 4단 배틀·오답 정복. 각 단의 산출물이 다음 단의 입력이 되는 파이프라인입니다 — 코드 한 줄 없이도 '데이터가 서식을 따라 흐른다'는 엔지니어링 감각을 몸으로 배웁니다.

② 제미나이 문제은행 프롬프트

[역할] 너는 초등 5~6학년 문제 출제 전문가다.
[입력] 아래는 교과서 단원 정리(PDF에서 복사한 텍스트)다.
[요구] 같은 내용으로 객관식 15문항을 만들어 아래 서식으로 출력한다:
문제,보기1,보기2,보기3,보기4,정답번호
[규칙]
1. 보기 4개의 난이도가 비슷해야 하고, '모두/모두 아니다' 같은 보기는 금지한다.
2. 산·염기는 실험 결과와 원인을 함께 묻고, 정치 발전은 변화의 순서를 묻는다.
3. 문항 간 중복이 없어야 하고, 정답번호는 1~4 중 하나다.
4. // TODO, /* 생략 */ 금지 — 끝까지 완성한다.

③ Blooket 서식 이해

Blooket은 문제집(question set)을 CSV 파일로 일괄 등록할 수 있습니다. 공식 템플릿의 열은 여섯 칸 — question(문제), answer1~answer4(보기), correctAnswerNum(정답 번호). 제미나이가 내준 '문제,보기1,보기2,보기3,보기4,정답번호' 서식과 열 순서가 정확히 같으므로, 엑셀에 붙여넣어 CSV로 저장하면 바로 업로드됩니다. 쉼표가 문장 안에 들어가면 셀이 흩어지므로, 문항 문장에서 쉼표는 ·(가운뎃점)로 바꿔 저장하는 것이 안전합니다.

④ 오답 정복 루틴

배틀이 끝나면 결과 화면의 틀린 문항 목록을 확보합니다. 여기서 두 번째 제미나이 프롬프트가 등장합니다 — 틀린 문항을 '오답 카드'로 재구성하는 것입니다. 오답 카드는 네 칸: 문제·내 답·정답·한 줄 정리. 학생이 '한 줄 정리' 칸을 직접 채우는 것이 메타인지의 핵심 동작입니다.

⑤ 원칙·정합

  • 닉네임 참가 — 게임룸 입장은 닉네임만. 실명·학번은 외부 플랫폼에 두지 않습니다(이름 저장 0).
  • 오답 데이터는 로컬 — 틀린 문항 정리는 교사 PC 문서·종이 학습지로. 외부 서비스에 학생별 기록을 영구 보관하지 않습니다.
  • 정책 확인 — 외부 플랫폼 사용은 학교·교육청 정책 기준을 따릅니다.

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

  1. 프롬프트 복사 — 아래 제미나이 전용 에러 제로 프롬프트를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 답변 — Gemini가 묻는 문항 수·난이도·단원 범위에 답합니다.
  3. 서식 변환·배틀 — 나온 표를 엑셀에 붙여넣어 CSV 저장 → Blooket 문제집 업로드 → 게임 코드로 학급 대항전.

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

[🚨 에러 방지 기본 안전장치]
1. 산출물은 표 형태(문제,보기1,보기2,보기3,보기4,정답번호)로만 출력한다 — HTML 코드가 아니라 문제은행 데이터다.
2. 문장 안의 쉼표는 가운뎃점(·)으로 바꾸어 CSV 셀이 흩어지지 않게 한다.
3. 정답번호는 반드시 1~4 사이의 숫자 하나다. 보기 안에 정답이 중복되거나 비어 있으면 안 된다.
4. 문항은 단원 정리 내용 안에 근거가 있는 것만 — 교과서에 없는 지식을 갖다 붙이지 않는다.
5. 오답 카드 모드가 요청되면 문제·내 답(빈칸)·정답·한 줄 정리(빈칸) 네 칸 표로 출력한다.
6. // TODO, /* 생략 */ 금지 — 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 문항 수와 난이도는? (기본: 15문항, 보기 4개)
Q2. 오답 카드 학습지 모드도 지금 함께 만들까? (기본: 함께)
Q3. 학습지 인쇄용 HTML이 필요하면 같이 줄까? (기본: 준다 — 단일 HTML, 인쇄 CSS 포함)

🎯 에디터 한줄평

'복습 시간'이 '배틀 시간'이 되고, 배틀의 잔해(틀린 문제)가 다시 학습지로 돌아옵니다 — 경쟁과 성찰의 순환이 곧 메타인지입니다. 이 워크플로의 진짜 미덕은 문제은행의 재사용성입니다. 한 번 만든 서식은 다음 학기에도 그대로 살아 있고, 오답 카드는 학생마다 다르게 열리는 개인 정복 지도가 됩니다. '오답이 사라져야 수업이 끝난다'는 문화가 반에 자리 잡히면, 배틀은 놀이가 아니라 진단이 됩니다.

📚 기술·교육 참고 링크

  • Blooket 공식 사이트 — 퀴즈 배틀 플랫폼(이 글 검증 시점 브라우저 접속 200 OK 실측)
  • 에이스 퀴즈 랩 등 국내 퀴즈 도구 — 도구명으로 검색해 공식 사이트에서 최신 주소와 엑셀 서식을 반드시 확인하세요(이 글 검증 시점에는 주소를 확인하지 못했습니다 — 정확한 도구명으로 직접 확인이 안전합니다).
  • 교육과정 연계: 과학(산과 염기 — 실험 결과·원인 문항), 사회(우리나라의 정치 발전 — 변화 순서 문항), 실과·정보(문제은행 서식 변환)와 함께 활용

[교과 연계] 우리 고장 역사 탐방 성향 진단 - 한국관광공사 TourAPI 연동 추천 웹앱



우리 고장을 성향 진단처럼 탐방하는 웹앱 — 역사 탐방 성향 진단 & TourAPI 연동 완전 정복

🏛 학생들이 역사 탐방 성향 진단 4대 축(유적지-자연경관, 도보-교통, 체험-관람, 맛집-기념관) 16문항을 직접 설계하면, 가중치(weight) 연산으로 4글자 성향 코드가 나오고 보딩패스(boarding pass) 형태의 결과 카드가 발급됩니다. 여기에 한국관광공사 공공데이터(TourAPI)를 연동하면 성향에 맞는 우리 고장 여행지까지 추천됩니다.

사회(우리 고장의 문화유산)·수학(가중치 연산과 비율)·실과(SW)가 한 화면에서 만나는 융합 수업입니다. 학내망 배포용은 '우리 고장 여행지 심기'로 통신 0 — TourAPI 연동은 교사 PC 시연용 확장(무료 키 발급)으로 설계합니다.

📖 한 줄 정의

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

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
수업 시나리오 사회 '우리 고장의 문화유산' + 실과 SW 단원. 학생이 진단 설계자가 되는 역전 구조 — 문항 16개도 학생 회의에서 만듭니다. 4축 문항표를 모둠별로 설계한 뒤 반 전체 문항 응답.
가중치(weight) 연산 답 하나가 축 양쪽에 +1. 4문항 합산 후 더 높은 쪽이 그 축의 글자 — 4축이 모이면 4글자 성향 코드. 합산 함수로 코드 산출 + 각 축 비율(%)까지 표시.
보딩패스(boarding pass) 카드 항공 티켓처럼 생긴 결과 카드 — 출발지 '우리 반', 도착지 '성향 코드', 좌석 칸에 축별 비율. 점선 분리선 + 큰 글자 코드로 카드 CSS 완성.
TourAPI 연동 한국관광공사 공공데이터 — 무료이지만 serviceKey(개인 인증키) 발급 필수. 구버전 KorService1은 폐기(실측), 현재는 KorService2. 공공데이터포털 가입 → 활용신청 → 키 발급 → areaBasedList2 호출.
학내망 배포 대응 진단·카드·여행지 추천은 전부 심기 모드(데이터 임베딩)로 완결 — 학생 단말은 통신 0. TourAPI fetch는 교사 PC 시연용 확장. 우리 고장 여행지 16곳을 성향 코드별로 EMBED_DATA에 심기.

2. 핵심 아키텍처 해설 — 진단 엔진은 이렇게 생겼다

① 4축 × 4문항 = 16문항 설계

축(axis) 하나가 두 극을 잡고(예: 유적지 vs 자연경관), 축마다 문항 4개를 만듭니다. 문항마다 답은 둘 중 하나 — 어느 쪽에 +1이 들어갈지만 정하면 됩니다. 예시:

  • 축1(유적지 vs 자연경관): "오래된 벽돌 담과 잔디 정원, 어느 쪽 사진이 끌리나?"
  • 축2(도보 vs 교통): "고장 골목은 걸어서 돌아보고 싶나, 자전거로 빠르게 돌고 싶나?"

② 가중치(weight) 연산 코드

const AXIS_META = [
  { a: "유", b: "자", name: "유적지 vs 자연경관" },
  { a: "보", b: "통", name: "도보 vs 교통" },
  { a: "체", b: "관", name: "체험 vs 관람" },
  { a: "맛", b: "기", name: "맛집 vs 기념관" }
];
// QUESTIONS 16개 — 각 문항은 축 번호(axis)와 두 극을 가진다

const tally = [0, 0, 0, 0, 0, 0, 0, 0];   // 4축 x 2극 = 8칸 점수판

QUESTIONS.forEach(function (q, i) {
  tally[q.axis * 2 + ANSWERS[i]] += 1;    // 답한 극에 +1
});

function letterFor(axis) {
  const a = tally[axis * 2];
  const b = tally[axis * 2 + 1];
  return { letter: a >= b ? AXIS_META[axis].a : AXIS_META[axis].b,
           pct: Math.round(a / (a + b) * 100) };
}

const parts = [0, 1, 2, 3].map(letterFor);
const code = parts.map(function (p) { return p.letter; }).join("");
// 예: '유보체맛' — parts[0].pct는 유적지 쪽 비율(예: 75)

③ 보딩패스(boarding pass) 결과 카드

<div class="pass">
  <p class="route">우리 반 ➜ <strong>유보체맛</strong></p>
  <p class="seat">유적지 75% · 도보 50% · 체험 62% · 맛집 100%</p>
</div>

티켓 감성은 CSS로 충분합니다 — 점선 분리선(border-style: dashed), 큰 성향 코드 글자, 하단에 축별 비율 좌석표. 이미지 파일이 하나도 필요 없습니다.

④ TourAPI 연동(교사 PC 시연용 확장 모드)

한국관광공사 공공데이터는 무료이지만 serviceKey 발급이 필수입니다. 절차: 공공데이터포털(data.go.kr) 가입 → '국문 관광정보 서비스' 활용신청 → 인증키 발급(보통 하루 이내).

const SERVICE_KEY = "발급받은_인증키";   // 교사 PC 전용 빌드에만 넣는다

async function loadPlaces() {
  const url = "https://apis.data.go.kr/B551011/KorService2/areaBasedList2"
    + "?numOfRows=5&pageNo=1&MobileOS=ETC&MobileApp=GajaTrip"
    + "&serviceKey=" + encodeURIComponent(SERVICE_KEY);
  const res = await fetch(url);
  const xml = await res.text();            // 응답은 XML
  const doc = new DOMParser().parseFromString(xml, "text/xml");
  const items = doc.getElementsByTagName("item");
  return Array.from(items).map(function (it) {
    return { title: it.getElementsByTagName("title")[0].textContent,
             addr: it.getElementsByTagName("addr1")[0].textContent };
  });
}

오늘 실측으로 잡아낸 함정 두 개: ① 구버전 주소 KorService1은 이미 폐기 — 호출하면 오류 코드 12 '해당 오픈API 서비스가 없거나 폐기됨'이 옵니다. ② 키 없이 KorService2를 호출하면 401·코드 20(SERVICE_KEY_IS_NULL). 오류 코드가 오히려 길잡이라는 좋은 수업 소재입니다. CORS도 실측 완료 — 요청에 Origin 헤더가 있으면(브라우저는 항상 실어 보냄) Access-Control-Allow-Origin을 돌려줍니다.

⑤ 학내망 전략: 우리 고장 여행지 16곳 심기

const EMBED_PLACES = {
  "유보체맛": "우리 고장 옛 성터 산책로",
  "자통관기": "고장 시립 박물관과 옛 우체국",
  // ... 16개 성향 코드별 1곳
};

학생 배포본은 이 상수만으로 추천이 완료되는 외부 통신 0 모드. 16곳 수집은 주말 현장 답사·TourAPI 웹사이트 검색을 활용한 교사의 미니 임무 — 한 번 심으면 갱신이 거의 필요 없습니다.

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

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 답변 — 4대 축 확정, 여행지 모드, 카드 톤 세 질문에 답하면 설계가 고정됩니다.
  3. HTML 파일 실행 — 완성 코드를 '고장탐방진단.html'로 저장 후 더블클릭. 학내망 배포본은 심기 모드 그대로입니다.

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

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·프레임워크·웹폰트 없이 단일 HTML 파일로 완성한다. (TourAPI fetch는 교사 PC 시연용 확장 모드에서만 허용)
2. 진단 로직(4축 16문항), 가중치 연산, 보딩패스 카드, 우리 고장 여행지 16곳(EMBED_PLACES)을 한 파일에 완성한다(학내망 배포용 외부 통신 0).
3. 사운드는 Web Audio API로 직접 합성한다: 문항 넘김 '똑', 성향 코드 발급 '팡파르'. 오디오 파일·CDN 사운드 금지.
4. 모바일·크롬북 터치 대응: 뷰포트 메타 태그 필수, 답 선택 버튼 최소 44×44px, 16문항 진행바 표시.
5. 도구명은 '성향 진단'으로 쓴다 — MBTI는 상표이므로 도구 이름·로고에 사용 금지(4축·16코드 스타일 참고만).
6. SERVICE_KEY 상수는 교사 PC 전용 빌드에만 넣고, 학생 배포 파일에는 fetch 모드 자체를 제거한다.
7. // TODO, /* 생략 */ 같은 미완성 코드는 절대 넣지 말고 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 4대 축은 무엇으로 확정할까? (기본: 유적지-자연경관 / 도보-교통 / 체험-관람 / 맛집-기념관)
Q2. 여행지 데이터는 어느 모드로 할까? (A: 우리 고장 16곳 심기 모드 / B: TourAPI 키 발급 후 실시간 모드)
Q3. 보딩패스 카드 톤은? (항공권 스타일 / 골든 티켓 스타일)

🎯 에디터 한줄평

'우리 고장 문화유산 암기 과제'가 '나에게 맞는 우리 고장 찾기'로 바뀌는 순간, 고장 사랑이 사랑 받아야 할 숙제에서 발견해야 할 재미로 바뀝니다. 가중치 연산은 비율 수업을 몸으로 하는 버전이고, 문항 16개를 학생이 설계한다는 점이 이 수업의 진짜 깊이입니다. 공공데이터는 '나라가 문을 열어준 창고' — 키 한 장 발급이 시민 데이터 소양의 첫걸음입니다. 구버전 폐기를 오류 코드로 잡아낸 실측 절차까지 학생과 함께 공유하세요. 그것이 이 방법의 핵심입니다.

📚 기술·교육 참고 링크

  • 한국관광공사 TourAPI 포털 : 공식 개발자 포털(오늘 실측 정상)
  • 공공데이터포털 : 가입·활용신청·serviceKey 발급 창구
  • 교육과정 연계: 사회(우리 고장의 문화유산), 수학(비율·가중치), 실과·정보(SW 활용)와 함께 활용

[교과 연계] 파이썬 스크래퍼 기상·미세먼지 수집기 - 재현성 있는 일일 자동 수집



우리 고장 하늘을 엑셀에 적는 파이썬 — 기상·미세먼지 일일 자동 수집기 완전 정복

🌤️ 5~6학년 과학 '날씨와 생활', 실과 데이터 단원. 학생들이 먼저 웹 구조 명세서(specification)(어느 페이지·어느 칸·어느 셀렉터)를 작성하고, 파이썬 스크래퍼(scraper)가 기상청·에어코리아의 실시간 데이터를 매일 아침 수집해 엑셀로 누적합니다.

이번 글의 키워드는 재현성(reproducibility) — 명세서가 있으면 누가 실행해도 같은 결과가 나옵니다. 과학의 재현성 개념이 코드로 몸에 붙는 수업입니다. 공개 데이터만 '받아오는' 도구라 학생 개인정보는 다루지 않으며, 교탁 PC(학내망)에서 실행됩니다.

📖 한 줄 정의

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

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
수업 시나리오 1차시 명세서 작성 → 2차시 스크래퍼 제작·실행 → 3차시 엑셀 누적·주간 그래프(수학 통계 연계). 주간 일정표에 3단계를 미리 배치.
웹 구조 명세서 페이지 주소·찾을 칸·셀렉터(selector)·수집 주기를 표로 정리한 지도 문서. 셀렉터는 개발자 도구(F12)에서 직접 확인합니다. 명세서 양식에 '미세먼지' 한 줄을 채워보기.
파이썬 스크래퍼 requests로 페이지를 받고, BeautifulSoup(HTML 문서 파서)로 칸을 골라냅니다. 셀렉터는 코드 안 상수로 — 명세서와 항상 맞춥니다. SELECTORS 상수를 명세서에서 옮겨 적기.
엑셀 누적 openpyxl로 오늘의 기록을 한 줄 추가. 일주일이면 수학 시간 그래프 그리기 재료가 완성됩니다. 엑셀 파일 열어 새 줄 추가 확인.
원칙·안전 공개 데이터 수신만, 외부 전송 0, 학생 개인정보 0. 사이트 구조가 바뀌면? 명세서를 고치고 셀렉터 상수만 교체 — 재현성이 이를 지탱합니다. '확인 필요' 오류 기록 → 명세서 갱신 루틴.

2. 핵심 아키텍처 해설 — 명세서가 지도, 스크래퍼는 배

① 웹 구조 명세서 양식

항목페이지 주소찾을 칸셀렉터(예시)주기
미세먼지airkorea.or.kr오늘 미세먼지 수치#pm10Value하루 1회
초미세먼지같은 페이지오늘 초미세먼지 수치#pm25Value하루 1회

셀렉터는 예시입니다 — 수업 시점에 개발자 도구로 직접 확인해 명세서에 기록하세요. 명세서가 바뀌지 않는 한, 코드는 언제나 같은 결과를 만듭니다(재현성).

② 페이지 받기: requests

import requests

url = "https://www.airkorea.or.kr/"   # 명세서 1행의 페이지 주소(예시)
res = requests.get(url, timeout=10)
res.raise_for_status()   # 실패하면 여기서 멈추고 이유를 알려준다

③ 칸 골라내기: 셀렉터는 상수로

from bs4 import BeautifulSoup

SELECTORS = {
    "미세먼지": "#pm10Value",      # 명세서에서 온 값(예시)
    "초미세먼지": "#pm25Value"     # 수업 시점에 직접 확인해 교체
}

soup = BeautifulSoup(res.text, "html.parser")
values = {}
for name, sel in SELECTORS.items():
    el = soup.select_one(sel)
    values[name] = el.get_text(strip=True) if el else "확인 필요"

칸을 찾지 못해도 프로그램이 죽지 않고 '확인 필요'를 기록합니다 — 조용히 실패하는 자동화가 가장 위험합니다.

④ 엑셀 누적: openpyxl

import openpyxl
from datetime import date

wb = openpyxl.load_workbook("우리고장_기록.xlsx")
ws = wb["기록"]
row = ws.max_row + 1
ws.cell(row=row, column=1, value=str(date.today()))
for i, name in enumerate(SELECTORS):
    ws.cell(row=row, column=2 + i, value=values[name])
wb.save("우리고장_기록.xlsx")

⑤ 재현성과 운영 원칙

  • 명세서 우선: 셀렉터는 항상 명세서에서 코드로 옮긴다 — 코드가 명세서를 바꾸지 않는다.
  • 매일 아침 실행: 무인 실행 등록은 작업 스케줄러로 이어집니다.
  • 원칙 정합: 공개 데이터 수신만 — 외부 전송 0, 학생 개인정보 0, 교탁 PC 실행.

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

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 Gemini에 붙여넣습니다.
  2. 역질문 답변 — 어느 도시, 하루 몇 차, 엑셀 서식 세 질문에 답하면 설계가 고정됩니다.
  3. 스크립트 실행 — 파이썬 설치 후 python 수집기.py로 실행, 엑셀 파일에서 누적 확인.

제미나이 전용 에러 제로 프롬프트 (파이썬판)

[🚨 에러 방지 기본 안전장치]
1. 라이브러리는 requests, beautifulsoup4, openpyxl 세 가지만 사용한다(설치 부담 최소화).
2. 모든 네트워크 요청에는 timeout을 붙이고, 실패 시 1회 재시도 후 친절한 오류 메시지를 남긴다.
3. 셀렉터는 코드 상단 SELECTORS 상수로 관리하고, 주석에 '명세서 몇 행에서 왔는지'를 표기한다.
4. 칸을 찾지 못하면 프로그램을 중단하지 않고 '확인 필요'를 기록한다(조용한 실패 금지).
5. 엑셀 파일이 이미 열려 있어 저장이 실패하면 '엑셀을 닫고 다시 실행하세요' 안내를 출력한다.
6. 이 스크립트는 공개 데이터를 받아오기만 한다 — 데이터를 외부로 전송하는 기능을 만들지 않는다(학내망 원칙).
7. // TODO, pass 등 미완성 코드 금지 — 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 어느 지역의 기상·미세먼지를 수집할까? (우리 고장 시·군 기준)
Q2. 하루 몇 차 수집이 적당할까? (아침 1회 기본 — 과학 기록 관찰 연계)
Q3. 엑셀 서식은? (날짜 / 미세먼지 / 초미세먼지 3칸 기본)

🎯 에디터 한줄평

'날씨 기록하기'가 '코드에 기록하기'로 — 명세서라는 지도를 먼저 그리는 수업이 재현성을 가르칩니다. 공공데이터는 '받아오는 것'에도 격이 있습니다. 출처를 밝히고, 구조가 바뀌면 명세서를 고치는 자세 — 그것이 시민 데이터 소양의 시작입니다. 일주일 누적이 곧 수학 시간의 그래프 재료가 되는 순환 구조도 아름답습니다.

📚 기술·교육 참고 링크

  • 기상청 날씨누리 : 실측으로 정상 응답 확인(2026-09-05)
  • 에어코리아 : 대기환경 공개 데이터 — 수업 시점 셀렉터 직접 확인
  • requests 공식 문서 : 파이썬 HTTP 요청 표준 라이브러리
  • openpyxl 공식 문서 : 엑셀 파일 읽기·쓰기 라이브러리
  • 교육과정 연계: 과학(날씨와 생활·환경), 사회(우리 고장), 수학(자료의 수집과 정리)과 함께 활용

[학급 경영] 주간 복습 골든벨 & 다모임 퀴즈 쇼 - 초성·OX 퀴즈로 1주일 돌아보기



금요일이 쿠폰 한 장의 무대가 된다 — 주간 복습 골든벨 & 학급 다모임 퀴즈 쇼 완전 정복

🔔 매주 금요일, 1주일 동안 배운 핵심 어휘와 학급 자치 룰을 초성 퀴즈·OX 퀴즈로 묶어 교실 전자칠판에 실시간 퀴즈 쇼로 진행하고, 우수 모둠에게 학급 칭찬 쿠폰을 수여합니다. 문항은 학생들이 직접 출제 의뢰하는 자치 활동 — 제미나이 프롬프트로 초성·OX가 자동 생성됩니다.

퀴즈 플랫폼이 없어도 됩니다 — 단일 HTML 골든벨 앱(더블클릭 실행, 문제은행을 파일 안에 심는 심기 모드)이라면 서버·설치 없이 전자칠판에서 바로 돌아갑니다. 화면 표기는 모둠 번호와 닉네임뿐(이름 저장 0), 모둠 점수는 세션 메모리(session memory — 창을 닫으면 사라지는 메모리)로 관리합니다.

📖 한 줄 정의

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

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
운영 시나리오 금요일 성장날 '1주일 돌아보기' — 초성 10문항 + OX 10문항 + 자치 룰 2문항, 전자칠판 실시간 퀴즈 쇼. 종료 후 우수 모둠에 칭찬 쿠폰 수여. 금요일 리듬표(출제 의뢰 → 쇼 → 쿠폰)로 학급 문화화.
문항 3종 초성(어휘 복습)·OX(개념 판별)·자치 룰(약속 확인) — 마지막 두 문항이 우리 반 약속이라는 설계. 문항 출제는 학생 회의에서 의뢰하는 자치 활동. 초성 예시 'ㅅㅅㅂ' → 산성비(과학 연계 어휘).
골든벨 운영 모둠 대표 지명 방식 — 맞히면 모둠 점수 추가 + Web Audio 벨 소리('딩!'), 연속 10문항이면 전체 골든벨 축하 연출. 점수는 세션 메모리로만 관리. 벨 소리는 오디오 파일 없이 코드로 합성 — 아래 벨 코드.
제미나이 문제은행 1주일간 배운 어휘·자치 룰 목록을 제미나이에 넣으면 초성·OX 20문항이 서식대로 생성 — 힌트 칸까지 한 번에. 아래 제미나이 전용 프롬프트 복사 → 목록 붙여넣기.
원칙·정합 닉네임·모둠 번호만(이름 저장 0), 모둠 점수는 세션 메모리(종료 시 소멸), 칭찬 쿠폰은 종이. 외부 플랫폼 사용은 학교 정책 기준 — 없으면 단일 HTML 골든벨 앱(더블클릭·문제은행 심기)으로 완결. EMBED_DATA에 이번 주 문제은행 22문항 심기 — 학내망 통신 0.

2. 핵심 아키텍처 해설 — 초성이 코드가 되는 순간

① 문항 3종 설계

초성 퀴즈는 어휘 복습의 가장 오래된 놀이입니다. 1주일 동안 배운 교과 어휘를 모둠별로 올려보게 한 뒤(자치), 그 목록을 문제은행으로 넘기면 제미나이가 초성 문항으로 변환합니다. OX 문항은 '예/아니오'가 명확히 갈리는 개념 문장만 — 애매한 문장은 프롬프트 규칙이 걸러냅니다. 자치 룰 문항은 우리 반 약속 문장을 그대로 인용해 마지막에 배치합니다.

② 초성 생성 코드

function chosung(word) {
  const CHO = ["ㄱ","ㄲ","ㄴ","ㄷ","ㄸ","ㄹ","ㅁ","ㅂ","ㅃ","ㅅ","ㅆ","ㅇ","ㅈ","ㅉ","ㅊ","ㅋ","ㅌ","ㅍ","ㅎ"];
  let out = "";
  for (const ch of word) {
    const code = ch.charCodeAt(0) - 44032;
    if (code >= 0 && code < 11172) out += CHO[Math.floor(code / 588)];
    else out += ch;
  }
  return out;
}
chosung("산성비");   // 'ㅅㅅㅂ'

한글 한 글자는 44032부터 시작하는 번호로 배열되어 있고, 초성 자리는 588로 나눈 몫입니다 — 한글 구조를 3줄의 코드로 이해하는 소재로도 좋습니다.

③ 골든벨·모둠 점수 코드

const MOODIM = [0, 0, 0, 0];   // 세션 메모리 — 모둠 점수

function answerOx(i, pick) {
  if (pick === QUIZ[i].answer) {
    MOODIM[currentGroup] += 10;
    sound("bell");   // Web Audio 벨 합성 — 오디오 파일 금지
    return true;
  }
  return false;
}

④ 플랫폼 없이도 되는 단일 HTML 골든벨 앱

외부 퀴즈 플랫폼 없이도 전자칠판 쇼는 가능합니다 — 단일 HTML 골든벨 앱은 문제은행을 파일 안에 심는 심기 모드(데이터 임베딩)로 동작하므로 더블클릭 한 번으로 실행되고, 학내망 통신이 완전히 0입니다. 문항 전환은 전자칠판 터치(버튼 44px 이상), 정답 공개·모둠 점수 기입도 한 화면에서 처리합니다. 정기적으로 다른 문제은행으로 갈아 끼우려면 EMBED_DATA만 교체하면 됩니다 — 세션 메모리 원칙과 문제은행 갱신 루틴이 그대로 적용됩니다.

⑤ 원칙·정합

  • 이름 저장 0 — 화면 표기는 모둠 번호·닉네임뿐. 점수는 세션 메모리로 관리하고 종료 전 CSV 내보내기로 기록을 남기거나, 종이 쿠폰으로 마무리합니다.
  • 외부 플랫폼 — 사용 여부는 학교·교육청 정책 기준을 따릅니다. 플랫폼이 없어도 단일 HTML 앱으로 동일한 수업이 완성됩니다.

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

  1. 프롬프트 복사 — 아래 제미나이 전용 에러 제로 프롬프트를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 답변 — 이번 주 어휘·자치 룰 목록을 건네주고, 골든벨 앱 제작 여부를 알립니다.
  3. 실행 — 문제은행 표는 곧바로 쇼에 쓰고, 단일 HTML 골든벨 앱은 저장 후 더블클릭으로 전자칠판에 띄웁니다.

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

[🚨 에러 방지 기본 안전장치]
1. 산출물은 표(종류,문제,답,출처,힌트)로만 출력한다 — 초성 10문항, OX 10문항, 자치 룰 2문항, 총 22문항.
2. 초성 문항의 답은 반 단원 어휘만 사용하고 문항 간 겹침이 없어야 한다.
3. OX 문장은 예/아니오가 명확히 갈리는 것만 — 애매한 표현('대체로', '아마도') 금지.
4. 자치 룰 문항은 우리 반 약속 문장을 그대로 인용해 출제한다.
5. 힌트 칸에는 문항이 풀리지 않을 때 한 번만 공개할 한 줄 힌트를 둔다.
6. 골든벨 앱 제작이 요청되면 단일 HTML로 완성한다: 외부 라이브러리·폰트·이미지 금지, 문제은행은 EMBED_DATA 상수로 심는다(학내망 통신 0), 사운드는 Web Audio API 합성, 버튼 44px 이상, // TODO 금지.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 이번 주 핵심 어휘 10개와 자치 룰 2개를 목록으로 줄 수 있나?
Q2. 초성 힌트 공개 타이밍은? (2회 공개 / 미공개)
Q3. 골든벨 앱은 4모둠 기준으로 만들까? (모둠 수를 알려준다)

🎯 에디터 한줄평

금요일이 '쿠폰의 날'이 되는 학급 문화 — 복습이 심사가 아니라 무대가 되는 리듬입니다. 초성 퀴즈는 어휘 복습의 가장 오래된 놀이인데, 제미나이가 등장하자 그 놀이가 즉석 생성으로 풀렸습니다. 그리고 마지막 두 문항이 우리 반 자치 룰이라는 설계 — 마지막 정답은 점수가 아니라 우리 반 약속입니다. 칭찬 쿠폰 한 장이 아이들에게는 게임보다 오래 남는 전리품이 됩니다.

📚 기술·교육 참고 링크

  • 에이스 퀴즈 랩 등 국내 퀴즈 도구 — 도구명으로 검색해 공식 사이트에서 최신 주소와 서식을 반드시 확인하세요(이 글 검증 시점에는 주소를 확인하지 못했습니다).
  • 교육과정 연계: 국어(어휘·토의), 창의적 체험활동·학급자치(자치 룰·모둠 활동)와 함께 활용

[바이브 코딩] 심기 모드(데이터 임베딩) 완전 정복 - 외부 호출 0으로 API 데이터를 쓰는 기술



외부 호출 0으로 API 데이터를 쓰는 기술 — '심기 모드(데이터 임베딩)' 완전 정복

🌱 수업용 웹앱에서 환율·노벨상 같은 API 데이터를 쓰되, 학생 단말에서 외부 통신이 단 한 번도 일어나지 않게 하는 방법 — 데이터를 미리 받아 HTML 파일 안에 심는 '심기 모드'입니다.

이유는 두 가지입니다. 학생 데이터가 학교 밖으로 나가지 않게(개인정보), 그리고 수업이 외부 서비스의 사정에 끌려다니지 않게(안정성). 실제로 무료 API의 대명사였던 CountAPI는 서비스 종료로 하루아침에 사라졌습니다 — 외부 의존의 리스크는 이론이 아니라 실제 사건입니다.

이 글 하나로 받기 → 뽑기 → 심기 3단계와 '갱신 주기로 모드 고르기' 판단 기준까지 정리됩니다.

📖 한 줄 정의

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

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
왜 심는가 웹앱이 실행되는 내내 외부와 통신하면, 학생 단말의 기록이 밖으로 흘러가고(개인정보) 외부 장애에 수업이 끌려갑니다. 심기 모드는 통신 시점을 '제작할 때 단 한 번'으로 옮겨 두 문제를 동시에 끊습니다. 점심시간에 데이터 한 번 받아 심기 → 오후 수업은 인터넷 없이 완결.
두 모드 비교 fetch 실시간 모드는 항상 최신이지만 통신이 있습니다. 심기 모드는 심은 시점의 데이터지만 통신이 0입니다. 학교 배포용은 심기, 교사 개인 연습·시연은 fetch가 기본값입니다. EMBED_DATA 상수 하나로 두 모드를 스위치처럼 전환(아래 3단계 참고).
갱신 주기로 고르기 데이터가 바뀌는 주기가 길수록 심기에 유리합니다. 노벨상 수상자(1년 1회)는 완벽, 환율(매일)은 '심기 + 기준 날짜 표시'로 타협, 학생 입력·답안 같은 실시간 정보는 심기 개념과 무관합니다. 판단 규칙: 바뀌는 주기가 학기보다 길면 무조건 심기.
어떻게 만드나 3단계입니다: ① 받기(브라우저에서 json 내려받기) ② 뽑기(필요한 필드만 골라 용량 줄이기) ③ 심기(EMBED_DATA 상수로 파일 안에 박기). 앱 코드는 상수가 있으면 fetch를 아예 건너뜁니다. 모드 스위치 코드 5줄이면 끝(아래 ③ 참고).
주의점 심은 데이터는 기준 날짜를 화면에 반드시 표시 — 학생이 '오늘 환율'이라 착각하지 않게 합니다. 용량은 슬림화로 줄이고, 학생 개인정보는 애초에 API로 보내는 것이 없으니 수집·전송 모두 0으로 유지됩니다. 화면 하단 '기준 날짜: 2026-09-04' 문구 필수.

2. 핵심 아키텍처 해설 — 심기 3단계

① 받기: 브라우저가 곧 다운로더

API 키도, 프로그램 설치도 필요 없습니다. 브라우저 주소창에 데이터 주소를 넣고 열린 내용을 파일로 저장하면 끝입니다.

  • 환율: usd.min.json (1달러 기준 전 세계 환율, 하루 갱신)
  • 노벨상: laureates?limit=1000 (1901년부터 수상자 전체, 약 3.8MB)

② 뽑기: 필요한 필드만 골라 10분의 1로

전체 JSON을 심을 수도 있지만, 수업에 필요한 필드만 골라내면 파일도 가볍고 코드도 단순해집니다.

const slim = json.laureates.flatMap(function (l) {
  return l.nobelPrizes.map(function (p) {
    return {
      name: (l.knownName || l.orgName).en,          // 사람: knownName, 단체: orgName
      year: p.awardYear,
      category: p.category.en,
      motivation: p.motivation ? p.motivation.en : ""
    };
  });
});

환율 데이터라면 json.date와 필요한 통화 몇 개만 { date, krw, eur }처럼 골라 담으면 충분합니다.

③ 심기: EMBED_DATA 모드 스위치

const CDN1 = "https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1/currencies/";
const EMBED_DATA = null;   // null이면 실시간(fetch) 모드 — 심기 모드는 여기에 데이터를 붙여넣는다

async function getUsdRates() {
  if (EMBED_DATA) return EMBED_DATA.usd;            // 심기 모드: 통신 0, 즉시 반환
  const res = await fetch(CDN1 + "usd.min.json");   // 실시간 모드: 외부 통신 1회
  const json = await res.json();
  return json.usd;
}

EMBED_DATA가 null이면 실시간 모드, 데이터를 심으면 심기 모드 — 한 파일로 두 세계를 다 살아갑니다. 교사 PC에서 실시간 모드로 시연해보고, 배포 직전에 데이터를 심어 외부 호출 0 파일로 확정하는 흐름이 실무적입니다.

④ 모드 판단 기준: 갱신 주기가 답을 준다

데이터 종류 바뀌는 주기 추천 모드
노벨상 수상자 등 역사 데이터 1년 (10월 발표) 심기 모드 — 완벽
환율 매일 심기 모드 + 기준 날짜 표시(타협), 개인용은 실시간 fetch
학생 입력·답안·기록 실시간 심기 개념과 무관 — 앱 안에서만 처리(외부 전송 자체가 원칙 위반)

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

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 답변 — Gemini가 던지는 질문 3가지(다룰 데이터, 갱신 주기, 화면 톤)에 답하면 모드 추천까지 받아 설계가 확정됩니다.
  3. HTML 파일 실행 — 완성 코드를 메모장에 붙여 .html로 저장 후 더블클릭. EMBED_DATA가 null인 채로 실시간 모드를 시험해보고, 배포 직전 심기 모드로 확정합니다.

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

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·프레임워크·웹폰트 없이 단일 HTML 파일로 완성한다. (외부 통신은 EMBED_DATA가 null일 때의 데이터 fetch만 허용)
2. 사운드는 Web Audio API로 직접 합성한다: 데이터 준비 완료 시 부드러운 '똑' 소리, 불러오기 실패 시 '삑' 경고음. 오디오 파일·CDN 사운드 사용 금지.
3. 모바일 터치 대응: 뷰포트 메타 태그 필수, 버튼 최소 44×44px, 입력 필드 font-size 16px 이상, 360px 화면에서 가로 스크롤 금지.
4. 파일 상단에 EMBED_DATA = null 상수를 반드시 두고, 값이 null이면 fetch로 데이터를 받고 값이 있으면 fetch를 완전히 생략한다(학내망 배포용 외부 호출 0 모드).
5. 두 모드 모두 데이터의 기준 날짜를 화면 하단에 표시한다: 심기 모드는 심은 데이터의 date 값, fetch 모드는 받아온 json의 date 값.
6. fetch 실패 시 화면에 '오프라인: 데이터를 불러올 수 없습니다'를 친절히 안내하고 '삑' 경고음을 낸다.
7. // TODO, /* 생략 */ 같은 미완성 코드는 절대 넣지 말고 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 어떤 데이터를 다루는 앱인가? (환율 / 노벨상 수상자 / 그 밖의 공개 데이터)
Q2. 데이터의 갱신 주기는? (실시간 / 매일 / 연 1회 — 주기에 맞는 모드를 먼저 추천해 줄 것)
Q3. 화면 톤은? (큰 숫자 전광판 스타일 / 심플 카드 스타일)

🎯 에디터 한줄평

심기 모드는 '외부를 안 쓰는 기술'이 아니라 '외부를 미리 내 것으로 만드는 기술'입니다. 데이터를 한 번 받아 내 파일 안에 심는 순간, 수업은 학교 안에서 완결되고 학생 데이터는 학교 밖으로 한 걸음도 나가지 않습니다. CountAPI처럼 하루아침에 사라진 서비스의 교훈까지 얹으면, 갱신 주기 한 줄만 판단하면 두려울 게 없는 — 교사용 API 입문의 안전벨트입니다.

📚 기술·교육 참고 링크

  • MDN — Fetch API 문서 : 실시간 모드의 데이터 가져오기 기초
  • jsDelivr CDN : 무료 데이터 파일을 내려받는 '받기' 단계의 창고
  • 노벨 공식 Developer Zone : 심기 모드와 가장 잘 맞는 연 1회 갱신 데이터의 예
  • 교육과정 연계: 정보·실과(데이터와 개인정보, 네트워크의 기초), 사회(국제 경제), 영어(원문 데이터 읽기) 단원과 함께 활용