첫 실행

이 단계의 목표는 단순합니다. 외부 서비스를 건드리지 않고, 내 컴퓨터에서 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에 맞는 다음 슬래시 명령을 안내합니다.

첫 진입이라면 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 + TypeScript + React Router + FSD 6레이어 + ESLint boundaries + jsx-a11y + Supabase client 자리 표시 값 + Stripe SDK 자리 표시 값 + 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 가 자리 표시 값으로 채워 둔 랜딩 화면이 떠야 정상입니다. 헤더 한 줄과 가격 카드 골격 세 장, 가입과 로그인 링크가 보입니다. 본인 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/         ← 행 수준 접근 정책 기준 문서

이 구조를 모두 이해할 필요는 아직 없습니다. 무언가 바꾸고 싶을 때는 Claude Code에 원하는 변화를 말로 알려 주는 것이 보통 가장 빠릅니다. 어느 파일이 어디에 대응하는지는 AI가 알고 있습니다.

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

다음 단계

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

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