Earthssaem Lab · 바이브 코딩 제작 가이드
🌍 지구과학 교사를 위한 단계별 안내

바이브 코딩 제작 방법

코드를 몰라도 괜찮습니다. AI와 충분히 대화하며 수업에 딱 맞는 교육용 웹앱을 직접 만들고,
학생들과 공유하는 두 가지 방법을 단계별로 안내합니다.

Intro

바이브 코딩이 뭔가요?✦

코드를 한 줄씩 직접 타이핑하는 대신, "이런 것을 만들고 싶어"라고 AI에게 말로 설명하고 AI가 코드를 만들게 하는 방식입니다. 우리는 '무엇을 만들지'와 '잘 만들어졌는지'에 집중하고, '어떻게 코드로 쓰는지'는 AI에게 맡깁니다.

🧑‍🏫

교사에게 좋은 이유

시중 자료가 우리 반 수업 흐름과 딱 맞는 경우는 드뭅니다. 판의 경계 시뮬레이션, 암석 분류 활동처럼 내 수업에 맞는 도구를 그날 바로 만들 수 있습니다.

🧩

필요한 것

AI 채팅 계정(Gemini·ChatGPT·Claude 중 하나)과 만들고 싶은 것에 대한 구체적인 생각이면 충분합니다. 방법 2는 GitHub 계정이 추가로 필요합니다. (Vercel로 배포하면 Vercel 계정도 필요)

💡

성공의 열쇠

좋은 결과물은 좋은 코드가 아니라 좋은 대화에서 나옵니다. 바로 코드를 시키지 말고 먼저 대화로 기획을 구체화하세요. 아래 핵심 원칙에서 자세히 다룹니다.

두 가지 방법 한눈에 비교

👉 표를 옆으로 밀어서 볼 수 있어요

항목방법 1 · 채팅으로 바로 만들기방법 2 · 코드 만들어 배포하기
난이도★☆☆ 매우 쉬움★★☆ 처음 한 번만 익히면 쉬움
준비물AI 채팅 계정AI 채팅 계정 + GitHub 계정 (Vercel로 배포하면 Vercel 계정 추가)
소요 시간10~20분30~40분 (두 번째부터는 10분)
공유 방법AI 서비스가 만들어 준 링크나만의 주소 (예: 사용자이름.github.io/my-app, my-app.vercel.app)
수정하기같은 채팅에서 바로 수정코드를 고쳐 GitHub에 올리면 자동 재배포
주의할 점서비스 정책에 따라 로그인이 필요하거나 링크가 만료될 수 있음처음 계정 만들기와 연결 과정이 낯설 수 있음
이럴 때 추천오늘 수업에 바로 쓸 간단한 도구, 일회성 활동여러 반·여러 해에 걸쳐 오래 쓸 도구, 동료와 공유할 자료
Key Principle

핵심 원칙 · 코드보다 대화가 먼저입니다✦

어떤 방법을 쓰든 가장 중요한 단계입니다. AI에게 첫 메시지를 보낼 때 이 한 문장을 꼭 넣으세요.

첫 메시지에 꼭 넣을 말
바로 코드를 짜지 말고, 먼저 나와 충분히 대화하면서 무엇을 만들지 구체화한 다음에 코드를 짜줘
AI가 질문을 던지고, 내가 답하면서 기획이 저절로 구체화됩니다.

😵 바로 코드를 시키면

  • AI가 모호한 부분을 자기 마음대로 채웁니다. (대상 학년, 용어, 화면 구성…)
  • 결과물을 보고 나서야 "이게 아닌데"를 깨닫습니다.
  • 고치는 요청을 반복하다 코드가 꼬이고, 처음부터 다시 만들게 됩니다.

😊 대화로 먼저 구체화하면

  • AI가 내가 미처 생각 못한 것을 질문해 줍니다. (스마트폰 지원? 퀴즈 채점?)
  • 내 머릿속 그림이 글로 정리되어, 나중에 수정 요청도 쉬워집니다.
  • 한 번에 원하는 것에 가까운 결과가 나와 시간이 절약됩니다.

대화로 구체화하는 3단계

1단계

대화를 요청한다

만들고 싶은 것을 한두 문장으로 말하고, "바로 코드를 짜지 말고 먼저 질문해 줘"라고 덧붙입니다.

2단계

AI의 질문에 답한다

대상 학년, 학습 목표, 기능, 화면, 사용 환경을 정합니다. 모르면 "네가 추천해 줘"라고 해도 됩니다.

3단계

요약을 확인하고 코드를 요청한다

AI가 정리한 기획 요약을 읽고 빠진 것을 보충한 뒤, "좋아, 이제 코드를 짜줘"라고 말합니다.

예시 대화 · 암석의 분류 학습 웹앱

실제로 이렇게 흘러갑니다. 파란색은 선생님, 회색은 AI입니다.

선생님고등학교 지구과학 수업에서 쓸 암석의 분류 학습 웹앱을 만들고 싶어. 바로 코드를 짜지 말고, 먼저 나에게 질문하면서 무엇을 만들지 충분히 구체화한 다음에 코드를 짜줘.
AI좋습니다! 코드를 짜기 전에 몇 가지 여쭤볼게요.
  1. 대상 학년과 학생들의 사전 지식은 어느 정도인가요? (암석의 순환, 광물은 배운 상태인가요?)
  2. 화성암·퇴적암·변성암을 모두 다루나요? 화성암은 조직(화산암·심성암)과 화학 조성(염기성·산성)으로 세분하나요?
  3. 학생이 어떤 활동을 하길 원하시나요? (암석 카드를 분류표에 드래그해 넣기, 사진 보고 이름 맞히기, 분류 기준 고르기 등)
  4. 실제 암석 사진을 쓸까요, 그림과 설명 카드로 대신할까요?
  5. 마지막에 퀴즈나 정리 활동을 넣을까요?
  6. 주로 어떤 기기에서 사용하나요? (교실 TV, 태블릿, 스마트폰)
선생님1. 고2 지구과학 선택 학생, 암석의 순환과 조암 광물은 배웠어. 2. 세 종류 다 다루고, 화성암은 조직×조성 2×2 표(현무암·반려암·유문암·화강암)로 세분해 줘. 3. 암석 카드를 드래그해서 분류표 칸에 넣는 활동으로, 틀리면 다시 놓을 수 있게. 4. 사진 없이 색·조직·구성 광물을 적은 설명 카드로. 5. 마지막에 5문제 퀴즈, 정답 여부 바로 표시. 6. 태블릿과 스마트폰에서도 잘 보이게, 전부 한국어로.
AI정리하면 이렇습니다.
  • 대상: 고2 지구과학, 암석의 순환·조암 광물 학습 후
  • 활동 1: 암석 카드 12장을 화성암·퇴적암·변성암 상자에 드래그해 분류 (틀리면 흔들리며 되돌아감)
  • 활동 2: 화성암 4장(현무암·반려암·유문암·화강암)을 조직(화산암/심성암)×조성(염기성/산성) 2×2 표에 배치
  • 카드 내용: 암석 이름은 숨기고 색·조직·주요 광물·생성 환경 설명만 표시
  • 퀴즈: 5문항 객관식, 즉시 채점과 해설
  • 환경: 반응형(태블릿·스마트폰), 한국어, HTML 파일 1개
추가로 활동을 마치면 암석의 순환 그림에서 각 암석이 어디에 위치하는지 보여주는 정리 화면을 넣을까요? 이대로 진행할까요?
선생님정리 화면 넣어줘. 좋아, 이제 코드를 짜줘. HTML 파일 하나로 만들어줘.

대화에서 꼭 정해야 할 것 체크리스트

  • 대상 · 학년, 선택 과목, 사전 지식 수준
  • 학습 목표 · 이 웹앱을 쓰고 나면 학생이 무엇을 할 수 있어야 하는가
  • 핵심 기능 · 시뮬레이션, 분류 활동, 퀴즈, 그래프 등 딱 필요한 것만
  • 화면 구성 · 어디에 무엇이 보이는지 (말로 설명하거나 손그림 사진 첨부)
  • 사용 환경 · 교실 TV, 태블릿, 스마트폰 / 인터넷 여부
  • 과학적 정확도 · 교과서 용어와 표기를 따르도록 요청 (예: "2022 개정 교육과정 고등학교 지구과학 용어 사용")
  • 형식 · "HTML 파일 하나로", "외부 로그인 없이", "한국어로"
Method 01

방법 1 · 채팅으로 바로 만들어 링크로 공유하기✦

Gemini, ChatGPT, Claude는 채팅창 안이나 옆에서 만든 웹앱을 바로 실행해 확인할 수 있는 기능을 제공합니다. Gemini는 Canvas, ChatGPT는 Code block·Preview, Claude는 Artifacts입니다. 여기서 만들고, 링크를 만들어 학생에게 보내면 끝입니다. 예시는 암석의 분류 학습 웹앱입니다.

G
Gemini
Canvas (캔버스)
켜는 법
입력창 아래 +(파일 추가) 버튼에서 Canvas 선택 후 요청
공유
캔버스 우측 상단 공유 및 내보내기 → 공유 → 링크 복사
G
ChatGPT
Code block · Preview
켜는 법
채팅창에서 "웹앱을 만들어줘. 미리보기로 바로 확인할 수 있게 만들어줘."라고 요청 → 생성된 코드 블록에서 Preview 선택
공유
지원되는 경우 코드 블록의 공유 버튼 → 읽기 전용 링크 생성
C
Claude
Artifacts (아티팩트)
켜는 법
설정 → 기능(Capabilities)에서 코드 실행 및 파일 생성 켜기 (보통 기본으로 켜져 있음) → 웹앱을 요청하면 오른쪽에 아티팩트 화면이 열림
공유
아티팩트 우측 상단 공유(Share) → 링크가 있는 모든 사용자 선택 → 링크 복사. 학생에게 보내기 전 로그인 없이 열리는지 확인
ℹ️ 메뉴 이름과 위치는 자주 바뀝니다

서비스 업데이트에 따라 버튼 이름이 조금씩 달라질 수 있습니다. 채팅창에 "바로 실행해 볼 수 있는 웹앱으로 만들어줘", "미리보기로 확인할 수 있게 만들어줘", "이 앱을 공유할 수 있는 링크를 만들어줘"라고 말로 요청해도 됩니다.

ℹ️ 공유 기능이 안 보일 수 있습니다

계정·환경에 따라 공유 기능이 표시되지 않을 수 있습니다. 특히 Google Workspace, ChatGPT Edu/Team, Claude Team/Enterprise 같은 학교·기관 계정은 관리자 설정의 영향을 받습니다.

진행률
0/5
1

도구를 고르고 미리보기 기능을 확인합니다

  1. Gemini, ChatGPT, Claude 중 이미 계정이 있는 것을 고릅니다. 셋 다 처음이라면 어느 것이든 좋습니다.
  2. 새 채팅을 열고 위 카드를 참고해 웹앱을 바로 실행해 볼 수 있는 기능(Canvas, Preview, Artifacts)을 확인합니다.
  3. 스마트폰보다는 컴퓨터 브라우저에서 작업하는 것이 훨씬 편합니다.
💡 팁

무료 요금제로도 충분히 만들 수 있습니다. 다만 하루 사용량 제한이 있으니 긴 대화는 한 번에 끝내는 것이 좋습니다.

2

대화로 무엇을 만들지 구체화합니다

가장 중요한 단계입니다. 첫 메시지를 아래처럼 보내고, AI의 질문에 차근차근 답합니다. (핵심 원칙의 예시 대화 참고)

첫 메시지 · 복사해서 빈칸만 채우세요
나는 [고등학교 2학년] 학생을 가르치는 지구과학 교사야.
[암석의 분류를 학습하는] 교육용 웹앱을 만들고 싶어.

바로 코드를 짜지 말고, 먼저 나에게 질문하면서 무엇을 만들지 충분히 구체화한 다음에 코드를 짜줘.
대상 학생, 학습 목표, 핵심 기능, 화면 구성, 사용 기기 등 네가 알아야 할 것을 한 번에 5~6개씩 질문해 줘.
기획이 정리되면 요약을 보여주고 내 확인을 받은 뒤에 코드를 짜줘.
  • AI 질문에 모두 답하지 않아도 됩니다. 모르는 것은 "네가 추천해 줘"라고 답하세요.
  • AI가 보여준 요약을 꼼꼼히 읽고, 다르게 이해한 부분은 바로잡아 줍니다.
3

"이제 코드를 짜줘" · 미리보기 확인

요약이 마음에 들면 코드 생성을 요청합니다. 미리보기 화면에 웹앱이 바로 실행되어 나타납니다.

코드 요청
좋아, 정리한 내용대로 이제 코드를 짜줘.
HTML 파일 하나에 CSS와 JavaScript를 모두 넣어서 만들어줘. 외부 로그인이나 서버 없이 브라우저에서 바로 실행되어야 해.
미리보기로 바로 확인할 수 있게 만들어줘. 스마트폰과 태블릿에서도 잘 보이게 만들어줘.
  • 미리보기에서 학생처럼 직접 눌러 봅니다. 카드 드래그, 퀴즈, 정리 화면이 의도대로 동작하는지 확인합니다.
  • 과학적 내용(용어, 분류 기준, 광물 조성)이 정확한지 교사의 눈으로 검토합니다. AI는 그럴듯하게 틀릴 수 있습니다.
4

수정을 요청합니다 (구체적으로, 한 번에 하나씩)

마음에 안 드는 부분을 어디가 · 어떻게 형태로 말합니다. "더 좋게 해줘"보다 "퀴즈 정답을 고르면 초록색으로 표시해 줘"가 훨씬 잘 됩니다.

수정 요청 예시
다음 세 가지를 수정해 줘. 다른 부분은 그대로 유지해.
1. 화강암 카드를 '화산암' 칸에 놓아도 정답으로 처리돼. 화강암은 심성암이니까 '심성암·산성' 칸에서만 정답이 되게 고쳐줘.
2. 퀴즈에서 정답을 고르면 초록색, 오답이면 빨간색으로 표시하고 간단한 해설을 보여줘.
3. 카드 글자 크기를 조금 키워줘. 태블릿에서 보기 편하게.
⚠️ 수정이 꼬이기 시작하면

여러 번 고치다 이상해지면 "지금까지 정리한 기획을 바탕으로 처음부터 다시 깔끔하게 만들어 줘"라고 요청하세요. 대화로 구체화해 둔 기획이 있으니 금방 다시 만들어 줍니다.

5

링크를 만들어 학생에게 공유합니다

  1. 아티팩트 화면 우측 상단의 공유(Share) 버튼을 누릅니다.
  2. 접근 권한(Who has access)을 링크가 있는 모든 사용자(Anyone with the link)로 바꾸고 링크를 복사합니다.
  3. 이렇게 공유한 아티팩트는 대부분 로그인 없이 열립니다. 다만 아티팩트에 따라 로그인해야 내용이 보이거나, Claude AI를 쓰는 기능이 동작하지 않을 수 있습니다. 학생에게 보내기 전에 시크릿 창에서 로그인 없이 열리고 제대로 실행되는지 확인하세요.
  4. 로그인이 필요하거나 실행이 제한된다면 코드를 복사(또는 다운로드)해 방법 2로 배포합니다. Claude는 만 18세 이상만 가입할 수 있어 학생 대부분은 로그인할 수 없습니다.
  5. 채팅에서 만든 예전 아티팩트에는 공유 대신 게시(Publish) 버튼이 보일 수 있습니다. 게시한 링크는 Claude 계정 없이 열 수 있고, Claude AI를 쓰는 기능을 쓸 때만 가입을 요청받습니다.
  1. 코드 블록(또는 Preview 화면)의 공유 버튼을 누르면 읽기 전용 링크가 만들어집니다. 버튼이 있는지, 받는 사람이 링크에서 앱을 바로 실행할 수 있는지는 계정·환경에 따라 다릅니다.
  2. 채팅 상단의 공유로 만드는 링크는 AI와 나눈 대화를 공유하는 것입니다. 웹앱을 따로 배포하는 기능과는 다릅니다.
  3. 링크를 만들었다면 시크릿 창에서 로그인 없이 앱이 실행되는지 확인합니다. 공유 버튼이 없거나 실행이 제한되면 코드 블록을 복사해 방법 2로 배포합니다.
  4. 계정에 따라 웹사이트를 게시하는 Sites 기능이 보일 수도 있습니다. 이용할 수 있는 요금제와 공개 범위는 계정마다 다르니 화면 안내를 확인하세요.
  1. 캔버스 화면 우측 상단의 공유 및 내보내기 → 공유를 누릅니다.
  2. 만들어진 공개 링크 옆 링크 복사를 누릅니다.
  3. 학교 Google Workspace(교육용) 계정이라면 캔버스의 Classroom에 공유 버튼으로 Google Classroom 수업에 바로 올릴 수 있습니다.
  4. 공유가 어렵다면 캔버스 코드를 복사해 방법 2로 배포합니다.
⚠️ 학생에게 보내기 전에 꼭 확인

내 계정에서 로그아웃한 브라우저(또는 시크릿 창, 스마트폰)로 링크를 열어 보세요. 로그인 없이 열리는지, 학생 기기에서 잘 보이는지 확인한 뒤 공유합니다. 학생이 열 수 없다면 방법 2로 배포하면 확실합니다.

🎉 완성!

QR코드 생성 사이트에 링크를 넣어 QR을 만들면 학생들이 스마트폰으로 바로 접속할 수 있습니다.

Method 02

방법 2 · 코드를 만들어 GitHub에 저장하고 배포하기✦

AI가 만든 코드를 GitHub(코드 보관소)에 저장하고, GitHub Pages나 Vercel(배포 서비스)로 그 코드를 인터넷에 공개합니다. 한 번 연결해 두면 코드를 고칠 때마다 자동으로 새 버전이 올라갑니다. 예시는 판의 경계 시뮬레이션입니다.

💬
AI와 대화코드 작성
→
📁
GitHub저장 · 버전 관리
→
🚀
Pages · Vercel배포 · 주소 발급
→
🌐
완성!나만의 웹 주소

📁 GitHub란?

코드를 저장하고 변경 이력을 관리하는 서비스입니다. 구글 드라이브의 '코드 전용 버전'이라고 생각하면 됩니다. 저장 단위를 저장소(repository)라고 부릅니다.

🚀 GitHub Pages · Vercel이란?

GitHub 저장소의 코드를 인터넷에 공개해 주는 배포 서비스입니다. GitHub Pages는 GitHub에 들어 있는 기능이라 따로 가입하지 않아도 되고, 사용자이름.github.io/저장소이름 주소를 줍니다. Vercel은 이름.vercel.app 주소를 주고 더 다양한 프로젝트를 배포할 수 있습니다. GitHub Pages는 공개 저장소라면 무료이고, Vercel은 개인·비상업용 무료 플랜(Hobby)이 있습니다. 둘 다 코드가 바뀌면 자동으로 다시 배포합니다.

🎒 준비물

  • AI 채팅 계정 (Gemini·ChatGPT·Claude)
  • GitHub 계정 (무료)
  • Vercel 계정 (Vercel로 배포할 때만 · GitHub 계정으로 가입, 개인용 무료 플랜 있음)
진행률
0/5
1

대화로 무엇을 만들지 구체화합니다

방법 1과 완전히 같습니다. 미리보기 기능 없이 일반 채팅으로 해도 됩니다. 핵심 원칙의 흐름대로 첫 메시지를 보내고, AI의 질문에 답하며 기획을 정리하세요.

첫 메시지
나는 [고등학교 2학년] 학생을 가르치는 지구과학 교사야.
[판의 경계에서 일어나는 지각 변동을 탐구하는 시뮬레이션] 교육용 웹앱을 만들고 싶어.

바로 코드를 짜지 말고, 먼저 나에게 질문하면서 무엇을 만들지 충분히 구체화한 다음에 코드를 짜줘.
대상 학생, 학습 목표, 핵심 기능, 화면 구성, 사용 기기 등 네가 알아야 할 것을 한 번에 5~6개씩 질문해 줘.
기획이 정리되면 요약을 보여주고 내 확인을 받은 뒤에 코드를 짜줘.
ℹ️ 판의 경계 시뮬레이션이라면 이런 것을 정하게 됩니다

발산형·수렴형(해양-대륙, 해양-해양, 대륙-대륙)·보존형 경계 중 무엇을 다룰지, 판의 이동 속도를 슬라이더로 조절할지, 단면도에 맨틀 대류·마그마·지진 발생 위치를 표시할지, 실제 예시 지형(동아프리카 열곡대, 안데스 산맥, 히말라야 산맥, 산안드레아스 단층)을 넣을지 등입니다.

2

코드를 만들고 내 컴퓨터에 index.html로 저장합니다

코드 요청 · 파일 하나로
좋아, 정리한 내용대로 이제 코드를 짜줘.
index.html 파일 하나에 HTML, CSS, JavaScript를 모두 넣어서 만들어줘.
서버나 로그인 없이 브라우저에서 바로 열리는 정적 웹페이지여야 하고, 스마트폰에서도 잘 보이게 해줘.
완성된 코드 전체를 하나의 코드 블록으로 보여줘.
  1. AI가 보여준 코드 블록 우측 상단의 복사 버튼을 누릅니다. (Canvas·Artifacts라면 다운로드 메뉴를 써도 됩니다.)
  2. 컴퓨터에서 메모장(Windows) 또는 텍스트 편집기(Mac)를 열고 붙여넣습니다. Mac 텍스트 편집기는 먼저 포맷 → 일반 텍스트로 만들기(Cmd+Shift+T)를 눌러 일반 텍스트로 바꿉니다.
  3. 다른 이름으로 저장 → 파일 이름을 정확히 index.html로, 인코딩은 UTF-8로 저장합니다. (메모장에서 파일 형식을 '모든 파일'로 바꿔야 .txt가 붙지 않습니다. Mac에서 확장자를 물으면 .html을 사용하도록 고릅니다.)
  4. 저장한 파일을 더블클릭하면 브라우저에서 열립니다. 판이 움직이는지, 경계를 바꾸면 단면도가 바뀌는지 확인합니다.
💡 왜 파일 하나로 만드나요?

파일이 하나면 GitHub에 올리고 관리하기가 가장 쉽습니다. 파일 이름이 index.html이어야 주소만 입력해도 그 페이지가 열립니다. 한글이 깨지면 "UTF-8로 저장했는지" 먼저 확인하세요.

3

GitHub에 저장소를 만들고 파일을 올립니다

  1. github.com에 로그인하고, 우측 상단 + → New repository를 누릅니다.
  2. Repository name에 영문 이름을 입력합니다. 예: plate-boundary-sim (띄어쓰기 대신 - 사용)
  3. Public을 선택하고 Create repository를 누릅니다. 다른 설정은 건드리지 않아도 됩니다.
  4. 새 저장소 화면에서 uploading an existing file 링크를 누릅니다. (파일이 이미 있는 저장소라면 Add file → Upload files를 누릅니다.)
  5. 2단계에서 저장한 index.html을 드래그해서 놓습니다.
  6. 아래 Commit changes 버튼을 누릅니다. 이제 코드가 GitHub에 저장되었습니다.
⚠️ Public 저장소는 누구나 볼 수 있습니다

Public 저장소는 누구나 코드를 볼 수 있으므로 학생 개인정보, 비밀번호, API 키 등 민감한 정보를 업로드하지 마세요.

ℹ️ 커밋(commit)이란?

"이 상태로 저장" 버튼입니다. 파일을 올리거나 고칠 때마다 커밋을 하며, 모든 커밋 이력이 남아 언제든 이전 버전으로 돌아갈 수 있습니다. 이것이 버전 관리입니다.

4

GitHub Pages 또는 Vercel로 배포합니다

저장소의 코드를 인터넷 주소로 공개합니다. 이 가이드처럼 index.html 하나로 만든 웹앱은 GitHub Pages로 바로 배포할 수 있습니다. 더 다양한 기능이 필요해지면 Vercel을 씁니다.

아래 순서는 index.html 파일 하나로 만든 웹앱 기준입니다.

  1. 3단계에서 만든 저장소 화면 상단의 ⚙️ Settings를 누릅니다.
  2. 왼쪽 메뉴에서 Pages를 누릅니다.
  3. Build and deployment의 Source에서 Deploy from a branch를 선택합니다.
  4. Branch는 main, 폴더는 / (root)를 선택합니다.
  5. Save를 누릅니다.
  6. 1~2분(길면 10분) 기다린 뒤 새로고침하면 위쪽에 배포 주소가 나옵니다. Visit site를 눌러 확인하고, 주소를 복사합니다. 예: https://사용자이름.github.io/plate-boundary-sim/
💡 배포 주소 형식

https://사용자이름.github.io/저장소이름/ 형식입니다. 주소는 언제든 저장소의 Settings → Pages에서 다시 확인할 수 있습니다.

ℹ️ GitHub Pages는 정적 웹사이트 배포 서비스입니다

올린 HTML·CSS·JavaScript 파일을 그대로 보여 줄 뿐, 서버에서 코드를 실행하거나 데이터를 저장하지 않습니다. 무료 계정은 저장소가 Public이어야 합니다. React·Vite 프로젝트는 별도의 빌드와 경로(base) 설정이 필요하니, AI에게 "GitHub Pages로 배포할 수 있게 설정해 줘"라고 요청하세요. 자세한 내용은 GitHub Pages 공식 문서를 참고합니다.

GitHub Pages보다 다양한 프로젝트를 배포할 수 있습니다. React·Vite처럼 빌드가 필요한 프로젝트를 자동으로 빌드하고, 서버리스 함수나 API 연동이 필요한 경우에도 활용할 수 있습니다.

  1. vercel.com에서 Sign Up → Continue with GitHub로 가입·로그인합니다. (개인 사용은 Hobby 무료 요금제)
  2. 대시보드에서 Add New… → Project를 누릅니다. (화면에 따라 New Project 버튼으로 보입니다.)
  3. GitHub 저장소 목록에서 방금 만든 저장소 옆 Import를 누릅니다. 목록에 없으면 Adjust GitHub App Permissions로 접근 권한을 허용합니다.
  4. 설정 화면은 아무것도 바꾸지 않고 Deploy를 누릅니다. (Framework Preset은 'Other'로 두면 됩니다.)
  5. 1분 정도 기다리면 🎉 축하 화면과 함께 주소가 나옵니다. Visit을 눌러 확인하고, 주소를 복사합니다. 예: https://plate-boundary-sim.vercel.app
💡 주소를 예쁘게 바꾸려면

Vercel 프로젝트의 Settings → Domains에서 원하는이름.vercel.app으로 바꿀 수 있습니다. (이미 누가 쓰는 이름은 안 됩니다.)

🎉 완성!

이 주소는 계속 유지됩니다. QR코드로 만들어 수업 자료에 넣어 두세요.

5

수정하기 · 고치면 자동으로 다시 배포됩니다

수업하다 보면 고칠 것이 생깁니다. 처음부터 다시 할 필요 없이 파일만 바꾸면 됩니다.

  1. AI 채팅으로 돌아가 수정을 요청합니다. "다른 부분은 그대로 두고 수렴 경계에 지진 발생 위치(베니오프대)만 추가해서, 전체 코드를 다시 보여줘."
  2. 새 코드 전체를 복사합니다.
  3. GitHub 저장소에서 index.html을 클릭 → 우측 상단 ✏️ (Edit) 연필 아이콘을 누릅니다.
  4. 기존 내용을 전체 선택(Ctrl+A, Mac은 Cmd+A)해 지우고 새 코드를 붙여넣습니다.
  5. Commit changes… → 무엇을 바꿨는지 짧게 적고(예: "베니오프대 표시 추가") → Commit changes.
  6. GitHub Pages나 Vercel이 변경을 감지해 자동으로 다시 배포합니다. 1~2분 뒤 같은 주소를 새로고침하면 반영되어 있습니다.
⚠️ 바뀐 게 안 보여요

브라우저가 이전 화면을 기억하고 있을 수 있습니다. Ctrl+Shift+R(Mac은 Cmd+Shift+R, 강력 새로고침) 또는 시크릿 창으로 열어 보세요. 배포 상태도 확인합니다. GitHub Pages는 저장소의 Actions 탭에 초록색 체크(✓)가 떴는지, Vercel은 대시보드의 Deployments에서 배포 상태가 Ready인지 봅니다.

선택 심화 과정

기본 5단계가 익숙해진 뒤 필요할 때 보세요. 진행률에는 들어가지 않습니다.

+

Claude Code, Codex로 자동화하기

선택

위 과정이 익숙해지면, AI가 코드 작성부터 GitHub 저장까지 직접 하게 할 수 있습니다. 복사·붙여넣기가 사라집니다.

코딩 에이전트가 해주는 일

  • 내 컴퓨터 폴더 연결 · 폴더 안 파일을 직접 읽고 수정
  • GitHub 연결 · 커밋·푸시·PR까지 대신 처리
  • 실행·검증 · 명령어와 테스트를 돌려 실제로 작동하는지 확인
  • 규칙 파일 · 학년·언어 등 프로젝트 조건을 기억
  • 스킬 · 자주 하는 작업 절차를 정해두고 명령 하나로 반복
  • 서브에이전트 · 큰 작업을 여러 AI에게 나누어 수행
  • 외부 서비스 연결(MCP) · Google Drive 등 외부 자료와 연동
  • 이미지 이해 · 손그림이나 오류 화면 캡처를 보고 제작·수정
  • 클라우드 작업 · 긴 작업을 맡겨 두거나 여러 작업을 동시에 진행
항목 CClaude Code CCodex
만든 곳AnthropicOpenAI
쓰는 곳터미널 · VS Code · 데스크톱 앱 · 웹웹 · 데스크톱 앱 · 터미널 · VS Code
규칙 파일CLAUDE.mdAGENTS.md
필요한 구독Claude Pro 이상 유료 플랜ChatGPT 무료 플랜부터 가능 (넉넉히 쓰려면 Plus 이상)
💡 Claude Code에 GitHub를 연결하면 · 말만 하면 저장소까지 반영됩니다

Claude Code는 설치 없이 웹(claude.ai/code)이나 데스크톱·모바일 앱에서도 쓸 수 있습니다. GitHub 계정을 한 번 연결해 두면 5단계의 복사·붙여넣기를 Claude Code가 대신 합니다.

  1. claude.ai/code에 접속해 GitHub 계정을 연결하고, Claude Code가 접근할 저장소를 허용합니다. (처음 한 번만)
  2. 작업할 저장소를 고르고 말로 요청합니다. "수렴 경계에 베니오프대 표시를 추가해 줘."
  3. Claude Code가 파일을 직접 고치고 커밋·푸시합니다. 변경 내용은 먼저 별도의 작업 브랜치에 올라갑니다.
  4. 바뀐 내용을 확인한 뒤 "main에 머지해 줘"라고 하면 main에 반영되고, GitHub Pages나 Vercel이 자동으로 다시 배포합니다.

매번 말하기 번거로우면 저장소의 CLAUDE.md에 "작업이 끝나면 main까지 머지한다"와 같은 규칙을 적어 둡니다.

Claude 채팅에서도 되나요? · 됩니다. GitHub가 연결되어 있으면 Claude 앱의 채팅에서도 "이 저장소를 고쳐서 main에 머지해 줘"라고 요청할 수 있습니다. 다만 계정이나 사용 환경에 따라 채팅에서는 안 될 수 있으니, 그럴 때는 claude.ai/code에서 하면 됩니다. 채팅창의 + → Add from GitHub는 코드를 읽어 오는 첨부 기능이라, 이것만으로는 저장소에 올라가지 않습니다.

⚠️ 병합하기 전에 바뀐 내용을 확인하세요

Claude Code나 Codex가 고친 코드는 보통 작업 브랜치나 PR(Pull request)로 올라옵니다. GitHub의 PR 화면에서 Files changed 탭으로 무엇이 바뀌었는지 확인한 뒤 Merge pull request로 병합하세요.

ℹ️ 어느 쪽을 고를까요?

이미 쓰고 있는 AI 쪽을 고르면 됩니다. Claude를 쓰시면 Claude Code, ChatGPT를 쓰시면 Codex입니다.

ℹ️ 언제 넘어가면 좋을까요?

파일이 여러 개로 늘어나거나, 수정이 잦아지거나, 여러 앱을 관리하게 될 때입니다. 처음에는 방법 2의 5단계까지로 충분합니다. 여기서도 원칙은 같습니다. "바로 코드를 짜지 말고, 먼저 나와 대화해 줘."

자주 겪는 문제

🔍 주소를 열면 404 NOT FOUND

파일 이름이 정확히 index.html인지 확인하세요. index.html.txt, Index.html, index.htm은 안 됩니다. 저장소 첫 화면(최상위)에 파일이 있어야 합니다. GitHub Pages는 첫 배포에 몇 분 걸릴 수 있으니 잠시 뒤 다시 열어 보세요.

⬜ 화면이 하얗게만 나와요

코드가 일부만 복사됐을 가능성이 큽니다. 코드 마지막이 </html>로 끝나는지 확인하고, AI에게 "전체 코드를 처음부터 끝까지 다시 보여줘"라고 요청하세요.

🈳 한글이 깨져요

파일을 UTF-8로 저장했는지 확인하세요. 코드 상단에 <meta charset="UTF-8">이 있는지도 확인합니다.

🤔 오류 메시지를 모르겠어요

오류 화면을 캡처해서 AI에게 붙여넣고 "이 오류가 왜 나는지 설명하고 고쳐줘"라고 하세요. 대부분 바로 해결됩니다.

Prompts

바로 쓰는 프롬프트 모음✦

복사 버튼을 누르고 [노란 빈칸]만 바꿔 쓰세요.

① 시작 · 대화 먼저
나는 [고등학교 2학년] 학생을 가르치는 지구과학 교사야.
[판의 경계에서 일어나는 지각 변동을 탐구하는 시뮬레이션] 교육용 웹앱을 만들고 싶어.

바로 코드를 짜지 말고, 먼저 나에게 질문하면서 무엇을 만들지 충분히 구체화한 다음에 코드를 짜줘.
대상 학생, 학습 목표, 핵심 기능, 화면 구성, 사용 기기 등 네가 알아야 할 것을 한 번에 5~6개씩 질문해 줘.
기획이 정리되면 요약을 보여주고 내 확인을 받은 뒤에 코드를 짜줘.
② 답하기 어려울 때
그 부분은 잘 모르겠어. 지구과학 교육 전문가 입장에서 [고등학생]에게 가장 효과적인 방식을 네가 2~3가지 제안하고 추천 이유를 알려줘. 내가 고를게.
③ 코드 요청
좋아, 정리한 기획대로 이제 코드를 짜줘.
index.html 파일 하나에 HTML, CSS, JavaScript를 모두 넣어서 만들어줘.
서버나 로그인 없이 브라우저에서 바로 열려야 하고, 스마트폰·태블릿에서도 잘 보이게 해줘.
모든 글은 한국어로, 과학 용어는 교과서 표기를 따라줘.
④ 수정 요청
다른 부분은 그대로 유지하고 다음만 수정해 줘.
1. [어디]에서 [무엇]을 [어떻게] 바꿔줘.
2. [어디]에 [무엇]을 추가해 줘.
수정한 뒤 전체 코드를 처음부터 끝까지 다시 보여줘.
⑤ 과학적 검토 요청
이 웹앱의 과학적 내용이 정확한지 지구과학 교사 입장에서 검토해 줘.
잘못된 용어, 방향, 수치, 오개념을 유발할 수 있는 표현이 있으면 목록으로 알려주고, 수정안을 제안해 줘.
특히 [2022 개정 교육과정 고등학교 지구과학 교과서]의 표기와 맞는지 확인해 줘.
⑥ 오류 해결
웹앱을 열었더니 아래와 같은 문제가 생겼어.
[문제 설명 또는 오류 메시지 붙여넣기 / 캡처 첨부]
왜 이런 문제가 생기는지 쉽게 설명하고, 고친 전체 코드를 다시 보여줘.
⑦ 처음부터 다시
수정을 반복하다 보니 코드가 복잡해진 것 같아.
지금까지 우리가 정리한 기획과 수정 사항을 모두 반영해서, 처음부터 깔끔하게 다시 만들어 줘.
만들기 전에 반영할 내용을 목록으로 먼저 보여줘.
FAQ

자주 묻는 질문✦

코딩을 전혀 몰라도 정말 할 수 있나요?
네. 이 가이드의 모든 단계는 코드를 읽거나 쓰지 않습니다. 복사·붙여넣기와 버튼 클릭만 합니다. 중요한 것은 코드 지식이 아니라 "무엇을 만들지" 명확히 말하는 능력이고, 그것은 교사가 가장 잘하는 일입니다.
어떤 AI가 가장 좋은가요?
셋 다 교육용 웹앱을 만들기에 충분합니다. 이미 쓰고 있는 것을 쓰세요. 결과가 마음에 안 들면 같은 기획 요약을 다른 AI에 붙여넣어 비교해 보는 것도 좋은 방법입니다.
무료로 가능한가요?
네. AI 채팅 무료 요금제와 GitHub 무료 계정(GitHub Pages 포함)으로 모두 가능합니다. Vercel도 무료 플랜(Hobby)이 있지만 개인·비상업용이며, 사용량 한도를 넘기거나 상업적으로 쓰려면 유료 플랜이 필요합니다. AI 무료 요금제는 사용량 제한이 있어 긴 작업은 나눠서 하는 것이 좋습니다.
학생 개인정보는 괜찮나요?
이 가이드의 기본 예시는 별도 서버 없이 브라우저에서만 실행되고, 학생 개인정보를 수집하지 않습니다. 다만 브라우저 저장 기능을 쓰거나 외부 서비스와 연동하면 정보가 기기에 저장되거나 외부로 전송될 수 있습니다. 학생 이름·점수 같은 개인정보를 서버에 모으려면 개인정보 수집·이용 동의서를 먼저 받아야 합니다(만 14세 미만은 보호자 동의). 학교의 개인정보 보호 절차에 따른 검토도 필요하니, 처음에는 저장 기능 없이 만드세요.
AI가 만든 내용이 과학적으로 틀릴 수도 있나요?
네, 그럴듯하게 틀릴 수 있습니다. 반드시 교사가 직접 검토하세요. 프롬프트 모음의 "⑤ 과학적 검토 요청"을 쓰면 AI 스스로 점검하게 할 수도 있지만, 최종 확인은 교사의 몫입니다.
방법 1로 만든 것을 나중에 방법 2로 옮길 수 있나요?
네. 미리보기 화면이나 코드 블록에서 코드를 다운로드(또는 복사)해 index.html로 저장한 뒤, 방법 2의 3단계부터 진행하면 됩니다.
동료 교사와 같이 수정하고 싶어요
GitHub 저장소의 Settings → Collaborators에서 동료의 GitHub 계정을 추가하면 함께 파일을 수정할 수 있고, 누가 무엇을 바꿨는지 이력이 남습니다.
손그림이나 캡처 화면도 보여줄 수 있나요?
네. 원하는 화면 구성을 종이에 그려 사진을 찍어 첨부하면 훨씬 정확하게 만들어 줍니다. "이 그림처럼 배치해 줘"라고 말하세요. 다만 다른 사이트를 캡처해 그대로 따라 만들게 하면 디자인·글·이미지를 베끼게 되어 저작권 문제가 생길 수 있습니다. 다른 사이트는 아이디어만 참고하고, 원하는 배치는 손그림이나 말로 설명하세요.