공개 템플릿 사용설명서 · 만든 사람 보드라운 고슴도치
3D 응원 공간을 우리 학교 이름으로 바꿔 인터넷 주소로 나누는 전체 과정입니다. 직접 하는 일은 대부분 계정 로그인과 클릭, 붙여 넣기입니다.
필수 단계만약 80분
2단계에서 멈춰도 됩니다. 내 컴퓨터에서 우리 학교 이름으로 돌아가므로 교실 TV에 띄우는 용도라면 여기까지로 충분합니다.
교문에서 출발해 운동장, 복도, 숲길, 옥상, 강당, 자습실, 시험고사장까지 15개 공간을 걸어 다니는 3D 웹사이트입니다. 학생은 링크를 누르고 입장 버튼만 누르면 됩니다. 5글자 별명이 자동으로 붙고, 같은 공간에 들어온 사람들이 서로 보입니다.
| 쓰임 | 필요한 단계 | 걸리는 시간 |
|---|---|---|
| 교실 TV나 내 노트북에 띄워 보여 준다 | 0~2단계 | 약 40분 |
| 학생에게 주소를 나누고 서로 보이게 한다 | 0~2단계, 7단계 | 약 80분 |
| 공간 이름, 응원 문구, 교복 색까지 바꾼다 | 위에 3~5단계 추가 | 70분 추가 |
| 건물 배치까지 우리 학교처럼 만든다 | 위에 6단계 추가 | 2~6시간 추가 |
모두 합쳐 필요한 계정은 GitHub와 Google 두 개입니다. 무료 요금제 안에서 쓸 수 있고 카드 등록은 필요 없습니다. Claude Code나 Codex를 쓰면 그 서비스의 이용 요금은 따로 듭니다.
너는 학교 선생님을 도와 공개 템플릿 https://github.com/thecozyforest/suneung-cheer-space 로 그 학교의 수능 응원 3D 공간을 만드는 코딩 에이전트다. 아래 순서대로 진행한다. [일하는 방식] - 한 번에 한 단계씩 진행하고, 단계가 끝날 때마다 무엇이 끝났는지 두세 문장으로 알린다. - 설명은 전문 용어 대신 "어디를 열어서 무엇을 누르고 무엇을 붙여 넣는지"로 말한다. - 사람이 직접 해야 하는 일을 만나면 멈춘다. 번호를 매겨 하나씩 안내하고 "끝났어요"라는 답을 기다린다. - 오류가 나면 같은 명령을 되풀이하기 전에 원인을 확인하고, 무슨 일인지 쉬운 말로 알린다. - 저장소를 받은 뒤에는 AGENTS.md를 먼저 읽는다. 이 지시서와 부딪히면 AGENTS.md의 금지 규칙을 따른다. [언제나 지키는 규칙] - 비밀번호, 인증 토큰, Firebase 서비스 계정 키를 달라고 하지 않는다. 내용에 "private_key"가 있는 값을 선생님이 붙여 넣으면 쓰지 말고, 그 키는 저장소에 넣으면 안 되는 값이라고 알린다. - 학생·교직원의 실명, 학번, 생년월일, 연락처, 얼굴 사진, 명렬표를 받지 않고 저장소에 넣지 않는다. - 학교 도면, 배치도 원본, 항공사진, 로드뷰 캡처는 _참고자료/ 폴더에서 보기만 하고 커밋하지 않는다. - 글을 자유롭게 입력하는 칸, 로그인, 회원가입, 학번 입력을 만들지 않는다. - 실제 인물을 등장인물로 만들지 않고, 음원 파일을 추가하지 않는다. - 기원 공간을 남긴다면 "학교의 실제 시설이 아닌 가상 공간" 표기를 지우지 않는다. - database.rules.json을 느슨하게 고치지 않는다. - npm audit fix --force를 실행하지 않고, 패키지의 큰 판 올림을 하지 않는다. - 공개 템플릿 원본 저장소(thecozyforest/suneung-cheer-space)에는 push도 PR도 하지 않는다. - 프로그램 설치, GitHub 저장소 만들기, git push, firebase deploy는 실행하기 직전에 무엇을 할지 말하고 동의를 받는다. [1단계: 먼저 묻기] 아래를 한 번에 모아서 묻는다. 실명이나 개인정보는 필요 없다고 먼저 말한다. 1. 학교 정식 이름 (예: 한빛고등학교) 2. 짧은 이름 2~3글자 (예: 한빛) 3. 수능일과 명칭. 기본값은 2026-11-19, 2027학년도 수능이다. 오늘이 그 날짜보다 뒤라면 다음 해 수능일을 확인해 달라고 한다. 4. 급식 창을 쓸지. 쓴다면 나이스 시도교육청 코드와 학교 코드(찾는 곳: https://open.neis.go.kr 의 학교기본정보). 모르면 비워 두고 진행한다. 5. 본관 뒤 건물 이름. 없으면 "별관"으로 둔다. 6. 어디까지 할지. A: 내 컴퓨터에서 띄우기까지. B: 인터넷 주소로 공개하고 접속자끼리 서로 보이게 하기. 7. 꾸미고 싶은 것. 없음 / 공간 이름 / 응원 문구 / 교복 색 / 건물 배치(건물 배치는 2~6시간 걸린다). 8. 새 저장소 이름. 영문 소문자, 숫자, 하이픈만 쓴다 (예: hanbit-cheer). [2단계: 환경 확인] node -v 로 Node.js 20 이상인지, git --version 으로 Git이 있는지 확인한다. 없으면 https://nodejs.org (LTS) 와 https://git-scm.com 에서 설치하도록 안내하고 기다린다. Windows PowerShell에서 npm이 실행 정책 오류로 막히면 실행 정책을 바꾸지 말고 npm.cmd를 쓰거나 명령 프롬프트(cmd)로 옮긴다. [3단계: 내 저장소로 복사하고 띄우기] 1. gh auth status 가 성공하면 저장소 이름과 비공개 생성을 확인받은 뒤 실행한다. gh repo create <저장소이름> --template thecozyforest/suneung-cheer-space --private --clone 2. gh를 쓸 수 없으면 선생님에게 안내한다. https://github.com/thecozyforest/suneung-cheer-space 를 열고 초록색 Use this template > Create a new repository를 누른 뒤, 이름을 넣고 Private을 고르고 Create repository를 누른다. 만들어진 주소를 받아 git clone 한다. 3. 받은 폴더로 들어가 AGENTS.md를 읽고 npm install 을 실행한다. 끝에 나오는 취약점 경고는 진행을 막지 않으니 그대로 둔다고 알린다. 4. npm test 로 9개가 모두 통과하는지 확인한다. [4단계: 학교 정보 넣기] 1. src/data/school.js 의 name, short, appName, audience, neis, examDate, examLabel, campus.annex 를 1단계 답으로 바꾼다. appName은 "<짧은 이름> 수능 응원 공간" 꼴로 쓴다. 2. index.html 의 og:title 과 og:description 을 학교에 맞춘다. 단톡방에 주소를 붙일 때 뜨는 제목이다. 3. npm test 와 npm run build 를 실행한다. 4. npm run dev 를 띄우고 http://127.0.0.1:5191 을 연다. 포트가 다르면 터미널에 표시된 주소를 쓴다. 교문 간판과 입장 화면에 학교 이름이 나오고 D-day가 맞는지 확인한다. 브라우저 도구가 있으면 직접 화면을 찍어 보여 주고, 없으면 선생님에게 확인을 부탁한다. A를 골랐고 꾸미기가 없으면 7단계로 간다. [5단계: 꾸미기, 고른 것만] - 공간 이름·설명: src/scenes/registry.js. 설명은 "~해요" 말투로 두 줄을 넘기지 않는다. - 응원 문구: src/data/phrases.js. 기존 문구는 지우지 않고 추가한다. 한 줄 60자 미만으로 쓴다. 학교 이름은 글자로 박지 말고 josa(SCHOOL.short, '이', '가') 를 쓴다. - 교복 색: src/engine/avatar.js 맨 위 상수. 바꾼 뒤 캐릭터를 앞쪽에서 찍어 눈으로 확인한다. - 건물 배치: docs/학교-모양-고치기.md 를 읽고 그 순서를 따른다. 꾸밀 때마다 npm test 와 npm run build 를 다시 돌린다. A를 골랐으면 7단계로 간다. [6단계: 함께 접속하고 공개하기, B를 고른 경우] 선생님이 Firebase 콘솔에서 직접 할 일을 하나씩 안내한다. 메뉴 이름이 다르게 보이면 콘솔 위쪽 검색창에 기능 이름을 넣도록 안내한다. 1. https://console.firebase.google.com 에서 프로젝트를 추가한다. 프로젝트 ID는 영문이어야 한다. Google 애널리틱스는 끈다. 2. Realtime Database를 만든다. Firestore가 아니다. 위치는 asia-southeast1, 보안 규칙은 잠금 모드로 시작한다. 3. Authentication > 로그인 방법 > 익명을 사용 설정한다. 4. 프로젝트 설정 > 내 앱 > 웹(</>)으로 앱을 추가하고 firebaseConfig 값을 복사해 이 대화에 붙여 넣게 한다. 받은 뒤 에이전트가 한다. 5. src/firebase-config.js 의 export const firebaseConfig = null; 줄을 받은 값으로 바꾼다. databaseURL이 빠져 있으면 Realtime Database 화면 위쪽 주소를 받아 채운다. 6. firebase --version 을 확인하고, 없으면 동의를 받아 npm i -g firebase-tools 를 실행한다. 7. firebase login 은 브라우저 로그인이 필요하다. 선생님이 자기 터미널에서 직접 실행하게 하고 끝날 때까지 기다린다. 8. 프로젝트 ID를 보여 주고 확인받은 뒤 이 순서를 지켜 실행한다. 보안 규칙이 먼저다. firebase deploy --only database --project <프로젝트ID> npm run build firebase deploy --only hosting --project <프로젝트ID> 9. 공개 주소는 https://<프로젝트ID>.web.app 이다. [7단계: 내 저장소에 저장] git status 와 git diff --stat 으로 올라갈 파일을 확인한다. 개인정보, 도면, 사진, .env, 서비스 계정 키가 없는지 본다. 어떤 파일을 올리는지 알리고 동의를 받은 뒤 한국어 메시지로 커밋하고 선생님의 저장소에 push 한다. [8단계: 점검과 보고] npm test 9개 통과와 npm run build 성공을 다시 확인한다. 주소 뒤에 ?time=<수능일>T08:45 를 붙여 수능날 화면을 미리 본다. 시험할 때는 ?solo 를 붙이면 서버에 기록이 남지 않는다. 선생님이 직접 확인할 일을 알린다. 휴대폰을 가로로 돌려 열어 보기, 기기 두 대로 같은 공간에서 서로 보이는지 보기, 자리에 앉았다 일어나기와 응원 보내기, 단톡방에 주소를 붙여 미리보기 제목 보기. 마지막에 다음을 표로 보고한다. 공개 주소 / 내 저장소 주소 / 바꾼 값 / 통과한 검사 / 확인하지 못한 것 / 선생님이 남은 일. 이제 1단계 질문부터 시작한다.
firebase login 실행private_key가 들어 있는 서비스 계정 키는 붙여 넣지 않습니다.| 준비물 | 받는 곳 | 비고 |
|---|---|---|
| Node.js 20 이상 | nodejs.org | LTS 버전을 받아 다음을 눌러 설치합니다 |
| Git | git-scm.com | 설치 선택지는 기본값 그대로 둡니다 |
| GitHub 계정 | github.com | 저장소 복사에 씁니다 |
| Google 계정 | 7단계에서 사용 | Firebase 로그인에 씁니다 |
Windows는 시작 메뉴에서 cmd를 검색해 명령 프롬프트를 엽니다. Mac은 Spotlight에서 터미널을 엽니다. 설치 직후라면 창을 새로 열어야 프로그램을 찾습니다.
아래 명령을 넣었을 때 버전 숫자가 나오면 준비가 끝난 것입니다.
node -v
git --versionhanbit-cheer. 한글은 쓸 수 없습니다.내아이디와 저장소이름은 본인 것으로 바꿉니다.cd Desktop
git clone https://github.com/내아이디/저장소이름.git
cd 저장소이름
npm install
npm run devhttp://127.0.0.1:5191을 열면 왼쪽 화면이 나옵니다. 첫 실행은 10초쯤 빈 화면일 수 있습니다.오른쪽 위의 혼자 보는 중은 정상입니다. 7단계를 마치면 접속자 수로 바뀝니다.
npm install 끝에 취약점 경고가 나와도 그대로 진행합니다. npm audit fix --force는 실행하지 마세요. 멈출 때는 명령 입력 창에서 Ctrl + C를 누릅니다.
받은 폴더의 src/data/school.js를 메모장이나 코드 편집기로 열어 작은따옴표 안의 값만 바꿉니다. 이 값이 간판, 전광판, 탭 제목, 응원 문구에 한꺼번에 들어갑니다.
| 항목 | 뜻 | 예시 (가상 학교) |
|---|---|---|
name | 교문과 본관 간판 | 한빛고등학교 |
short | 전광판과 응원 문구, 2~3글자 | 한빛 |
appName | 브라우저 탭과 입장 화면 제목 | 한빛 수능 응원 공간 |
audience | 입장 화면 맨 아랫줄 | 한빛고 학생·졸업생·선생님·학부모 누구나 |
neis | 급식 창의 나이스 코드, 비워도 됨 | office: B10, school: 숫자 7자리 |
examDate | D-day 기준일 | 2026-11-19 |
examLabel | 수능 명칭 | 2027학년도 수능 |
campus.annex | 본관 뒤 건물 이름 | 백양관 |
나이스 교육정보 개방 포털의 학교기본정보에서 학교 이름을 검색합니다. ATPT_OFCDC_SC_CODE가 office, SD_SCHUL_CODE가 school입니다. 비워 두면 자습실의 급식 창만 안내 문구로 뜹니다.
index.html의 og:title과 og:description 두 줄을 학교에 맞게 고칩니다.
npm test
npm run dev수능이 지난 뒤에 쓴다면 examDate와 examLabel을 공고된 다음 해 수능일로 바꿉니다.
건너뛰어도 7단계로 바로 갈 수 있습니다. 파일을 직접 고치기보다 에이전트에게 요청하는 편이 빠릅니다. 저장소의 단계별 안내서에 요청문이 더 있습니다.
| 단계 | 바꾸는 것 | 파일 | 시간 |
|---|---|---|---|
| 3 | 공간 이름과 소개 글 | src/scenes/registry.js | 20분 |
| 4 | 응원 문구 (한 줄 60자 미만) | src/data/phrases.js | 30분 |
| 5 | 교복 색 | src/engine/avatar.js | 20분 |
| 6 | 건물 배치 | src/scenes/front.js, rear.js | 2~6시간 |
src/data/phrases.js 의 응원 문구에 우리 학교 느낌을 더해 줘.
- 우리 학교는 산 중턱에 있어서 등굣길 계단이 길어. 그걸 소재로 몇 개 넣어 줘.
- 기존 문구는 지우지 말고 추가만 해 줘.
- 학교 이름이 들어가면 josa() 로 조사를 맞춰 줘.
- 한 줄 60자를 넘기지 말고, 다 쓴 뒤 npm test 로 확인해 줘._참고자료/ 폴더에 두고 보기만 합니다. 이 폴더는 GitHub에 올라가지 않습니다.Firebase 콘솔에서 아래 네 가지를 켭니다. 메뉴 이름이 다르게 보이면 콘솔 위쪽 검색창에 기능 이름을 넣어 찾습니다.
hanbit-cheer-2026. Google 애널리틱스는 꺼도 됩니다.asia-southeast1, 보안 규칙은 잠금 모드로 시작합니다.
firebaseConfig 값이 나옵니다. src/firebase-config.js의 export const firebaseConfig = null; 줄을 그 값으로 바꿉니다.
순서를 지켜 주세요. 보안 규칙이 먼저입니다. 프로젝트ID는 본인 것으로 바꿉니다.
npm i -g firebase-tools
firebase login
firebase deploy --only database --project 프로젝트ID
npm run build
firebase deploy --only hosting --project 프로젝트IDhttps://프로젝트ID.web.app 주소가 나옵니다. 이 주소를 학생에게 줍니다.| 주소 뒤에 붙이는 값 | 하는 일 |
|---|---|
?solo | 혼자 보기. 서버에 기록이 남지 않아 시험할 때 씁니다 |
?space=temple | 그 공간으로 바로 들어갑니다 |
?time=2026-11-19T08:45 | 그 서울 시각부터 시간이 흐릅니다. 수능날 화면을 미리 봅니다 |
?fresh | 별명을 새로 뽑습니다 |
| 항목 | 무료 한도 | 이 공간 기준 |
|---|---|---|
| 실시간 동시 접속 | 100명 | 101번째부터는 혼자 보기로 표시됩니다. 화면은 다 보이고 다른 사람만 안 보입니다 |
| 호스팅 전송 | 하루 360MB | 첫 방문 한 번에 약 370KB. 하루 첫 방문 약 970회 분량입니다 |
| 실시간 DB 내려받기 | 하루 360MB (월 10GB) | 같은 방에 있는 사람의 정보만 받도록 줄여 두었습니다 |
한 반이나 한 학년이 띄엄띄엄 들어오는 정도면 무료로 충분합니다. 조회 시간에 전교생이 함께 접속할 계획이면 종량제인 Blaze 요금제와 예산 알림을 먼저 살펴보세요. 사용량은 Firebase 콘솔에서 볼 수 있습니다.
남는 것은 날짜별 응원 수와 켜진 초 수 같은 숫자뿐이고 누가 눌렀는지는 남지 않습니다. 별명, 위치, 동작은 접속을 끊으면 사라집니다. 글은 저장되지 않습니다.
| 보이는 내용 | 뜻과 해결 |
|---|---|
'npm'은(는) 내부 또는 외부 명령이 아닙니다 | Node.js가 없거나 설치 전에 연 창입니다. 설치 후 창을 새로 엽니다 |
이 시스템에서 스크립트를 실행할 수 없으므로 | PowerShell의 제한입니다. 명령 프롬프트(cmd)로 옮겨 실행합니다 |
high severity vulnerabilities | 패키지 경고입니다. 그대로 진행하고 npm audit fix --force는 실행하지 않습니다 |
Some chunks are larger than 500 kB | 빌드 크기 안내입니다. 빌드는 성공한 상태입니다 |
Port 5191 is in use | 다른 창에서 이미 실행 중입니다. 명령 입력 창에 표시된 주소로 열거나 이전 창을 닫습니다 |
| 계속 "혼자 보는 중" | firebase-config.js의 databaseURL이 비었거나 틀렸습니다. 주소에 ?solo가 붙어 있는지도 봅니다 |
| 들어가는데 서로 안 보임 | 익명 로그인이 꺼져 있습니다 |
콘솔에 PERMISSION_DENIED | 보안 규칙을 올리지 않았습니다. firebase deploy --only database를 실행합니다 |
| 배포했는데 빈 화면 | npm run build 없이 올렸습니다. 빌드 후 다시 배포합니다 |
해결되지 않으면 저장소 이슈에 어느 단계에서 막혔는지 남겨 주세요.
.env 같은 비밀값기원 공간을 남긴다면 "학교의 실제 시설이 아닌 가상 공간" 표기를 유지합니다.