2026년 9월 6일 일요일

[바이브 코딩] 국립국어원 우리말샘 API - 우리말 어휘 검색기 & 방언 퀴즈 교구 만들기



우리말 어휘 검색기 & 방언 퀴즈 교구 만들기 — 국립국어원 우리말샘 API 완전 정복

📚 국립국어원 우리말샘은 표준국어대사전뿐만 아니라 전국 지역어(방언), 북한어, 고유어, 신조어까지 100만 개 이상의 풍부한 어휘 지식을 담고 있는 대한민국 대표 개방형 사전 플랫폼입니다.

학생들이 교과서 속 어려운 낱말의 뜻풀이를 스스로 찾아보고, "이 말은 어느 지역 사투리일까?"를 탐구하는 방언 퀴즈 교구를 단 한 장의 HTML 파일로 완성할 수 있습니다.

📖 한 줄 정의

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

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

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
어휘의 범위 표준어뿐만 아니라 지역어(방언), 고유어, 속담, 관용구까지 구분 필터로 골라 조회할 수 있는 국어 어휘의 보물창고입니다. 국어 5~6학년 '다양한 우리말 표현' 단원에서 각 지역 방언 카드를 모아 방언 사전 만들기.
인증 방식 우리말샘 누리집(opendict.korean.go.kr)에서 회원가입 후 30초 만에 16진수 32자리 무료 인증키를 발급받을 수 있습니다. 교사가 발급받은 인증키로 수업에 필요한 어휘 세트를 미리 추출해 두기.
CORS 실측과 해법 실측 결과 우리말샘 API는 브라우저 직접 호출용 CORS 헤더를 제공하지 않습니다. 교실 배포는 심기 모드(데이터 임베딩)가 필수이자 가장 안전한 해법입니다. 단원 핵심 어휘 30개를 파일 상단 상수에 심어 학내망 통신 0으로 배포하기.

2. 핵심 아키텍처 해설 — 우리말샘 데이터 구조와 심기 모드

① URL 해부와 파라미터

우리말샘 검색 엔드포인트는 다음과 같이 구성됩니다:

https://opendict.korean.go.kr/api/search?key=인증키&q=검색어&req_type=json&part=word&sort=dict
  • key: 16진수 32자리 발급 인증키 (필수)
  • q: 검색어 (UTF-8 인코딩)
  • req_type=json: 기본값이 xml이므로 JSON 형식으로 받으려면 필수 지정
  • type3: 어휘 범주 (general: 일반어, dialect: 지역어/방언, nkorean: 북한어, ancient: 옛말)
  • region: 방언 지역 코드 (1: 강원, 2: 경기, 5: 경상, 7: 전라, 9: 제주 등)

② 실측 응답 데이터 모양

{
  "channel": {
    "total": 2,
    "item": [
      {
        "word": "나무",
        "sense": {
          "definition": "줄기나 가지가 목질로 된 여러해살이 식물.",
          "pos": "명사",
          "type": "일반어"
        }
      }
    ]
  }
}

개별 검색 결과는 channel.item[] 배열로 들어오며, word(표제어), sense.definition(뜻풀이), sense.pos(품사), sense.type(범주)가 핵심 필드입니다.

③ CORS 장벽을 넘는 '심기 모드(데이터 임베딩)' 설계

우리말샘 API는 서버 간 통신에 최적화되어 브라우저에서 직접 fetch를 호출하면 CORS 오류가 발생합니다. 교실 수업에서는 교사가 필요한 어휘 세트를 미리 추출하여 파일 안의 상수로 심어두는 심기 모드(데이터 임베딩)로 완벽하게 해결할 수 있습니다.

const EMBED_WORDS = [
  { word: "가시버시", type: "고유어", pos: "명사", def: "부부(夫婦)를 낮추어 이르는 말." },
  { word: "동티", type: "고유어", pos: "명사", def: "공연히 건드려 스스로 사서 겪는 걱정이나 탈." },
  { word: "혼저옵서", type: "방언(제주)", pos: "감탄사", def: "'빨리 오십시오'라는 뜻의 제주도 방언." },
  { word: "호랭이", type: "방언(경상)", pos: "명사", def: "'호랑이'의 경상도 방언." }
];

④ 검색 코드(제미나이 전용 에러 제로 프롬프트로 완성할 부분)

const API = "https://opendict.korean.go.kr/api/search";

async function searchWord(key, word) {
  const qs = new URLSearchParams({
    key: key, q: word, req_type: "json", num: 10, part: "word"
  });
  const res = await fetch(API + "?" + qs);
  const json = await res.json();
  return json.channel;   // channel.item[].word, sense.definition
}

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

  1. 제미나이 전용 에러 제로 프롬프트 복사 — 아래 프롬프트 전체를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 3가지에 답변 — 국어 교과 단원, 방언 지역, 카드 스타일을 결정합니다.
  3. HTML 파일 저장 후 더블클릭 — 외부 통신 없이 즉시 학내망 배포 완결.

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

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·폰트·이미지 없이 단일 HTML 파일로 완성한다(더블클릭 즉시 실행).
2. 파일 상단 EMBED_WORDS 상수에 방언·속담·고유어 어휘 카드를 심기 모드(데이터 임베딩)로 완전 내장한다(외부 통신 0).
3. 우리말샘 API는 CORS 헤더를 제공하지 않으므로 브라우저에서 직접 fetch하는 코드를 넣지 않는다(실측 오류 방지).
4. 방언 퀴즈 모드: 표준어를 보고 맞는 방언 카드를 고르는 4지선다 + 정답 판정음(Web Audio 합성).
5. 어휘 카드 조회 모드: 품사·범주(일반어/방언/속담)별 필터와 검색을 지원한다.
6. 학생 표기는 번호·닉네임만 허용(실명·성적 저장 금지), 기록은 세션 메모리로만 관리한다.
7. 모바일 터치 대응: 뷰포트 메타 태그 필수, 버튼 최소 44×44px, 360px 화면 가로 스크롤 금지.
8. // TODO, /* 생략 */ 금지 — 끝까지 완성한다.

[❓ 역질문 유도]
Q1. 우리 반 학년·단원 주제는 무엇인가? (예: 5학년 '다양한 우리말 표현', 방언 지역)
Q2. 퀴즈 형식은 무엇으로 할까? (방언↔표준어 짝 맞추기 / 뜻 고르기 4지선다)
Q3. 어휘 카드 톤은 무엇으로 할까? (국어책 느낌 파스텔 / 사전 느낌 심플)

🎯 에디터 한줄평

'사전 찾아보기'라는 소극적 과제가 '내 손으로 방언 카드를 심어 방언 퀴즈를 만드는 작업'으로 완전히 바뀌었습니다. 특히 API의 CORS 실측 사실(브라우저 직접 fetch 불가)을 오류가 아니라 **교육적 설계의 기회**로 전환한 과정이 돋보입니다. 국어·지역어·속담이 학생들의 손끝에서 데이터로 재탄생하는 순간이 최고의 국어 수업입니다.

📚 기술·교육 참고 링크

By 시간: