첫 실행

이 단계의 목표는 단순합니다. 외부 서비스를 건드리지 않고, 내 컴퓨터에서 SaaS 골격 화면이 http://localhost:5173 에 뜨는 모습을 직접 보는 것입니다. Supabase 연결과 Stripe 결제는 다음 단계입니다. 보통 40분 안에 끝납니다.

1) base 디렉토리에서 Claude Code 실행

02-clone-and-install.md에서 cd my-saas 까지 했다면 같은 자리에서 다음 명령을 실행합니다.

claude

Claude Code 프롬프트가 뜨면 CLAUDE.md 와 자동화 규칙을 조용히 읽어 들입니다. 화면에 출력이 별로 안 보일 수 있는데 정상입니다.

2) 한 줄로 시작

Claude Code 프롬프트에 다음을 입력합니다.

/start

또는 자연어로 프로젝트 세팅 시작. 어느 쪽이든 start 라우터 스킬을 트리거합니다. 라우터가 현재 stage를 자동 감지한 다음 (empty → paced → analyzed → designed → customized → implemented → built → deployed 중 하나) 그 자리에 맞는 다음 슬래시 명령을 안내합니다.

첫 진입이라면 stage가 empty 로 잡히고, 라우터가 /1-pace 호출을 권합니다.

3) `/1-pace` — 호흡 결정

/1-pace 가 호출되면 한 질문이 옵니다.

개발 경험을 어떻게 잡으시겠어요?

novice (한 번에 한 질문씩 안내)

experienced (관련 질문 2~3개 묶음)

처음이라면 novice 가 안전합니다. AI가 phase 3과 4의 결정 질문(컨셉, 라우팅 모드, 가격 모델, 데이터 스키마)을 한 번에 하나씩 풀어 줍니다. experienced 를 고르면 같은 질문 묶음이 한 번에 들어옵니다. 같은 결정에 도달하지만 호흡이 다릅니다.

대답은 .claude/state/user-pace.json 에 박힙니다. 다음 phase 부터는 이 호흡 위에서 진행됩니다.

4) AI가 phase 1과 2를 도는 동안

이 시간 동안 라우터가 다음을 알아서 합니다.

/2-setup-base phase 호출 — 스택 골격 확인 (Vite + React + TS + React Router + FSD 6레이어 + ESLint boundaries + jsx-a11y + Supabase client placeholder + Stripe SDK placeholder + api/ 디렉토리). 이미 base 가 깔려 있으니 새로 만드는 자리가 거의 없고, 검증만 한 바퀴 도는 단계입니다.
빈 템플릿 자동 생성 — .claude/session-state/archive/active.md, .claude/state/progress.md, .claude/agent-memory/MEMORY.md 같은 자리.

화면에 Phase 2 setup-base 완료 같은 진행 줄이 흘러갑니다. 머신 속도에 따라 2~5분 정도 걸립니다.

phase 3 부터 6 (컨셉 분석, 디자인 결정, 커스터마이즈, 잔재 정리) 은 첫 실행의 범위 밖입니다. 이 단계에서는 phase 2 까지만 통과하고 dev 서버를 띄우는 자리에서 한 번 멈춥니다.

5) Vite dev 서버 띄우기

pnpm dev

콘솔에 다음 모양의 줄이 떨어집니다.

  VITE v5.x.x  ready in 312 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

Local: 자리의 URL 을 브라우저로 엽니다. base 가 박아 둔 placeholder 랜딩 화면이 떠야 정상입니다. 헤더 한 줄, 가격 카드 골격 세 장, 가입과 로그인 링크. 본인 SaaS 의 이름과 컨셉은 아직 박혀 있지 않습니다. 그 자리는 phase 3 과 5 에서 채워집니다.

브라우저가 빈 화면으로만 떠 있고 콘솔에 빨간 줄이 떨어진다면 보통 다음 둘 중 하나입니다.

pnpm install 이 끝까지 깔끔하게 끝나지 않은 상태. 새 터미널에서 pnpm install 을 한 번 더 돌리고 pnpm dev 를 다시 띄웁니다.
5173 포트가 이미 다른 프로세스가 잡고 있는 상태. 콘솔 메시지에 다른 포트 (5174, 5175 등) 가 안내되면 그쪽 URL 을 엽니다.

6) `src/` 한 번 둘러보기

여기까지 왔으면 base 가 들고 있는 폴더 모양을 한 번 훑어 두면 좋습니다.

src/
├── app/                ← main.tsx, App.tsx, providers, router
├── pages/              ← landing, pricing, auth, app(보호), checkout-result
├── widgets/            ← site-header, site-footer, pricing-grid, app-shell
├── features/           ← sign-in, sign-up, checkout, manage-subscription, require-auth
├── entities/           ← User, Subscription, Plan, Invoice
└── shared/             ← ui, lib, api, config
api/
├── functions/          ← Edge Functions (Deno 런타임)
└── migrations/         ← RLS 정책 SSOT

이 구조를 모두 이해할 필요는 아직 없습니다. 무언가 바꾸고 싶을 때는 Claude Code에 원하는 변화를 그냥 말로 알려 주는 것이 보통 가장 빠른 길입니다. 어느 파일이 어디에 매핑되는지는 AI가 압니다.

src/ 안의 폴더는 phase 5 (/5-customize-saas) 까지는 골격뿐입니다. 라우트 트리도, 도메인 entity 도, 가격 페이지 본문도 placeholder 입니다. 본인 SaaS 의 모양이 잡히는 자리는 phase 5 입니다.

다음 단계

가고 싶은 자리	이 매뉴얼의 어느 곳
Supabase 연결과 첫 마이그레이션	04-real-backend.md
컨셉을 정하고 라우팅, 가격, 데이터 스키마 결정	Claude Code에 “컨셉 분석 시작” 또는 `/3-analyze-saas`
브랜딩과 디자인 톤 입히기	05-customize-design.md
무언가 깨졌을 때	09-troubleshooting.md

다음 단계를 어디로 잡아야 할지 모르겠다면 04 부터가 무난합니다. Supabase 가 안 잡힌 상태에서는 가입과 로그인 흐름이 placeholder 자리에서만 돌고, 결제도 mock 화면으로 멈춥니다. 04 가 한 번 통과하고 나면 그 위에서 phase 3, 4, 5 의 컨셉과 데이터 결정이 의미 있게 풀립니다.