번들러 없이 정적 사이트로 학습·시험 앱 만드는 법
빌드 도구 없이 바닐라 HTML/CSS/JS로 학습·시험 사이트를 만들어 GitHub Pages에 배포한 기록. 콘텐츠 계층과 시험 엔진, 에이전트의 문항 작성·검토, CSS 버그와 브라우저 검증, 이후 추가된 콘텐츠 회귀 검사를 다룬다.

번들러도, 프레임워크도, 패키지 매니저도, CI 워크플로도, 타입 검사도 없다. 그래도 HTML·CSS·바닐라 자바스크립트로 개념 학습, 문제풀이, 시간제한 모의고사가 돌아갔다. 작은 학습 앱을 혼자 만들면서 번들러 설정에 시간을 쓰는 일이 부담스럽다면 참고할 만한 구성이다. 다만 이 선택에는 네 HTML의 공용 헤더를 따로 수정하고 화면 동작을 브라우저에서 확인하는 부담이 남았다.
JSON을 읽어 학습과 시험을 제공하는 범위에서는 빌드 도구 없이도 구현할 수 있었지만, 콘텐츠 검사와 화면 검증은 별도로 필요했다.
이 사례는 미용사(일반) 필기시험 대비 학습·모의고사 사이트를 GitHub Pages에 배포한 기록이다. 2026년 7월 6일 배포 시점에는 대과목 4개, 중과목 27개, 개념 55개, 문항 240개였다. 이 글에 반영한 현재 코드·데이터 기록에서는 중과목 28개, 개념 56개, 문항 244개로 늘어났다. 아래에서는 당시 구현과 이후 추가된 콘텐츠 회귀 검사를 구분한다.
왜 번들러 없이 만들기로 했나
이 사이트는 계정·결제·실시간 통신 없이 JSON 데이터를 읽어 화면에 표시하는 범위였다. 서버 쪽 로직 없이 정적 파일로 학습과 시험을 제공했다. 이 요구사항에서는 빌드 도구를 추가하지 않는 구성을 선택했다.
자바스크립트는 ES5 IIFE 스타일로 작성했다. IIFE는 함수를 선언한 뒤 즉시 실행해 함수 안의 변수를 전역 공간과 구분하는 패턴이다. 배포는 GitHub Pages의 브랜치 기반 배포 설정을 사용했고, 별도의 Actions 워크플로를 작성하지 않았다. 2026년 7월 6일 첫 배포에는 12개 파일, 7,916줄이 포함됐으며 네 HTML 화면과 데이터·JS·CSS의 HTTP 200 응답을 확인했다.
npm 의존성은 설치하지 않았다. 첫 배포 시점에는 테스트 파일이 포함되지 않았지만, 이후 콘텐츠 JSON에 대한 파이썬 회귀 테스트가 추가됐다. 현재는 이 회귀 테스트를 로컬에서 수동으로 실행한다. UI·JS 로직 자동 테스트와 CI 워크플로, 타입 검사는 없는 상태다.
파일 간 의존 순서는 HTML의 스크립트 태그 순서로 관리한다. 공용 헤더도 index·study·quiz·exam 네 HTML에 각각 복사돼 있다. 헤더 문구를 바꾸려면 네 파일을 함께 수정해야 하며, 공유 컴포넌트로 모으는 작업은 남아 있다. 혼자 유지보수한다면 빌드 설정을 줄인 이점과 반복 수정의 부담을 함께 판단해야 한다.
서버 상태가 필요한 앱이라면 검토할 범위가 달라진다. 인증과 과금을 다루는 별도 주제는 SaaS 인증·과금 보일러플레이트 글에 정리돼 있다. 여기서 확인한 구현 범위는 JSON을 읽는 학습·시험 화면이며, 이 조건을 벗어나는 요구사항까지 같은 구조로 해결했다고 볼 수는 없다.
4단계 계층으로 콘텐츠를 쌓다
2026년 7월 6일 배포 당시 학습 계층은 대과목 4개, 중과목 27개, 개념 55개였다.
이론·피부·화장품·위생의 개념 수는 각각 21·11·12·11개였다.
현재 기록에서는 대과목 4개를 유지하면서 중과목 28개, 개념 56개로 바뀌었고, 같은 순서의 개념 수는 22·11·12·11개다.
데이터는 concepts.json의 categories[].subCategories[].concepts[]에 담고, 각 개념에 제목·본문·요약·시험포인트 필드를 뒀다.
배포 당시 중과목은 공식 출제기준과 표준교재라는 두 기준을 겹쳐 매핑했다. 학습 화면에서는 계층 속 개념들을 순서대로 펼쳐 한 번에 하나씩 읽도록 했다. 이전·다음 버튼에는 이동할 개념의 제목을 작게 표시했다.
학습 화면 가운데에는 해당 중과목의 문제풀이로 이동하는 버튼을 뒀다.
버튼은 quiz.html?sub=에 중과목 키를 붙여 전달한다.
읽던 개념은 URL 해시에 남기므로 같은 URL을 다시 열거나 새로고침해도 그 개념으로 돌아간다.
이 학습 위치 보존에는 로그인이나 서버 저장을 사용하지 않았다.
2026년 7월 6일 배포에서는 문제은행을 80문항에서 240문항으로 확장했다. 당시 구성은 이론 96·피부 24·화장품 36·위생 84문항이었고, 비어 있던 중과목 9개를 채워 27개 중과목을 모두 다뤘다. 현재 기록의 문제은행은 이론 100·피부 24·화장품 36·위생 84문항으로 총 244문항이다. 각 문항에는 카테고리·질문·보기 4개·정답 인덱스·해설·소속 중과목 필드가 있다.
시험 엔진의 규칙
앱의 모의고사는 최대 60문항을 출제하며 100점 만점에 60점을 합격 기준으로 삼는다. 현재 244문항인 문제은행에서는 60문항·60분으로 동작한다. 은행에 60문항보다 적게 있으면 있는 문항을 사용하고 제한시간도 문항당 1분으로 줄인다. 은행이 비어 있으면 시작 버튼을 비활성화한다.
시험 화면에는 남은 시간을 보여주는 타이머와 문항 이동용 그리드를 뒀다.
제출 후에는 오답을 모아 복습할 수 있다.
오답노트의 접기·펼치기는 브라우저 기본 요소인 <details>로 구현했다.
응시 시작 시 문제은행 전체의 복사본을 Fisher-Yates 방식으로 섞고 앞에서 최대 60개를 취한다. 각 문제의 보기 순서도 다시 섞으며, 바뀐 순서에 맞춰 정답 인덱스를 재계산한다. 문항 순서뿐 아니라 보기 위치도 달라지므로 고정된 문항 번호나 보기 번호가 정답을 가리키지 않게 하는 구성이다.
일반 문제풀이 화면은 모의고사와 별도로 카테고리별 모드와 랜덤 모드를 제공한다.
URL에 ?sub=가 있으면 해당 중과목 범위로 문제풀이를 시작한다.
그 범위에 문항이 하나도 없으면 안내 후 일반 설정 화면으로 돌아가도록 처리했다.
베끼는 대신 다시 쓴 이유
초기에는 기존 정리 블로그의 문항과 설명을 그대로 옮기는 접근을 검토했다.
자료 수집을 맡은 에이전트가 저작권 문제를 지적했고, 원문 복제를 피하는 방향으로 바꿨다.
새 문항의 재료로는 이미 정제한 concepts.json, 기존 문항의 스타일, 공개 출제기준·표준교재의 미용사 표준지식을 사용했다.
이 자료를 바탕으로 세션 에이전트가 신규 160문항을 작성했다. 2026년 7월 6일에는 Opus 계열 모델로 4회에 걸쳐 반박과 오류를 찾는 어드버서리얼 검증을 수행한 것으로 기록돼 있다. 아래는 배포 완료 기록에 남은 결과이며, 모델의 검토 결과를 문항에 오류가 없다는 증명으로 볼 수는 없다.
| 카테고리 | 검증한 신규 문항 수 | 기록된 지적 사항 |
|---|---|---|
| 화장품학 | 24문항 | 0건 |
| 피부학 | 16문항 | 0건 |
| 공중위생 | 56문항 | 0건 |
| 이론(미용학개론 등) | 64문항 | 1건(문두 표현 명확화 필요) |
이론의 지적 사항 한 건은 문두 표현을 명확히 하는 수정으로 처리했다. 기존의 잘못된 폐업신고 7일 문항은 법상 미용업 신고제를 묻는 문항으로 재작성했다. 폐업신고 20일 규정은 신규 위생 문항이 별도로 다루며, 현재 콘텐츠 회귀 테스트도 그 값을 확인한다. 조회일 2026-09-29 기준 공중위생관리법 제3조에 따르면 공중위생영업자는 폐업한 날부터 20일 이내에 시장·군수·구청장에게 신고해야 한다. 다만 영업정지 등의 기간 중에는 폐업신고를 할 수 없다.
배포와 검증에서 걸린 함정들
퀴즈·모의고사에서 숨겨져야 할 화면 요소가 겹쳐 보이는 문제가 있었다.
해당 요소에는 [hidden] 속성이 있었지만 작성한 CSS의 display:flex·display:block과 충돌해 표시됐다.
[hidden]{display:none} 규칙을 세 곳에 추가해 숨김 상태를 바로잡았다.
화면 확인에는 구현과 별도의 브라우저 검증 에이전트를 사용했다. 두 검증 에이전트가 디버깅 포트 8765와 같은 Chrome 인스턴스를 공유하자 서로 탭을 빼앗고 페이지가 저절로 이동하는 현상이 나타났다. 에이전트를 하나씩 단독으로 실행해 이 충돌을 해결했다. 이 경우에는 순차 실행이 확실했으며, 순차·병렬 실행의 소요 시간을 비교한 결과는 아니다.
공용 헤더 중복은 아직 남아 있다. index·study·quiz·exam 네 화면을 따로 수정하므로 같은 헤더가 화면마다 달라질 위험이 있다. 관련 구현 기록은 프로그래밍 카테고리에서 함께 볼 수 있다.
정적 사이트를 다시 검증하는 순서
현재 콘텐츠 JSON 회귀 테스트는 로컬에서 수동 실행하지만, UI·JS 로직 자동 테스트와 CI 워크플로는 없다. 따라서 데이터 검사를 통과했다는 사실과 학습·문제풀이·모의고사 화면이 연결된다는 사실은 따로 확인해야 한다. 다음은 이 구조를 다시 점검할 때 사용할 수 있는 브라우저 확인 순서다. 같은 Chrome 인스턴스에 검증 에이전트를 동시에 붙이지 않고 한 작업이 끝난 뒤 다음 작업을 시작한다.
- 네 HTML 화면을 각각 직접 연다.
index·study·quiz·exam을 새로고침하고 개발자 도구 콘솔에서 스크립트 로드와 참조 오류를 확인한다. 오류가 있다면 해당 HTML의 스크립트 태그 순서와 파일 의존 관계를 대조한다. - 학습 위치가 URL에 남는지 본다. 데이터에 있는 개념으로 이동한 뒤 주소의 해시가 바뀌는지 확인한다. 그 URL을 다시 열었을 때 같은 개념으로 돌아와야 한다.
- 중과목 연결과 빈 데이터 처리를 나눠 확인한다.
학습 화면의 문제풀이 버튼이
?sub=를 전달하고 해당 범위의 문제를 여는지 본다. 별도 검증용 데이터에서 문항이 없는 중과목도 만들어 안내 후 일반 설정 화면으로 돌아오는지 확인한다. - 은행 크기에 따른 시험 규칙을 확인한다. 60문항 이상이면 60문항·60분, 1~59문항이면 해당 문항 수와 문항당 1분이 표시돼야 한다. 은행이 비면 시작 버튼이 비활성화돼야 한다. 제출 후에는 100점 만점 점수, 60점 합격 판정, 오답노트가 같은 답안 결과를 반영하는지 본다.
- 숨김 요소가 실제로 숨었는지 본다.
시작 전·응시 중·제출 뒤 상태를 바꾸면서 패널이 겹치지 않는지 확인한다.
아래 콘솔 식은
[hidden]이 있으면서 계산된display가none이 아닌 요소를 찾는 점검용 예시다.
Array.prototype.filter.call(document.querySelectorAll('[hidden]'), function (el) {
return getComputedStyle(el).display !== 'none';
});
콘텐츠 수는 과거 배포 숫자를 고정 기준으로 삼지 말고 검토 중인 데이터 버전과 맞춰 확인한다. 전체 문항 합계와 카테고리별 합계가 데이터 파일의 선언 값 또는 해당 버전의 기대값과 일치하는지 본다. 개념·중과목 연결, 보기 4개, 정답 인덱스 범위, 중복 문항도 콘텐츠 회귀 검사에서 확인할 항목이다. 모의고사에 60문항이 나온다는 사실만으로 전체 문제은행이나 중과목 연결이 올바르다고 판단해서는 안 된다.
| 점검할 증상 | 확인할 경계 | 기록된 대응 |
|---|---|---|
| 숨겨야 할 패널이 겹쳐 보임 | [hidden]과 display:flex·display:block 충돌 | [hidden]{display:none} 명시 |
| 검증 중 페이지가 저절로 이동함 | 검증 에이전트의 디버깅 포트 8765와 Chrome 인스턴스 공유 | 에이전트를 하나씩 단독 실행 |
| 중과목 링크의 대상 문항이 없음 | ?sub= 대상의 문항 존재 여부 | 안내 후 일반 설정 화면으로 복귀 |
이 프로젝트에서는 계정·결제·실시간 통신 없이 학습과 시험을 제공하는 범위를 정적 파일로 구현했다. 이후 콘텐츠 회귀 테스트를 추가했지만 공용 헤더 중복과 수동 스크립트 순서 관리, 별도 화면 검증은 여전히 남아 있다. 작은 앱의 도구를 고를 때는 빌드 설정을 얼마나 줄일 수 있는지와 이런 유지보수 작업을 감당할 수 있는지를 함께 따져보는 편이 좋다.
자주 묻는 질문
번들러 없이 만든 구조에서 가장 큰 유지보수 비용은 무엇이었나요?
스크립트 태그 순서로 파일 의존성을 손수 관리해야 했다. study·quiz·exam·index 네 화면의 공용 헤더도 각각 복사해 뒀다. 헤더 문구 하나를 바꿀 때 네 파일을 모두 수정해야 하는 중복이 남았다.
문항이 없는 중과목 링크를 열면 빈 화면이 나오나요?
아니다. ?sub= 파라미터로 해당 중과목 문제를 시작하되 문항이 하나도 없으면 안내 후 일반 설정 화면으로 되돌린다. 문항이 있는 경우와 없는 경우를 나눠 확인할 수 있도록 처리한 경계다.
기존 블로그 문항은 어떻게 처리했나요?
자료 수집 에이전트의 저작권 지적을 받아 원문을 그대로 옮기는 접근을 바꿨다. 이미 정제한 concepts.json, 기존 문항 스타일, 공개 출제기준·표준교재의 지식을 재료로 삼았다. 이를 바탕으로 세션 에이전트가 2026년 7월 6일 배포에 포함된 신규 160문항을 작성했다.
왜 브라우저 검증 에이전트를 동시에 실행하지 않았나요?
두 에이전트가 디버깅 포트 8765와 같은 Chrome 인스턴스를 공유했다. 그 상태에서 서로 탭을 빼앗고 페이지가 저절로 이동하는 현상이 나타났다. 이 충돌은 에이전트를 한 번에 하나씩 단독 실행해 해결했다.
아직 댓글이 없습니다.