Ch.3-8에서 PLAN의 마지막 단계로 빌드킷 ZIP을 다운로드 받았어요. 이 빌드킷이 뭔지 다시 정리해 볼게요. 빌드킷은 "Claude가 본인 서비스를 어떻게 만들지 미리 숙지한 폴더"예요. 그 안에는 본인 서비스의 기획서, 디자인 시스템, 와이어프레임, AI에게 알려줄 컨텍스트, 만들어야 할 티켓 목록 등이 모두 들어 있어요.

비유하면 빌드킷은 건축 시공팀에 넘기는 도면 보따리예요. 도면, 자재 목록, 시공 순서, 안전 수칙이 한 가방에 들어 있어요. 이걸 본인 작업 공간(PC)에 풀어 놓아야 시공팀(Claude Code + AI 에이전트)이 일을 시작할 수 있어요.

🎨 생성 (Codex CLI) — 빌드킷 ZIP → PC 폴더 → Claude가 읽는 흐름 다이어그램. — ZIP을 풀어 놓는 게 BUILD의 첫 발자국이에요.

준비물 — 시작 전 체크리스트

본인 노트북 (Mac 또는 Windows)
Ch.3-8에서 다운로드한 빌드킷 ZIP 파일 (보통 my-service-buildkit.zip 또는 본인 프로젝트명 + .zip)
인터넷 연결 (다음 레슨부터 Antigravity 다운로드)
약 5GB 빈 디스크 용량
(아직 빌드킷이 없으면) Ch.3-8로 돌아가서 vuild.kr 대시보드 → PLAN → "빌드킷 다운로드"를 먼저 끝내고 오세요

단계 1 — 작업 폴더 위치 정하기

ZIP을 아무 데나 풀면 나중에 못 찾아요. 미리 본인 코드 작업용 상위 폴더를 한 군데 정해 놓고, 거기 안에 빌드킷을 풀 거예요. 한 번 정한 위치는 앞으로 30일 동안 계속 쓰니까 신중하게 골라요.

Mac — 추천 위치

홈 디렉토리(~) 바로 아래에 dev 폴더 만들기
Finder 열기 → 좌상단 메뉴 "이동 → 홈" → 우클릭 → "새로운 폴더" → 이름을 dev로
최종 경로 예: /Users/본인이름/dev

Windows — 추천 위치

C 드라이브 바로 아래에 dev 폴더 만들기
탐색기 → "내 PC → 로컬 디스크 (C:)" → 우클릭 → "새로 만들기 → 폴더" → 이름을 dev로
최종 경로 예: C:\dev
피해야 할 위치: 바탕화면, OneDrive·iCloud Drive 자동 동기화 폴더, "다운로드" 폴더. 동기화 도구가 빌드 중에 파일을 잠그면 에러가 나요.

📷 캡쳐 — Mac Finder에 <code>~/dev</code> 폴더 / Windows 탐색기에 <code>C:\dev</code> 폴더 2분할. — 앞으로 모든 코드는 이 폴더 안에 모여요.

단계 2 — ZIP 파일 옮기기

브라우저에서 다운로드 받은 빌드킷 ZIP은 보통 "다운로드" 폴더에 들어가 있어요. 그 파일을 방금 만든 dev 폴더로 잘라내기 → 붙여넣기로 옮기세요.

Mac: ZIP 우클릭 → "옮기기" → ~/dev 선택. 또는 드래그-드롭.
Windows: ZIP 우클릭 → "잘라내기" → C:\dev 폴더 안에서 우클릭 → "붙여넣기".

단계 3 — ZIP 압축 풀기

Mac

dev 폴더로 이동.
빌드킷 ZIP 파일을 더블클릭 한 번. 자동으로 같은 위치에 풀려요.
풀린 폴더 이름이 본인 프로젝트명과 같은지 확인 (예: my-service).

Windows

C:\dev 폴더로 이동.
빌드킷 ZIP 우클릭 → "압축 풀기" 선택.
대화상자가 뜨면 압축 푸는 위치를 확인하고 (현재 폴더 그대로 OK) "압축 풀기" 클릭.
같은 위치에 새 폴더가 생겼는지 확인.

단계 4 — 폴더 구조 둘러보기

풀린 폴더 안에 들어가 보면 파일이 잔뜩 있어요. 당황하지 마세요. 다음 레슨부터 Antigravity 에디터를 쓰면 한눈에 정리돼요. 지금은 가장 중요한 5가지만 머리에 넣고 가요.

파일/폴더	한 줄 역할	언제 다시 보나
CLAUDE.md	Claude에게 본인 프로젝트를 처음 소개하는 인사 카드. AI가 가장 먼저 읽음.	매 세션 시작 시 자동
.claude/skills/	본 프로젝트 전용 AI 스킬 모음 (예: `/v3-database`, `/v3-auth`).	스킬 호출 시 자동
.claude/agents/	AI 팀원 페르소나 (Rails 개발자, 디자이너, 리뷰어 등).	4-7 (새 티켓 + 에이전트 활용)
.claude/commands/	슬래시 명령어 정의 (`/setup`, `/dashboard`, `/backlog` 등).	4-4 ~ 4-7
docs/	PLAN에서 만든 기획서 / 와이어프레임 / 디자인 시스템 마크다운.	언제든 본인이 직접 참고

📷 캡쳐 — Finder/탐색기에서 빌드킷 폴더 펼친 화면 + 5개 핵심 파일 강조. — 이 5개만 알아도 70%는 끝이에요.

".으로 시작하는 폴더가 안 보여요"

.claude처럼 점(.)으로 시작하는 폴더는 OS 기본 설정에서 숨김 처리돼 있어요. 정상이에요. Mac은 Finder에서 Cmd + Shift + . 누르면 토글됩니다. Windows는 탐색기 상단 "보기 → 표시 → 숨김 항목"을 켜면 보입니다. 다음 레슨에서 Antigravity 에디터를 깔면 숨김 파일도 자동으로 다 보이니까 지금은 안 보여도 OK.

CLAUDE.md를 한번 열어 보세요

가장 중요한 파일이 CLAUDE.md예요. 한번 메모장이나 TextEdit으로 열어 보세요. 본인 프로젝트의 이름, 한 줄 설명, 사용한 기술, 주요 디렉토리 같은 정보가 적혀 있을 거예요. 이게 Claude가 매번 처음 읽는 인사 카드예요.

지금은 그냥 "이런 게 있구나" 정도만 보고 닫으세요. 다음 레슨부터 Antigravity 안에서 더 편하게 볼 거예요. 괜히 메모장에서 수정하지 마세요. (인코딩이 꼬일 수 있어요.)

📷 캡쳐 — CLAUDE.md를 메모장/TextEdit으로 연 화면. 본인 프로젝트 이름 + 한 줄 설명 강조. — 이게 Claude가 매번 읽는 인사 카드예요.

자주 발생하는 문제 + 해결

"풀었더니 폴더 안에 폴더가 또 들어 있어요"

ZIP에 따라 my-service/my-service/처럼 한 단계 더 들어가 있을 수 있어요. 그 안쪽에 CLAUDE.md가 있으면 그게 진짜 작업 폴더예요. 안쪽 폴더만 잘라내서 한 단계 위로 올려 두면 깔끔해요.

"Windows에서 압축이 안 풀려요"

Windows 기본 압축 도구가 큰 ZIP을 못 다룰 때가 있어요. 무료 7-Zip(7-zip.org)을 설치하면 우클릭 메뉴에 "7-Zip → 압축 풀기"가 추가돼요. 이걸로 다시 시도하세요.

"Mac에서 '확장자가 위험할 수 있어요' 경고가 떠요"

가끔 macOS Gatekeeper가 ZIP을 의심해요. "확인" 또는 "열기" 클릭하면 진행돼요. 그래도 풀리지 않으면 시스템 설정 → 개인정보 보호 및 보안 → "확인되지 않은 개발자" 항목 옆 "그래도 열기"를 한 번 클릭하세요.

"폴더 이름에 한글이 들어갔는데 괜찮나요?"

가급적 영문 + 하이픈으로만 폴더 이름을 두세요 (예: my-cafe-app). 한글·공백·특수문자가 들어가면 일부 빌드 도구에서 에러가 나요. 이미 한글이면 폴더 우클릭 → "이름 바꾸기"로 영문으로 바꿔 두세요. 빌드킷 자체는 한글이어도 동작은 하지만, 미래의 본인이 고생할 가능성이 커요.

자가 진단 — 이 레슨 통과 기준

☐ ~/dev 또는 C:\dev 같은 본인만의 코드 작업 폴더가 만들어져 있다
☐ 그 안에 빌드킷 ZIP이 풀려서 본인 프로젝트 폴더가 생겨 있다
☐ 폴더 안에 CLAUDE.md 파일이 보인다 (메모장으로 한번 열어 봤다)
☐ .claude/ 폴더가 어디 있는지 안다 (지금 안 보여도 다음 레슨에서 자동으로 보임)

다음 단계 → 4-2 Antigravity + Claude Code 설치 + 터미널 친해지기

지금까지는 메모장으로만 봤어요. 다음 레슨에서 Antigravity(구글 무료 코드 에디터)를 설치하면 이 폴더 전체가 한 화면에 깔끔하게 펼쳐져요. 그리고 Claude Code 확장을 깔면 채팅창이 에디터 안에 같이 떠요. 마지막으로 터미널(검은 화면) 무서워하지 않는 법까지 한 번에 다뤄요. 시간은 약 30분 잡으세요. 다음 레슨이 BUILD 전체에서 가장 중요한 환경 셋업이에요.