Session 1 추가자료 — Claude Code + GitHub + Vercel 배포 미션

아래 프롬프트 하나를 복사해 Claude Code에 붙여넣으세요. 나머지는 Claude가 물어보며 진행합니다.

대상 세션: Session 1 — Claude Code 첫인상 & 내 업무 지도 그리기 (추가자료) 대상 독자: 비개발자 입문자. 터미널을 오늘 처음 열어보는 사람 기준. 화면 문구 안내: GitHub·Vercel 웹 화면의 버튼 이름과 위치는 서비스 업데이트에 따라 달라질 수 있습니다. 이 문서의 버튼명은 참고용이며, 비슷한 뜻의 버튼을 찾으면 됩니다.

이 자료 쓰는 법

1. 준비물 확인 — GitHub 계정 / Vercel 계정 / Node.js 설치 (시작 전 딱 3가지)
2. 바탕화면에 폴더 만들고, 그 폴더에서 터미널을 열어 claude 실행 — 클릭 순서까지 아래에 다 적어뒀습니다
3. 마스터 프롬프트 붙여넣기 — 이후엔 Claude와 한국어로 대화만 하면 됩니다

코드를 읽을 줄 몰라도 됩니다. 1번과 2번만 손으로 하고, 3번부터는 Claude가 물어보는 말에 답만 하면 됩니다.

목차

• 시작 전 딱 3가지
• 🚀 여기부터 통째로 복사하세요 — 마스터 프롬프트
• 붙여넣은 다음 무슨 일이 벌어지나
• 내가 직접 해야 하는 화면 작업 3개
• 완료 기준과 제출
• 부록 A — 막힐 때 쓰는 보조 프롬프트
• 부록 B — 자주 나는 에러 & 해결
• 부록 C — 수동으로 하고 싶은 사람을 위한 git 명령어
• 부록 D — 보안 주의사항
• 부록 E — 완료 체크리스트
• 참고 링크

시작 전 딱 3가지

1. 계정 2개 + 프로그램 1개

Vercel을 "Continue with GitHub"로 가입해야 나중에 창고를 바로 불러올 수 있습니다. 이메일로 따로 가입하면 연결 단계가 하나 더 늘어납니다.

계정 3개(GitHub / Vercel / Claude)의 아이디·비밀번호를 메모장에 미리 적어두세요. 중간에 로그인 창이 여러 번 뜹니다.

두 가지만 더 확인하세요.

• 로그인이 실제로 되는지 미리 확인. 가입만 해두고 나중에 배포 단계에서 비밀번호가 기억 안 나 막히는 경우가 많습니다. 지금 github.com 과 vercel.com 에 각각 한 번씩 로그인해보세요.
• 하드디스크 여유 공간 1GB 이상. 대시보드 하나를 만드는 데 실제로 약 600MB 를 씁니다(부품 파일이 2만 개 넘게 깔립니다). 용량이 빠듯하면 중간에 설치가 실패합니다.

2. 바탕화면에 폴더 만들고, 그 폴더에서 터미널 열기 — Windows

먼저 안심하고 시작하세요. 잠시 후 검은 창이 하나 열립니다. 이 창은 "마우스 대신 글자로 컴퓨터에 명령을 내리는 창"이고, 이름은 터미널(또는 명령 프롬프트)입니다. 글자를 잘못 입력해도 대부분 "그런 명령 없습니다" 같은 메시지만 나오고 넘어갑니다. 웬만해서는 컴퓨터가 망가지지 않습니다. 겁내지 말고 그대로 따라 하세요.

순서대로 따라 하기

① 바탕화면의 빈 곳에서 마우스 오른쪽 클릭 → 새로 만들기 → 폴더 → 왜? 이번 미션에서 만들 파일들이 한곳에 모이도록, 전용 방을 먼저 만드는 것입니다. 안 만들면 파일이 바탕화면에 흩어집니다.

② 폴더 이름을 my-dashboard 로 입력하고 Enter → 왜? 이름에 한글이나 띄어쓰기를 쓰지 마세요. 폴더 경로에 한글·공백이 들어가면 프로그램이 경로를 잘못 읽어 오류가 나는 경우가 있습니다. 영어 소문자와 하이픈(-)만 쓰는 게 안전합니다.

⚠️ OneDrive를 쓰고 있다면 읽어주세요. 요즘 Windows는 바탕화면이 OneDrive와 자동 동기화되는 경우가 많습니다. 폴더 주소가 C:\Users\내이름\OneDrive\... 로 시작하면 해당됩니다. 이 경우 설치 중 아래 같은 경고가 뜰 수 있습니다. (실제 테스트에서 발생을 확인했습니다.)

code복사

npm warn cleanup [Error: EPERM: operation not permitted, rmdir ...]

OneDrive가 파일을 붙잡고 있어서 생기는 현상입니다. 설치가 끝까지 진행됐다면 무시해도 됩니다. 다만 설치에 2만 개가 넘는 파일이 깔리고 그게 전부 OneDrive에 동기화되므로, 동기화가 느려질 수 있습니다. 설치가 반복해서 실패하면 바탕화면 대신 C:\dev\my-dashboard 처럼 OneDrive 바깥 폴더를 만들어 거기서 다시 시작하세요.

③ 방금 만든 my-dashboard 폴더를 더블클릭해서 엽니다 → 왜? 이 폴더 안에서 터미널을 열어야 하기 때문입니다.

④ 폴더 창 맨 위의 주소창(폴더 경로가 적힌 긴 칸)을 마우스로 한 번 클릭합니다 → 클릭하면 경로 글자가 파랗게 선택된 상태로 바뀝니다. 이 상태가 되어야 다음 단계가 됩니다. → 왜? 이 칸은 주소를 적는 칸이자, 명령어를 입력할 수 있는 칸이기도 합니다.

⑤ 그 상태에서 키보드로 cmd 를 입력하고 Enter → 파랗게 선택돼 있던 경로가 지워지면서 cmd 세 글자만 남고, Enter를 누르면 검은 창이 열립니다. → 왜? 이렇게 열면 지금 보고 있는 폴더 위치에서 터미널이 열립니다. 시작 메뉴에서 그냥 여는 것과 다른 점이 이것입니다.

⑥ 검은 창의 맨 앞줄을 확인합니다 — 여기가 제일 중요합니다 아래처럼 방금 만든 폴더 경로가 적혀 있어야 제대로 된 것입니다.

C:\Users\내이름\Desktop\my-dashboard>

경로 끝이 my-dashboard> 로 끝나면 성공입니다. C:\Windows\System32> 처럼 다른 경로가 보이면 잘못 열린 것이니, 검은 창을 닫고 ③번부터 다시 하세요. → 왜 중요한가? Claude Code는 "지금 터미널이 열려 있는 폴더" 안에서만 작업합니다. 엉뚱한 폴더에서 열면 파일이 엉뚱한 곳에 생깁니다.

⑥-1. (선택) 프로그램이 깔려 있는지 확인 불안하면 claude 를 켜기 전에 아래 두 줄을 한 줄씩 입력하고 각각 Enter를 눌러보세요.

node -v
claude --version

둘 다 v20.11.0 같은 버전 숫자가 나오면 정상입니다. 아무것도 안 나오거나 오류가 뜨면 설치가 안 된 것이니, 설치 후 검은 창을 닫았다가 ③번부터 다시 하세요. → 왜 지금 하나? 다음 단계에서 Claude Code를 켜고 나면, 이 확인 명령을 칠 자리가 사라지기 때문입니다.

⑦ 검은 창에 claude 를 입력하고 Enter → Claude Code가 켜집니다.

알아두면 편한 것

• 붙여넣기: Ctrl + V 로 붙여넣습니다. 명령 프롬프트에서는 마우스 오른쪽 클릭만으로 붙여넣기가 되는 경우도 있습니다. 둘 중 되는 쪽을 쓰면 됩니다.
• 이 검은 창을 끄지 마세요. 미션이 끝날 때까지 계속 이 창에서 작업합니다. 실수로 껐다면 ③~⑦번을 다시 하면 됩니다(작업 내용은 폴더에 남아 있습니다).
• 창이 답답하면 마우스로 창 모서리를 끌어 크게 키우세요.

2-1. macOS를 쓰는 경우

① 바탕화면 빈 곳에서 마우스 오른쪽 클릭(또는 Control + 클릭) → 새로운 폴더 ② 폴더 이름을 my-dashboard 로 입력 (한글·띄어쓰기 금지 — 이유는 Windows와 같습니다)

③ 폴더에서 터미널 열기 — 방법 A (마우스) 만든 폴더를 마우스 오른쪽 클릭 → 서비스 → 폴더에서 새로운 터미널 열기 → 이 메뉴가 안 보이면 켜져 있지 않은 것입니다. 시스템 설정 → 키보드 → 단축키 → 서비스 항목에서 해당 기능을 켠 뒤 다시 시도하세요. → 메뉴 이름과 위치는 macOS 버전에 따라 다를 수 있습니다. 안 보이면 아래 방법 B를 쓰세요.

③ 폴더에서 터미널 열기 — 방법 B (확실한 방법) ⌘ + Space → 터미널 입력 → 터미널 실행 → 아래를 입력하고 Enter

cd ~/Desktop/my-dashboard

cd 는 "이 폴더로 이동" 이라는 뜻입니다. 실행 후 아래를 입력하면 현재 위치가 보입니다.

pwd

/Users/내이름/Desktop/my-dashboard 처럼 나오면 제대로 온 것입니다.

③-1. (선택) 프로그램이 깔려 있는지 확인 — claude 를 켜기 전에 한 줄씩 입력해보세요.

node -v
claude --version

둘 다 버전 숫자가 나오면 정상입니다. 안 나오면 설치 후 터미널을 닫았다가 다시 여세요.

④ claude 입력 후 Enter

• 붙여넣기: ⌘ + V
• 터미널 창을 끄지 마세요. 미션이 끝날 때까지 계속 씁니다.

3. claude 를 실행한 직후

처음 claude 를 실행하면 이런 것들이 나올 수 있습니다.

• 로그인이나 계정 연결을 요청하는 안내
• "이 폴더에서 작업해도 괜찮은지" 확인하는 질문
• 사용 방법을 알려주는 짧은 첫 화면

→ 나오는 안내에 따라 진행하면 됩니다. 대부분 Enter나 "예/신뢰함" 계열 선택으로 넘어갑니다.

초보가 자주 겪는 함정: Claude Code가 켜진 뒤에는 입력한 글이 터미널 명령이 아니라 Claude에게 보내는 말이 됩니다. 그래서 이 상태에서 node -v 같은 걸 쳐도 버전이 뜨지 않고 Claude가 대답을 합니다. 이번 미션에서 터미널 명령을 직접 칠 일은 없으니 신경 쓰지 않아도 됩니다. 명령은 전부 Claude가 알아서 실행합니다.

주의: 위 화면의 정확한 문구·순서·선택지는 Claude Code 버전에 따라 다릅니다. 이 문서를 만들 때 실제 화면을 캡처해 대조하지 않았으므로 확인 불가 항목입니다. 문서와 화면이 다르더라도 당황하지 말고, 화면에 적힌 안내를 그대로 따르세요.

claude 를 쳤는데 이런 게 나온다면:

'claude'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는
배치 파일이 아닙니다.

→ Claude Code가 아직 설치되지 않았거나, 설치 후 터미널을 다시 켜지 않은 것입니다. 부록 B의 에러 표와 Claude Code 공식 문서를 참고해 설치한 뒤, 검은 창을 닫고 다시 열어서 재시도하세요.

여기까지가 사람이 직접 하는 준비 작업의 전부입니다. 이제 아래 마스터 프롬프트를 붙여넣으면 됩니다.

🚀 여기부터 통째로 복사하세요 — 마스터 프롬프트

아래 코드블록 전체를 복사해서 Claude Code에 그대로 붙여넣으세요. 한 줄도 빼지 마세요.

바꿀 곳은 없습니다. GitHub 아이디 같은 정보는 Claude가 필요한 순간에 직접 물어봅니다. 복사한 뒤 검은 창(터미널)에 Ctrl + V (macOS는 ⌘ + V)로 붙여넣고 Enter 를 누르세요.

너는 지금부터 "비개발자 스터디 참가자의 배포 미션 코치"다.
나는 컴퓨터를 쓸 줄은 알지만 코드는 전혀 모르는 완전 초보다.
코드 작업과 터미널 명령은 전부 네가 직접 하고, 나에게는 확인과 클릭만 요청해라.

[최종 목표]
더미 데이터 대시보드 웹페이지를 만들어 → GitHub에 올리고 → Vercel에 배포해서
"남에게 링크를 보냈을 때 그 사람 폰에서도 열리는 URL"을 얻는 것.
이 URL을 얻기 전까지는 미션이 끝난 게 아니다.

[말투 규칙]
1. 나는 완전 초보다. 전문용어를 최대한 쓰지 마라.
   꼭 써야 하면 그때마다 괄호로 한 줄 설명을 붙여라.
   예: 커밋(지금까지 한 작업을 하나로 묶어 저장해두는 것)
2. 영어 로그나 코드를 그대로 길게 붙여넣지 마라.
   무슨 뜻인지 한국어로 두세 줄로 요약해서 알려줘라.
3. 내가 "모르겠어" 또는 "무슨 말인지 어려워" 라고 하면,
   같은 설명을 반복하지 말고 더 쉬운 말로 다시 설명해라. 필요하면 일상적인 비유를 써라.
4. 나에게 질문할 때는 한 번에 하나만 물어라. 여러 개를 한꺼번에 묻지 마라.

[진행 방식 규칙]
1. 반드시 한 번에 한 단계씩만 진행해라. 여러 단계를 몰아서 하지 마라.
2. 매 단계를 시작할 때 맨 첫 줄에 지금 어디쯤인지 먼저 알려줘라.
   형식: "8단계 중 3단계: 실수로 올리면 안 되는 파일 걸러내기"
3. 각 단계가 끝나면 "지금 무엇이 완료됐는지"를 한국어 두세 줄로 요약하고,
   "다음 단계로 갈까요?" 라고 물어본 뒤 내 대답을 기다려라.
4. 나에게 시킬 일이 있으면 "어느 사이트에서 어떤 버튼을 누르라"까지 구체적으로 알려줘라.
   버튼 이름이 실제 화면과 다를 수 있다면 그 점도 같이 말해줘라.
5. 내가 "됐어" 또는 "완료" 라고 말하기 전에는 다음 단계로 넘어가지 마라.

[누가 무엇을 하는가]
1. 터미널에 명령어를 입력하는 일은 네가 해라. 나에게 명령어를 대신 치라고 시키지 마라.
   단, 내가 웹 브라우저 화면에서 직접 눌러야 하는 작업은 예외다.
2. 네가 명령을 실행하기 전에 내 화면에 "이 명령을 실행해도 되냐"고 허용을 묻는 창이 뜰 수 있다.
   그런 게 뜰 것 같으면 미리 "곧 허용 여부를 묻는 창이 뜰 테니 허용을 눌러달라"고 알려주고,
   그게 무슨 명령인지 한 줄로 쉽게 설명해라.

[만들 대시보드 사양]
- Next.js (App Router) + TypeScript + Tailwind CSS
- 외부 API·데이터베이스·환경변수 없이, 코드 안의 더미 데이터만 사용
- 메인 페이지 한 장에 아래를 모두 배치
  (1) 상단: 대시보드 제목 + 오늘 날짜.
      날짜는 "보는 사람의 브라우저 기준 오늘 날짜"로 표시해라.
      서버에서 날짜를 굳혀버리면 배포 후 날짜가 안 바뀌니 그렇게 하지 마라.
  (2) 요약 카드 4개 — 총 매출 / 신규 고객 수 / 진행 중 프로젝트 / 완료율
      각 카드에 숫자, 항목명, 전월 대비 증감(+12% 형태) 표시
  (3) 차트 1개 — 최근 6개월 월별 매출 추이.
      차트 라이브러리는 지금 설치된 React 버전과 호환되는 것으로 네가 골라라.
      고른 이유를 한 줄로 알려줘라.
  (4) 표 1개 — 최근 주문 8행. 컬럼: 주문번호 / 고객명 / 금액 / 상태(완료·진행중·취소) / 날짜.
      상태는 색상 배지로 구분
- 밝은 테마, 카드에 은은한 그림자, 모바일에서도 안 깨지는 반응형, 텍스트는 한글
- 중요: 내 컴퓨터가 다크 모드로 설정돼 있어도 화면이 밝은 테마로 고정되게 해라.
  기본 템플릿에 다크 모드 설정이 들어 있으면 걷어내라.

[진행할 단계 — 전체 8단계, 이 순서대로]
① 프로젝트 생성: 지금 이 폴더에 위 사양대로 Next.js 프로젝트를 만들고 필요한 설치를 끝내라.
   설치에 몇 분 걸릴 수 있다는 점을 미리 나에게 알려줘라.
   설치 도중 화면에 나오는 경고(vulnerabilities, deprecated, warn 같은 단어)는
   실패가 아니라 흔한 알림이라는 점도 미리 알려줘라.
   내가 "audit fix" 류의 명령을 스스로 실행하지 않도록, 그건 누르지 말라고 말해줘라.
② 로컬 실행 확인: 개발 서버를 실행해라.
   서버가 알려주는 주소는 3000번이 아닐 수 있다. 다른 프로그램이 3000번을 쓰고 있으면
   자동으로 다른 번호(3001, 3002 등)로 열린다.
   그러니 화면에 실제로 출력된 "Local:" 주소를 그대로 읽어서 나에게 정확히 알려줘라.
   주소를 어떻게 여는지도 알려줘라.
   또 개발 서버는 실행하면 끝나지 않고 계속 켜져 있는 것이 정상이라는 점,
   첫 접속은 5~10초 걸릴 수 있다는 점을 미리 말해줘라.
   내가 "잘 보인다" 고 말할 때까지 기다려라. 안 보인다고 하면 원인을 찾아 고쳐라.
③ .gitignore 확인: node_modules, .next, .env* 가 들어 있는지 확인하고 없으면 추가해라.
   이게 "실수로 올리면 안 되는 파일을 미리 걸러두는 목록"이라는 것을 쉬운 말로 설명해라.
④ git 저장소 준비·커밋:
   - 먼저 이 폴더에 이미 git 저장소가 만들어져 있는지 확인해라.
     프로젝트를 만들 때 자동으로 생겼을 수 있다. 있으면 새로 만들지 마라.
   - 저장소가 없으면 새로 만들고, 있으면 그대로 쓴다. 어느 쪽이든 기본 가지 이름은 main으로 맞춰라.
   - 그 다음 전체를 커밋해라.
   - 이때 커밋이 무엇인지 반드시 쉬운 비유로 설명해라.
     예: "커밋은 지금까지 한 작업을 하나로 묶어 저장해두는 것이다. 게임의 중간 저장과 비슷하다."
   - git 사용자 이름·이메일이 설정 안 돼 있으면 나에게 하나씩 물어보고 설정해라.
⑤ 배포용 검사 (이 단계를 절대 건너뛰지 마라):
   npm run build 를 실행해라.
   ②단계에서 화면이 잘 보였더라도 이 검사는 따로 실패할 수 있다.
   개발용 실행과 배포용 검사는 검사 항목이 다르기 때문이다.
   그리고 Vercel은 배포할 때 바로 이 검사를 돌린다.
   즉 여기서 실패하면 나중에 배포도 반드시 실패한다.
   실패하면 원인을 찾아 네가 직접 고치고, 통과할 때까지 반복해라.
   무엇을 고쳤는지는 쉬운 한국어 한 줄로만 알려줘라.
   통과하면 "배포해도 안전한 상태"라고 나에게 알려주고 다음 단계로 넘어가라.
   고친 게 있으면 다시 커밋해라.
⑥ GitHub 업로드:
   기본은 내가 웹에서 직접 만드는 방식이다. 아래 순서로 진행해라.
   - 나에게 GitHub 웹(github.com/new)에서 빈 저장소를 만드는 절차를 번호로 알려줘라.
     이름은 my-dashboard, 공개(Public)로,
     그리고 README·.gitignore·license 추가 항목은 전부 체크 해제하라고 반드시 말해줘라.
     (체크하면 올릴 때 충돌이 난다)
   - 내가 다 만들고 "됐어" 라고 하면 저장소 주소를 물어본 뒤,
     원격 연결과 업로드는 네가 해라.
   - 업로드를 실행하기 직전에 반드시 나에게 미리 알려줘라.
     "지금 올리면 GitHub 로그인 창이 뜰 수 있다. 뜨면 Browser(브라우저) 쪽을 골라서
     GitHub에 로그인하고 승인을 눌러달라. 한 번만 하면 다음부터는 안 뜬다" 라고 말해줘라.
     이 창은 네가 대신 눌러줄 수 없다. 창이 떠 있는 동안은 기다렸다가,
     내가 로그인을 끝냈다고 하면 이어서 진행해라.
     로그인 창이 안 뜨고 바로 올라가면 그냥 넘어가면 된다.
   - 예외: 혹시 이 컴퓨터에 gh 라는 도구가 이미 설치돼 있고 로그인까지 되어 있다면,
     그걸로 저장소 생성과 업로드를 한 번에 처리해도 된다.
     다만 시작하기 전에 "어느 방식으로 진행할지"를 나에게 한 줄로 먼저 알려줘라.
     설치되어 있지 않으면 설치하라고 하지 마라. 웹 방식으로 진행하면 된다.
   - 업로드가 끝나면 node_modules 가 저장소에 올라가지 않았는지 확인하고 결과를 알려줘라.
⑦ Vercel 배포 안내: vercel.com/new 에서 저장소를 Import 하고 Deploy 하는 절차를
   내가 그대로 따라 할 수 있게 번호로 알려줘라. 설정은 기본값을 그대로 두라고 안내해라.
   내가 배포를 끝내고 "됐어" 라고 할 때까지 기다려라.
⑧ 최종 URL 확인: 내가 받은 vercel.app 주소를 알려주면,
   휴대폰이나 시크릿 모드에서 열어보라고 안내하고 결과를 확인해라.
   차트는 브라우저에서 잠깐 뒤에 그려질 수 있으니, 바로 안 보이면 몇 초 기다려보라고 알려줘라.

[사람이 직접 해야 하는 구간]
계정 로그인, GitHub 웹에서 빈 저장소 만들기, 업로드할 때 뜨는 GitHub 로그인 창 처리,
Vercel에서 Import·Deploy 버튼 누르기는 내가 한다.
이 구간에서는 절대 혼자 앞서가지 말고, 나에게 할 일을 알려준 뒤 멈춰서 기다려라.
내가 "됐어" 라고 하면 그때 이어서 진행해라.

[에러 대응 규칙]
에러가 나면 나에게 에러 메시지를 해석시키지 마라. 영어 에러 문구를 그대로 길게 보여주지도 마라.
네가 원인을 찾아서 직접 고치고, "무엇이 문제였고 어떻게 고쳤는지"를 쉬운 한국어 한 줄로만 알려줘라.
같은 에러가 두 번 반복되면 다른 접근 방법을 시도하고, 그 사실을 나에게 말해줘라.
내가 뭘 잘못한 게 아니라는 점도 알려줘라. 에러는 원래 자주 나는 것이다.

[보안 규칙]
- .gitignore 에 node_modules, .next, .env* 가 반드시 포함돼야 한다.
- 토큰·비밀번호·API 키를 코드나 파일에 저장하지 마라. 필요하면 나에게 입력 방법을 안내해라.
- 개인정보나 민감한 실제 데이터는 커밋하지 마라. 이번 대시보드 데이터는 전부 가짜여야 한다.

[마무리]
모든 단계가 끝나면 아래 양식을 채워서 출력해줘라. 내가 모르는 항목은 나에게 물어봐라.

[Session 1 배포 미션 제출]
- 이름/닉네임:
- Vercel URL:
- GitHub 저장소 URL:
- 걸린 시간:
- 가장 막혔던 지점 (한 줄):

준비됐으면 ①번 단계부터 시작해라.

붙여넣고 Enter를 치면 Claude가 "8단계 중 1단계"부터 시작합니다.

진행 중 "이 명령을 실행해도 될까요?" 같은 확인 창이 뜨면 허용하세요. 설치와 프로젝트 생성에 필요한 명령입니다. (확인 창의 문구와 선택지는 버전에 따라 다를 수 있습니다 — 확인 불가)

글자가 화면에 계속 올라가는 동안은 정상 작동 중입니다. 몇 분 걸릴 수 있으니 창을 닫지 말고 기다리세요.

설치 중 12 high severity vulnerabilities 같은 빨간 경고가 나와도 실패가 아닙니다. 그냥 두세요. 특히 npm audit fix --force 는 절대 직접 실행하지 마세요 — 프로젝트가 깨질 수 있습니다.

붙여넣은 다음 무슨 일이 벌어지나

예상 소요 시간: 약 1시간~1시간 30분 (처음이면 2시간 잡으세요)

이 중 절반 이상은 계정 만들기·로그인·웹 화면 클릭·눈으로 확인하는 데 쓰입니다. Claude가 실제로 작업하는 시간은 생각보다 짧습니다. 진도가 안 나가는 것 같아도 정상입니다.

⑤ 배포용 검사가 왜 따로 있나요? ②단계에서 화면이 잘 보여도 배포가 실패할 수 있기 때문입니다. 개발용 실행과 배포용 검사는 검사하는 항목이 다릅니다. 실제 테스트에서도 ②는 멀쩡히 통과했는데 배포용 검사에서 오류가 잡혔습니다. Vercel은 배포할 때 바로 이 검사를 돌리므로, 여기서 통과시켜야 ⑦에서 안 터집니다.

내가 직접 해야 하는 화면 작업 3개

Claude가 대신 못 하는 건 이 세 가지뿐입니다. 해당 단계에서 Claude가 멈추고 안내할 때 보세요.

왜 Claude가 못 하나요? 이 셋은 전부 내 계정으로 로그인해서 버튼을 누르는 일입니다. Claude는 내 브라우저를 대신 조작할 수 없습니다. 그래서 이 구간에서는 Claude가 멈춰서 나를 기다립니다. 멈춘 게 아니라 기다리는 것이니, 다 하고 나서 "됐어"라고 말해주면 이어서 진행합니다.

작업 1 — GitHub 웹에서 빈 저장소 만들기

1. https://github.com/new 접속
2. Repository name 에 my-dashboard 입력
3. Public(공개) 선택
4. README / .gitignore / license 추가 항목은 전부 체크 해제 ← 체크하면 푸시할 때 충돌이 납니다
5. Create repository 클릭
6. 다음 화면의 주소를 복사해서 Claude에게 알려주기 — 형태: https://github.com/내아이디/my-dashboard.git

이게 기본 경로입니다. gh 라는 명령줄 도구를 쓰면 이 화면 작업을 건너뛸 수 있지만, 대부분의 컴퓨터에는 gh 가 깔려 있지 않습니다(실제 테스트 환경에서도 없었습니다). 설치하지 않아도 됩니다. 이미 깔려 있고 로그인까지 되어 있는 경우에만 Claude가 알아서 그 방식을 씁니다. 자세한 건 부록 C 참고.

작업 2 — 첫 업로드 때 뜨는 GitHub 로그인 창 처리

이게 제일 많이 놀라는 지점입니다.

Claude가 파일을 GitHub에 올리는 순간, GitHub 로그인을 요구하는 창이 뜹니다. 컴퓨터에 GitHub 로그인 정보가 아직 저장되어 있지 않기 때문입니다. (실제 테스트 PC에서도 이 창이 필요했습니다.)

• 창 제목은 보통 Git Credential Manager 계열이고, Browser / Token 같은 선택지가 보입니다
• Browser(브라우저) 를 고르면 브라우저가 열리고, GitHub에 로그인한 뒤 Authorize(승인) 를 누르면 끝납니다
• 화면 문구와 선택지는 프로그램 버전에 따라 다를 수 있습니다 — 확인 불가 항목입니다. 나오는 안내를 그대로 따르세요

딱 한 번만 하면 됩니다. 한 번 로그인하면 컴퓨터에 저장되어, 다음부터는 이 창이 안 뜹니다.

중요: 이 창이 떠 있는 동안 Claude는 아무것도 못 하고 기다립니다. 화면이 멈춘 것처럼 보여도 고장이 아닙니다. 로그인을 끝내면 그때부터 다시 진행됩니다.

로그인 창이 안 뜨고 바로 올라갔다면, 이미 저장되어 있던 것이니 그냥 넘어가면 됩니다.

작업 3 — Vercel에서 Import → Deploy

1. https://vercel.com/new 접속
2. GitHub 연결 승인 화면이 나오면 승인 (All repositories 또는 Only select repositories → my-dashboard)
3. 목록에서 my-dashboard 를 찾아 Import 클릭
4. 설정 화면은 아무것도 건드리지 말고 그대로 — Framework Preset이 Next.js 로 잡혔는지만 확인
5. Deploy 클릭 → 1~3분 대기
6. 완료 화면에 나오는 https://my-dashboard-xxxx.vercel.app 주소 복사

버튼 이름과 배치는 업데이트에 따라 달라질 수 있습니다. 흐름은 저장소 선택 → Import → Deploy 세 단계입니다.

완료 기준과 제출

완료 기준은 딱 하나입니다.

내 Vercel URL을 휴대폰(와이파이 끄고 데이터로) 또는 브라우저 시크릿 모드에서 열었을 때 페이지가 뜨면 성공.

개발 중에 봤던 http://localhost:... 주소는 내 컴퓨터에서만 열리는 주소입니다. 그건 성공이 아닙니다.

제출 양식 — 스터디 게시판에 남겨주세요. (마스터 프롬프트가 마지막에 이 양식을 채워서 출력해줍니다.)

[Session 1 배포 미션 제출]

- 이름/닉네임:
- Vercel URL:
- GitHub 저장소 URL:
- 걸린 시간:
- 가장 막혔던 지점 (한 줄):

막혔던 지점을 꼭 적어주세요. 다음 세션에서 실제로 많이 걸린 곳을 골라 함께 풉니다.

부록 A — 막힐 때 쓰는 보조 프롬프트

마스터 프롬프트로 진행하다 흐름이 끊기면 아래를 골라 붙여넣으세요.

A-1. 에러가 났을 때 (만능)

방금 에러가 났어. 나는 비개발자라 에러를 해석하지 못해.
네가 원인을 찾아서 직접 고치고, 무엇이 문제였고 어떻게 고쳤는지 한 줄로만 알려줘.
고친 뒤에는 실행이 되는지 네가 먼저 확인해줘.

A-2. Vercel 빌드가 실패했을 때

Vercel 배포에서 빌드가 실패했어. 아래는 실패 로그야.

[여기에 Vercel 화면의 빨간 로그를 복사해서 붙여넣기]

먼저 로컬에서 npm run build 를 실행해 같은 에러가 나는지 확인하고,
원인을 찾아 직접 고친 다음 커밋과 푸시까지 해줘.

A-3. 대화가 끊겨서 다시 이어서 할 때

아까 하던 배포 미션을 이어서 하고 싶어.
지금 이 폴더의 상태(프로젝트 생성 여부, git 커밋 여부, 원격 저장소 연결 여부)를 먼저 확인하고,
지금 몇 번째 단계까지 됐는지 알려준 다음, 그다음 단계부터 이어서 진행해줘.

A-4. 화면이 안 뜰 때

브라우저에서 페이지가 안 보여. 화면에는 이렇게 나와 있어: [본 그대로 적기]
개발 서버가 실제로 켜져 있는지, 접속 주소가 맞는지, 포트가 바뀌지 않았는지 확인해서 알려줘.

부록 B — 자주 나는 에러 & 해결

포트 정리 (에러 #7 심화)

Windows (PowerShell)

netstat -ano | findstr :3000
taskkill /PID 여기에_나온_숫자 /F

macOS

lsof -i :3000
kill -9 여기에_나온_PID숫자

원칙: 위 표를 외울 필요 없습니다. 대부분은 부록 A-1 프롬프트를 붙여넣는 것으로 해결됩니다. 이 표는 Claude가 고치지 못하고 반복될 때 참고용입니다.

부록 C — 수동으로 하고 싶은 사람을 위한 git 명령어

마스터 프롬프트를 쓰면 Claude가 알아서 처리합니다. 직접 손으로 해보고 싶은 경우에만 참고하세요.

C-1. 기본 흐름 (웹에서 빈 저장소를 만든 뒤)

git init
git add .
git commit -m "첫 대시보드 커밋"
git branch -M main
git remote add origin https://github.com/내아이디/my-dashboard.git
git push -u origin main

주의: 프로젝트를 만들 때 git 저장소가 이미 자동으로 만들어져 있을 수 있습니다(실제 테스트에서 그랬고, 가지 이름이 master 로 잡혔습니다). 그 경우 git init 은 건너뛰고 git branch -M main 부터 하면 됩니다. 이미 있는 저장소에 git init 을 다시 해도 망가지지는 않습니다.

첫 커밋에서 이름/이메일을 설정하라는 메시지가 나오면:

git config --global user.name "내 이름"
git config --global user.email "내 이메일"

C-2. gh CLI로 한 번에 (선택 사항 — 설치하지 않아도 됩니다)

gh 는 대부분의 컴퓨터에 기본으로 깔려 있지 않습니다. 실제 테스트 환경에서도 없었습니다. 이번 미션의 정규 경로는 GitHub 웹 화면이며, gh 는 이미 쓰고 있는 사람을 위한 지름길입니다. 미션을 위해 새로 설치할 필요는 없습니다.

설치는 GitHub CLI 안내 참고.

gh auth login
git init
git add .
git commit -m "첫 대시보드 커밋"
gh repo create my-dashboard --public --source=. --remote=origin --push

마지막 한 줄로 저장소 생성 + 원격 연결 + 푸시가 전부 끝납니다.

C-3. Vercel CLI로 배포 (대안)

npm install -g vercel
vercel login
vercel

질문이 나오면 대부분 Enter(기본값)로 넘기면 됩니다. 운영용 주소로 배포하려면:

vercel --prod

CLI만으로도 배포는 되지만, 이번 미션은 GitHub 연동까지가 목표이므로 GitHub 업로드를 건너뛰지 마세요.

부록 D — 보안 주의사항

배포는 인터넷 전체에 공개하는 행위입니다. 아래 3가지는 습관으로 만들어두세요.

1. .gitignore에 .env* 는 무조건 포함

환경변수 파일에는 API 키, 비밀번호, 접속 정보가 들어갑니다. 한 번 GitHub에 올라가면 커밋 기록에 남습니다.

node_modules
.next
.env*

2. API 키를 코드에 직접 쓰지 않기

❌ const apiKey = "sk-실제키값..."
✅ 환경변수로 분리 → Vercel 프로젝트 설정의 Environment Variables 에 등록

이번 미션은 더미 데이터만 쓰므로 키가 필요 없습니다. 키를 요구하는 코드가 생겼다면 Claude Code에게 "환경변수로 분리해줘"라고 요청하세요.

3. 공개 저장소에 민감정보 올리지 않기

• 실제 고객명, 연락처, 사내 매출 수치 → 넣지 마세요. 이번 미션은 전부 가짜 데이터입니다
• 개인 파일(이력서, 계약서 등)이 프로젝트 폴더에 섞이지 않았는지 git add . 전에 확인
• 이미 키를 올렸다면: 파일만 지우는 걸로 끝나지 않습니다. 발급처에서 그 키를 폐기(revoke)하고 새로 발급해야 합니다

부록 E — 완료 체크리스트

준비

• GitHub 계정 생성 완료 + 실제로 로그인해봄
• Vercel 계정 생성 완료 (GitHub 연동으로 가입) + 실제로 로그인해봄
• 하드디스크 여유 공간 1GB 이상 확보
• node -v 실행 시 버전 출력됨
• claude --version 실행 시 버전 출력됨

0단계 — 시작 (사람이 직접)

• 바탕화면에 my-dashboard 폴더 생성 (한글·띄어쓰기 없이)
• 폴더를 열고 주소창에 cmd 입력 → Enter 로 터미널 열기
• 검은 창 첫 줄이 ...\Desktop\my-dashboard> 로 끝나는지 확인
• claude 입력해서 Claude Code 실행됨
• 마스터 프롬프트를 통째로 붙여넣음 (Ctrl + V)

제작

• 카드 4개 / 차트 1개 / 표 1개가 화면에 있음

로컬 확인

• 개발 서버 실행 성공
• 터미널에 표시된 Local: 주소에서 페이지 정상 표시 (3000번이 아닐 수 있음)
• 창을 좁혀도 레이아웃이 깨지지 않음

배포용 검사 (가장 중요)

• npm run build 실행
• 오류 없이 통과할 때까지 수정 완료 ← 여기를 통과해야 Vercel 배포가 성공합니다
• 수정한 내용이 있으면 다시 커밋함

GitHub

• .gitignore 에 node_modules, .next, .env* 포함 확인
• GitHub 웹에서 빈 저장소 생성 (README 등 체크 해제)
• 업로드 중 GitHub 로그인 창이 뜨면 브라우저로 로그인 + 승인 (최초 1회 / 안 뜨면 통과)
• 푸시 성공
• GitHub 웹에서 파일 목록 확인됨
• node_modules 폴더가 저장소에 없음

배포

• Vercel에서 저장소 Import 후 Deploy 성공
• https://...vercel.app 주소 확보
• 휴대폰 또는 시크릿 모드에서 열림 ← 진짜 완료 기준

제출

• 스터디 게시판에 Vercel URL 제출
• 막혔던 지점 한 줄 기록

참고 링크

• Claude Code 공식 문서
• Vercel 공식 문서
• GitHub 공식 문서
• Next.js 공식 문서