공개 템플릿 사용설명서 · 만든 사람 보드라운 고슴도치

우리 학교 수능 응원 공간 만들기

3D 응원 공간을 우리 학교 이름으로 바꿔 인터넷 주소로 나누는 전체 과정입니다. 직접 하는 일은 대부분 계정 로그인과 클릭, 붙여 넣기입니다.

필수 단계만약 80분

파일이 움직이는 길
공개 템플릿GitHub의 원본
1단계
복사
내 GitHub 저장소내 계정의 복사본
1단계
내려받기
내 컴퓨터2~6단계
학교 정보 넣고 꾸미기
7단계
올리기
Firebase공개 주소와
실시간 접속
주소
나누기
학생 휴대폰링크 누르고 입장
단계 시간표 (누르면 자세한 설명으로 이동합니다)

2단계에서 멈춰도 됩니다. 내 컴퓨터에서 우리 학교 이름으로 돌아가므로 교실 TV에 띄우는 용도라면 여기까지로 충분합니다.

무엇을 만드나

교문에서 출발해 운동장, 복도, 숲길, 옥상, 강당, 자습실, 시험고사장까지 15개 공간을 걸어 다니는 3D 웹사이트입니다. 학생은 링크를 누르고 입장 버튼만 누르면 됩니다. 5글자 별명이 자동으로 붙고, 같은 공간에 들어온 사람들이 서로 보입니다.

교문과 D-day 전광판이 보이는 학교 전경
학교 전경
가상 기원 공간인 법당
법당 (가상 기원 공간)
타이머와 단어장이 있는 자습실
자습실
별관 앞 낙엽 벤치
별관 앞 낙엽 벤치

어디까지 할까

쓰임필요한 단계걸리는 시간
교실 TV나 내 노트북에 띄워 보여 준다0~2단계약 40분
학생에게 주소를 나누고 서로 보이게 한다0~2단계, 7단계약 80분
공간 이름, 응원 문구, 교복 색까지 바꾼다위에 3~5단계 추가70분 추가
건물 배치까지 우리 학교처럼 만든다위에 6단계 추가2~6시간 추가

모두 합쳐 필요한 계정은 GitHub와 Google 두 개입니다. 무료 요금제 안에서 쓸 수 있고 카드 등록은 필요 없습니다. Claude Code나 Codex를 쓰면 그 서비스의 이용 요금은 따로 듭니다.

에이전트에게 맡기기

  1. 바탕화면에 빈 폴더를 하나 만들고 Claude Code나 Codex에서 그 폴더를 엽니다.
  2. 아래 지시서를 전체 복사해서 입력창에 붙여 넣고 보냅니다.
  3. 에이전트의 질문 8개에 답합니다. 학교 이름, 수능일, 어디까지 할지 같은 내용입니다.
  4. 에이전트가 멈추고 안내하면 그대로 클릭한 뒤 "끝났어요"라고 답합니다.
너는 학교 선생님을 도와 공개 템플릿 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단계 질문부터 시작한다.

사람 직접 하는 일

  • Node.js, Git 설치
  • GitHub, Google 계정 로그인
  • Firebase 콘솔에서 프로젝트, 데이터베이스, 익명 로그인 켜기
  • firebase login 실행
  • 휴대폰과 다른 기기로 확인하기

에이전트 맡기는 일

  • 저장소 받기와 패키지 설치
  • 학교 정보, 문구, 색 고치기
  • 시험과 빌드 돌리기
  • 보안 규칙 올리기와 배포 명령 실행
  • 바꾼 내용과 남은 일 보고하기
비밀번호는 입력창에 쓰지 마세요로그인은 브라우저에서 직접 합니다. Firebase의 웹 설정값은 붙여 넣어도 되지만 private_key가 들어 있는 서비스 계정 키는 붙여 넣지 않습니다.
0

준비

20분내 컴퓨터
준비물받는 곳비고
Node.js 20 이상nodejs.orgLTS 버전을 받아 다음을 눌러 설치합니다
Gitgit-scm.com설치 선택지는 기본값 그대로 둡니다
GitHub 계정github.com저장소 복사에 씁니다
Google 계정7단계에서 사용Firebase 로그인에 씁니다

명령 입력 창 열기

Windows는 시작 메뉴에서 cmd를 검색해 명령 프롬프트를 엽니다. Mac은 Spotlight에서 터미널을 엽니다. 설치 직후라면 창을 새로 열어야 프로그램을 찾습니다.

아래 명령을 넣었을 때 버전 숫자가 나오면 준비가 끝난 것입니다.

node -v
git --version
학교 업무용 PC보안 프로그램 때문에 설치가 막히면 개인 컴퓨터에서 진행합니다.
1

복사해서 띄우기

10분GitHub → 내 컴퓨터
  1. 공개 템플릿 페이지를 열고 로그인합니다.
  2. 오른쪽 위 초록색 버튼을 누르고 Create a new repository를 고릅니다.
    Use this template
  3. Repository name에 영문으로 이름을 적습니다. 예: hanbit-cheer. 한글은 쓸 수 없습니다.
  4. Private을 고르고 Create repository를 누릅니다. 공개 여부는 나중에 바꿀 수 있습니다.
  5. 명령 입력 창에 아래를 차례로 넣습니다. 내아이디와 저장소이름은 본인 것으로 바꿉니다.
cd Desktop
git clone https://github.com/내아이디/저장소이름.git
cd 저장소이름
npm install
npm run dev
○○ 수능 응원 공간 입장 화면. D-8과 혼자 보는 중 표시가 보인다
이렇게 되면 성공브라우저에서 http://127.0.0.1:5191을 열면 왼쪽 화면이 나옵니다. 첫 실행은 10초쯤 빈 화면일 수 있습니다.

오른쪽 위의 혼자 보는 중은 정상입니다. 7단계를 마치면 접속자 수로 바뀝니다.

npm install 끝에 취약점 경고가 나와도 그대로 진행합니다. npm audit fix --force는 실행하지 마세요. 멈출 때는 명령 입력 창에서 Ctrl + C를 누릅니다.

2

학교 정보 넣기

10분내 컴퓨터src/data/school.js, index.html

받은 폴더의 src/data/school.js를 메모장이나 코드 편집기로 열어 작은따옴표 안의 값만 바꿉니다. 이 값이 간판, 전광판, 탭 제목, 응원 문구에 한꺼번에 들어갑니다.

항목뜻예시 (가상 학교)
name교문과 본관 간판한빛고등학교
short전광판과 응원 문구, 2~3글자한빛
appName브라우저 탭과 입장 화면 제목한빛 수능 응원 공간
audience입장 화면 맨 아랫줄한빛고 학생·졸업생·선생님·학부모 누구나
neis급식 창의 나이스 코드, 비워도 됨office: B10, school: 숫자 7자리
examDateD-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
이렇게 되면 성공시험 9개가 통과하고, 교문 간판과 입장 화면이 우리 학교 이름으로 바뀝니다.

수능이 지난 뒤에 쓴다면 examDate와 examLabel을 공고된 다음 해 수능일로 바꿉니다.

3~6

꾸미기 (선택)

건너뛰어도 7단계로 바로 갈 수 있습니다. 파일을 직접 고치기보다 에이전트에게 요청하는 편이 빠릅니다. 저장소의 단계별 안내서에 요청문이 더 있습니다.

단계바꾸는 것파일시간
3공간 이름과 소개 글src/scenes/registry.js20분
4응원 문구 (한 줄 60자 미만)src/data/phrases.js30분
5교복 색src/engine/avatar.js20분
6건물 배치src/scenes/front.js, rear.js2~6시간

에이전트에게 보낼 요청 예시

src/data/phrases.js 의 응원 문구에 우리 학교 느낌을 더해 줘.
- 우리 학교는 산 중턱에 있어서 등굣길 계단이 길어. 그걸 소재로 몇 개 넣어 줘.
- 기존 문구는 지우지 말고 추가만 해 줘.
- 학교 이름이 들어가면 josa() 로 조사를 맞춰 줘.
- 한 줄 60자를 넘기지 말고, 다 쓴 뒤 npm test 로 확인해 줘.
건물 배치 자료항공사진, 배치도, 로드뷰 캡처는 _참고자료/ 폴더에 두고 보기만 합니다. 이 폴더는 GitHub에 올라가지 않습니다.
7

함께 접속하고 공개하기

40분Firebase 콘솔 → 내 컴퓨터Google 계정 필요

Firebase 콘솔에서 아래 네 가지를 켭니다. 메뉴 이름이 다르게 보이면 콘솔 위쪽 검색창에 기능 이름을 넣어 찾습니다.

  1. 프로젝트 만들기. 프로젝트 ID는 영문 소문자로 정해지며 주소에 그대로 쓰입니다. 예: hanbit-cheer-2026. Google 애널리틱스는 꺼도 됩니다.
  2. 실시간 데이터베이스 켜기. 이름이 비슷한 Firestore가 아닙니다. 위치는 asia-southeast1, 보안 규칙은 잠금 모드로 시작합니다.
    빌드›Realtime Database›데이터베이스 만들기
  3. 익명 로그인 켜기. 학번과 이메일을 받지 않고 브라우저마다 임시 번호를 주는 방식입니다.
    빌드›Authentication›로그인 방법›익명›사용 설정
  4. 설정값 가져오기. 웹 앱을 추가하면 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 프로젝트ID
이렇게 되면 성공https://프로젝트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 없이 올렸습니다. 빌드 후 다시 배포합니다

해결되지 않으면 저장소 이슈에 어느 단계에서 막혔는지 남겨 주세요.

함께 지킬 약속

저장소에 넣지 않는 것

  • 학생과 교직원의 실명, 학번, 생년월일, 연락처, 얼굴 사진, 명렬표
  • 학교 설계 도면, 배치도 원본, 항공사진, 로드뷰 캡처
  • Firebase 서비스 계정 키와 .env 같은 비밀값

만들지 않는 것

  • 글을 자유롭게 입력하는 칸. 익명 입력창은 학교에서 사고로 이어질 수 있습니다
  • 로그인, 회원가입, 학번 입력
  • 실제 학생과 교직원을 본뜬 등장인물

기원 공간을 남긴다면 "학교의 실제 시설이 아닌 가상 공간" 표기를 유지합니다.