/setup 명령어 — 빌드킷 셋업 + 문제 대응
이 레슨이 끝나면
- Claude Code에서
/setup을 호출해서 빌드킷 자동 셋업이 끝나 있다 (의존성 설치 / DB 생성 / 환경변수 템플릿) /setup이 자동으로 무엇을 해 주는지 한 줄씩 설명할 수 있다- 자주 발생하는 5가지 문제(의존성 실패 / Ruby 버전 / Node 버전 / 권한 / 포트 충돌)에 대응할 수 있다
- 다음 레슨에서
/dashboard로 빌드킷 내용을 둘러볼 준비가 끝났다
/setup이 뭔가요?
/setup은 빌드킷에 들어 있는 슬래시 명령(slash command)이에요.
Claude Code 채팅에서 한 줄 입력하면, 본인 PC에 본인 프로젝트가 동작하기 위해 필요한 모든 기본 셋업을 자동으로 해 줘요.
비유하자면 새집 입주 청소 + 기본 가전 설치예요. 사람이 살기 위해 필요한 가스·수도·전기·인터넷을 한 번에 들여놓는 셈.
/setup이 자동으로 해 주는 일:
- Vuild MCP 연결 확인: 빌드킷이 vuild.kr 보드와 통신할 수 있게 연결
- 환경 검사: Ruby / Node / Bundler 등 필수 도구 버전 점검 (없으면 설치 안내)
- 의존성 설치:
bundle install(Ruby 라이브러리들),npm install(Node 라이브러리들) 자동 실행 - DB 생성:
bin/rails db:create db:migrate로 DB 파일 만들고 초기 테이블 생성 - 환경변수 템플릿:
.env.example→.env복사 (API 키 등 비밀값을 적을 빈 양식)
단계 1 — Claude Code 채팅에 /setup 입력
Antigravity의 우측(또는 본인이 설정한 위치) Claude Code 패널을 여세요.
4-2에서 첫 메시지를 보냈던 그 채팅창이에요. 입력란에 슬래시(/)를 치면 사용 가능한 명령 목록이 자동완성으로 떠요.
/setup
엔터 누르면 Claude가 단계별로 진행 상황을 알려줘요. 보통 다음 흐름이에요:
- "MCP 연결 확인 중..." → 성공 시 "✓ vuild MCP 연결됨"
- "환경 검사 중..." → "✓ Ruby 3.3 / ✓ Node 20 / ✓ Bundler 2.5"
- "의존성 설치 중..." (1~3분 정도, 진행 상황 출력)
- "DB 생성 중..." → "✓ db:create / ✓ db:migrate"
- "환경 준비 완료! 다음:
/dashboard로 보드 현황 확인"
중간 질문이 뜨면 — 이렇게 답하세요
/setup이 진행 중에 가끔 본인에게 한두 가지를 묻기도 해요. 자주 묻는 것 + 추천 답변:
| 묻는 것 | 기본 추천 답 |
|---|---|
| "Vuild API 토큰을 알려주세요" | vuild.kr/my/api_token에서 발급 → 복붙 |
| "setup 모드 (basic / pro)?" | basic 추천 (SQLite + Solid). 결제 트래픽 본격적이면 나중에 pro로 전환 |
| "Ruby/Node가 없습니다. 자동 설치할까요?" | "네" — 자동 설치 진행 (5~15분, 인터넷 필요) |
| "이 명령을 실행할까요? (y/n)" | 읽어 보고 위험한 명령(rm, sudo) 아니면 y |
setup_mode: basic vs pro
본 코스는 basic 모드를 default로 권장해요. 이유:
| basic (권장) | pro | |
|---|---|---|
| DB | SQLite (파일 1개) | PostgreSQL (서버 별도) |
| 캐시·잡 | Solid Queue/Cache (DB 안) | Redis (서버 별도) |
| 설치 부담 | 없음 (자동) | PostgreSQL/Redis 별도 설치 |
| 언제 적합 | 학습 / MVP / 사용자 ~수천명 | 트래픽 본격 / 백그라운드 잡 많음 |
본 코스 모든 lesson은 basic 기준으로 진행돼요. pro로 전환은 출시 후 트래픽이 본격적으로 들어오기 시작했을 때 한 번 고민하면 돼요.
자주 발생하는 문제 5가지 — 풀이
① "의존성 설치 실패" — bundle install 또는 npm install 에러
가장 흔한 원인: 인터넷 일시 끊김, 패키지 저장소 일시 장애, 권한 부족.
해결:
- 한 번 더
/setup호출 → 보통 두 번째에 됨 - 그래도 안 되면 에러 메시지 전체를 그대로 Claude Code 채팅에 복붙 → "이 에러 풀어줘"
- Mac에서 권한 문제면
sudo안 쓰고brew install또는mise로 Ruby 다시 설치 권장
② "Ruby version mismatch" — 버전이 안 맞음
빌드킷은 Ruby 3.2 이상을 요구. ruby --version으로 확인.
해결:
- Mac:
brew install ruby@3.3또는mise install ruby@3.3 - Windows: RubyInstaller에서 3.3 버전 다운로드 → 설치 → Antigravity 재시작
- WSL/Linux:
sudo apt install ruby-full또는 mise/rbenv 추천
③ "Node version too old" — Node 20 미만
node --version으로 확인. 20.x 이상 필요.
해결:
- Mac:
brew install node - Windows: nodejs.org LTS 다운로드 → MSI 설치
④ "Permission denied" — 권한 거부
시스템 폴더(/usr/local 등)에 쓰려고 할 때 발생.
해결: sudo로 강제하지 말고 본인 홈 폴더(~/dev) 안에서 작업하세요.
한 번이라도 sudo로 깐 게 있으면 권한이 꼬일 수 있어요. 그때는 Claude에게 "권한 꼬임 풀어줘" 부탁.
⑤ ".env 파일 없음" — 환경변수 템플릿 빠짐
빌드킷에 .env.example은 있지만 .env는 없는 게 정상.
/setup이 자동으로 복사해 주는데, 가끔 빠질 수 있어요.
해결: 터미널에서 한 줄.
cp .env.example .env
또는 Claude Code에 ".env 파일이 없어, .env.example에서 복사해줘" 부탁.
[보너스] "포트 3000이 이미 사용 중"
다른 Rails 앱이 같은 포트를 쓰고 있을 때. 4-9에서 본격적으로 풀지만, 지금 발생하면:
# Mac/Linux: 포트 3000 점유 프로세스 찾기 lsof -i :3000 # Windows netstat -ano | findstr :3000
결과의 PID를 본 뒤 해당 프로세스 종료.
설치 끝나면 — 첫 git commit
/setup이 끝나면 새 파일들(.env, DB 파일 등)이 생겨 있어요.
이 시점에서 한 번 git commit을 해 두면 좋아요.
git status # 변경 파일 확인 git add . git commit -m "/setup 완료 - 의존성 설치 + DB 생성"
중요: .env는 git에 안 들어가요
.env는 비밀 정보(API 키)를 담는 파일이라 git이 자동으로 무시하게 되어 있어요 (.gitignore에 등록됨).
이건 정상이에요. 4-13에서 환경변수를 본격적으로 다룰 때 자세히 풀어요.
결과 검토 — 이게 다 됐는지 체크
터미널에서 다음 한 줄 실행해서 Rails 앱이 제대로 셋업됐는지 확인.
bin/rails about
Rails 버전, Ruby 버전, DB 어댑터 등이 출력되면 성공이에요. 에러가 나면 그 메시지를 Claude Code에 복붙하고 풀이 부탁.
자가 진단 — 통과 기준
- ☐ Claude Code에서
/setup을 호출해서 "환경 준비 완료" 메시지를 받았다 - ☐
bin/rails about명령이 정상 응답한다 (Rails 8.1.x 출력) - ☐
.env파일이 폴더에 존재한다 - ☐
git commit -m "/setup 완료"로 셋업 직후 상태를 세이브했다 - ☐ 자주 발생하는 5가지 문제 중 어떤 것이 본인에게 일어났고 어떻게 풀었는지 한 줄로 적을 수 있다 (안 일어났으면 OK)
다음 단계 → 4-5 /dashboard 명령어 — 빌드킷 내용 보기
환경 셋업이 끝났으니 다음은 빌드킷 안에 뭐가 들어 있는지 둘러볼 차례예요.
/dashboard 한 줄로 본인 빌드킷의 스킬·에이전트·티켓 목록을 한눈에 봐요.
그 후 4-6에서 빌드킷에 이미 만들어져 있는 티켓을 하나씩 실행해서 진짜 코드를 만들기 시작해요.
실습하기
로그인하면 스킬을 실습할 수 있습니다