02 TRACK 02 / BUILD & SHIP

만들기

만들고자 하는 내용을 한국어로 설명하면 Claude가 코드를 작성하고 작업 저장소(GitHub)에 저장합니다. 아래 4단계는 초보자용 웹 인터페이스를 기준으로 하며, 터미널·IDE로 작업해도 됩니다.

박사모를 쓴 척척박사 기상이
Step 1 — 웹 Claude Code 시작하기
저장소는 개발용 작업 공간입니다

웹 Claude Code를 GitHub 저장소에 연결하여 동작하는 것을 가정하여 설명합니다. 이 저장소는 개발용 작업 공간이며 반드시 최종 소스는 GitHub이 아닌 구글 폼에 업로드합니다.

1

GitHub 저장소 먼저 만들기

  1. github.com 로그인 후 우측 상단 + → New repository
  2. 이름 입력(예: weather-project) — 공개/비공개(Public/Private)는 자유롭게 선택
  3. Create repository 클릭
저장소 이름은 이후 Vercel 주소가 되므로, 팀 프로젝트 이름으로 지어 두면 좋습니다.
2

claude.ai/code 접속 후 GitHub 연결

  1. claude.ai/code 접속 → 제공받은 계정으로 로그인
  2. 입력창 아래쪽의 "+ 레포 선택..." 버튼 클릭
  3. 목록에서 방금 만든 저장소(예: weather-project) 선택
  4. 선택이 끝나면 버튼 자리에 저장소 이름과 브랜치 이름이 표시됩니다. 브랜치 이름은 계정 설정에 따라 main 또는 master로 보일 수 있으며, 둘 다 '기본 브랜치'라는 같은 의미이므로 그대로 두면 됩니다.
레포 선택 전 — 입력창 아래 '+ 레포 선택...' 버튼이 보이는 화면
레포 선택 전 — 입력창 아래 "+ 레포 선택..." 버튼을 클릭하세요.
레포 선택 후 — 저장소 이름과 브랜치 이름이 버튼 자리에 표시되는 화면
레포 선택 후 — 저장소 이름과 브랜치 이름(main 또는 master)이 표시되면 연결 완료.
이 연결을 한 번 해 두면 이후 Claude Code가 코드를 작성할 때마다 GitHub에 자동으로 저장합니다.
!

연결·Push 에러가 날 때 (개인·팀 공통)

저장(푸시)하거나 새 브랜치를 올릴 때 "Permission denied (publickey)" 에러가 나거나 저장소 목록이 보이지 않을 수 있습니다. 웹 Claude Code는 개인 SSH 키를 쓰지 않고 Claude GitHub App(github.com/apps/claude) 연결로 인증하므로, 이 에러는 대부분 App 설치·권한 문제입니다. 혼자 작업할 때도 동일하게 발생할 수 있습니다.

GitHub App 설치·권한 확인하기

  1. GitHub 프로필 → Settings → Applications → Installed GitHub Apps
  2. Claude(연결된 App) 옆 Configure 클릭
  3. Repository access에 작업 중인 저장소가 포함됐는지 확인 (없으면 Select repositories로 추가)
  4. 권한에서 Contents: Read and write, Pull requests: Read and write 허용 확인
  5. claude.ai/code로 돌아와 "+ 레포 선택..."으로 저장소를 다시 선택
핵심 웹 환경에서는 SSH 키를 직접 만들거나 바꿀 필요가 없습니다. "SSH"·"publickey"가 보여도, 해결은 항상 GitHub App 설치 화면에서 저장소·권한 다시 확인입니다.
Step 2 — Claude Code로 만들기
3

자연어로 요청하면 코드가 작성됩니다

요청할 때 (1) 무엇을 보여줄지 (2) 어떻게 조작할지 (3) 파일 이름(index.html), 이 세 가지만 포함하면 됩니다.

예시 대화
기온과 풍속 슬라이더로 체감온도를 보여주는 웹페이지를 index.html 하나로 만들어 줘. 기상청 체감온도 공식을 사용해 줘.
슬라이더를 움직이면 체감온도가 실시간으로 바뀌는 index.html을 만들었습니다. GitHub에 저장했습니다.
배경색을 하늘색으로 바꾸고, 모바일에서도 잘 보이게 해 줘.
배경색과 반응형 레이아웃을 적용했습니다. 변경 사항을 GitHub에 저장했습니다.
Step 3 — CLAUDE.md 설정하기
4

프로젝트 규칙서, CLAUDE.md

CLAUDE.md는 Claude Code가 프로젝트를 열 때 가장 먼저 읽는 파일입니다. 여기에 적어 둔 규칙은 매 대화마다 자동으로 적용됩니다. "파일 이름은 index.html로 고정", "한국어로 응답" 같은 규칙을 넣어 두면 매번 설명할 필요가 없습니다.

  1. 아래 CLAUDE.md 내용을 전체 복사합니다.
  2. Claude Code에 붙여넣으며 "이 내용으로 저장소 최상단에 CLAUDE.md 파일을 만들어 줘"라고 요청합니다.
  3. Claude가 파일을 생성해 GitHub에 저장합니다.
파일 이름은 반드시 CLAUDE.md(대문자)이며, 위치는 저장소 최상단 폴더입니다.
CLAUDE.md (예시)# CLAUDE.md ## 교육 목표 콘텐츠를 추가·수정할 때는 PLAN.md에 작성한 학습 대상·목표에 부합하는지 먼저 확인합니다. 코드나 콘텐츠가 계획과 어긋나면 코드보다 계획을 먼저 갱신하고 작업합니다. ## 표절 및 아이디어 중복 방지 새 기능·UI·컨셉을 추가하기 전, 유사한 기상 교육 콘텐츠와 이번 해커톤 타 팀의 공개 자료를 확인합니다. 유사한 아이디어가 이미 존재한다면 그대로 재현하지 말고, 데이터 활용 방식·구성·인터랙션의 차별점을 명시적으로 설계합니다. ## 라이선스 및 저작권 외부 리소스(폰트, 라이브러리, 이미지, 데이터셋)를 추가할 때는 라이선스 종류와 교육·해커톤 용도 허용 여부를 먼저 확인합니다. 각 리소스의 출처·라이선스는 README.md에 기록합니다. 저작권이 불명확한 소재는 확인 전까지 사용하지 않습니다. ## 보안 — API 키 유출 방지 API 키는 HTML·JS 소스코드에 직접 쓰지 않습니다. 키를 코드에 넣었다면 GitHub에 올리기 전에 반드시 제거합니다. 최종 제출 시에는 반드시 본인 개인 계정으로 발급받은 개인용 API 키를 사용합니다.
Step 4 — Vercel로 배포하기
5

GitHub로 로그인 후 프로젝트 가져오기

  1. vercel.com 접속 → Continue with GitHub
  2. Add New → Project 클릭
  3. 방금 만든 저장소 선택 → Import
6

Framework Preset 설정

Import 직후 설정 화면에서 Framework Preset을 선택합니다. 이 가이드처럼 index.html을 직접 만든 경우에는 Other를 선택하면 됩니다. 별도 빌드 과정이 없기 때문입니다.

주의 Preset이 맞지 않으면 빌드가 실패할 수 있습니다. index.html을 직접 만들었다면 반드시 Other입니다.
7

배포 후 링크 받기

  1. 설정 확인 후 Deploy 클릭
  2. 1~2분 뒤 weather-project.vercel.app 같은 주소가 생성됩니다
  3. 이 주소가 구동 URL(제출 항목 ①)입니다
참고 GitHub에서 index.html을 수정하면 Vercel이 자동으로 다시 배포하므로, 별도로 재배포할 필요가 없습니다.
배포 후 확인

다른 컴퓨터에서도 링크가 열리는지, 슬라이더 등 인터랙티브 기능이 정상 작동하는지 확인하세요. 구동 환경은 크롬 브라우저 기준이며, 1366×768·1920×1080·2560×1440 해상도에서 정상 표시되어야 합니다.

기상청 API key 사용 규정

기상청 API는 개인용 API key만 사용합니다. 개인용 API key는 횟수 제한 없이 개발·테스트하기 위해 제공되며 8월 22일까지 유효합니다. 단, 최종 제출 시 소스코드와 URL에는 반드시 본인 개인 계정으로 발급받은 API key를 사용해야 하며, 개인용 API key는 절대 제출하면 안 됩니다.