비개발자용 시작

이 가이드는 풀타임 개발자가 아닌 분을 위한 안내입니다. 본인 컴퓨터에서 Vite dev 서버 위에 SaaS 화면이 직접 뜨는 데까지 한 단계씩 따라가도록 짜여 있습니다. 도중에 막히면 09-troubleshooting.md을 옆 탭에 켜두고 같은 증상을 찾아 보면 됩니다.

어떤 분을 염두에 두고 썼나

이 base를 집어 드는 분 중에는 풀타임 개발자가 아닌 경우가 적지 않습니다. 그래서 문체를 되도록 친절하게 썼습니다. 다만 가정하는 학습 수준이 하나 있습니다.

터미널을 한 번이라도 열어 봤고, AI와 코딩해 본 경험이 있다는 가정입니다. 명령을 한 줄씩 풀어 적기는 하지만, “터미널이 무엇인지”, “git이 무엇인지”, “Node가 왜 필요한지”를 처음부터 설명하지는 않습니다. 그 부분은 이 매뉴얼이 가르치지 않습니다. 옆 탭에 무료 학습 자료(YouTube의 git/터미널 입문, MDN의 Node.js, Anthropic의 Claude Code 빠른 시작)를 두고 함께 보시면 됩니다.

다음 세 가지를 가정합니다.

• 터미널과 git, Node의 이름과 대략의 쓰임은 알고 있다고 봅니다. 그 위에서 명령을 한 줄씩 풀어 적습니다.
• 첫 실행에는 Supabase나 Stripe 같은 외부 서비스 연결이 필요 없습니다. pnpm dev 가 띄우는 Vite 화면이 http://localhost:5173 에 뜨는 것까지가 첫 단계의 끝입니다. 외부 서비스 연결은 04-real-backend.md 단계에서 시작합니다.
• 코드는 AI가 씁니다. 이 가이드에서는 Claude Code를 씁니다. 어떤 SaaS를 만들고 싶은지만 알면 됩니다.

이미 익숙한 부분이 있다면 그 단계는 훑고 넘어가도 됩니다. 다만 한 번씩은 눈으로 지나가 두는 편이 좋습니다. 기대와 다르게 동작하는 상황을 만났을 때 어디로 돌아와야 하는지가 머릿속에 남기 때문입니다.

처음 보는 단어가 단계마다 쌓이면, 매뉴얼이 가르치려는 본론(AI가 잘못된 방향으로 갈 때의 안전망, 컨텍스트 복구, 시나리오 검증, 결제와 행 수준 접근 정책 안전망)에 도달하기 전에 지치게 됩니다. 그 본론이 이 base의 핵심이니, 입구 단계에서 막히는 일이 쌓인다고 느끼면 학습 자료부터 한 번 정리하고 돌아오는 편이 빠릅니다.

단계 안내

단계	무엇을 하나	대략 시간
1 01-prerequisites.md	Node, git, Docker, Supabase 계정, Stripe 계정, Claude Code를 설치합니다	처음이면 40~60분
2 02-clone-and-install.md	base를 받고 의존성을 설치합니다	5~10분
3 03-first-run.md	/start 를 호출한 뒤 Vite dev 서버로 첫 화면을 봅니다	20~40분
4 04-real-backend.md (선택)	Supabase를 연결하고 행 수준 접근 정책 마이그레이션을 적용합니다	30분~1시간
5 05-customize-design.md (선택)	브랜딩과 디자인 톤을 입힙니다	15~30분
6 06-when-ai-gets-stuck.md	AI 워크플로 자체가 막힐 때 푸는 방법을 익힙니다	필요할 때만
7 07-automated-safety-net.md	base가 자동으로 챙겨주는 안전망을 이해합니다	10분
8 08-distribution.md (선택)	Vercel, Netlify, Cloudflare Pages 중 하나로 배포합니다	30분~2시간
9 09-troubleshooting.md	자주 부딪히는 증상을 모아 봅니다	필요할 때만
10 10-staying-up-to-date.md (선택)	base 업데이트를 내 코드에 가져옵니다	한 사이클당 10~30분

이미 React와 React Router, Supabase, Stripe가 익숙한 분이라면 전문가용 매뉴얼이 같은 base를 더 짧게 설명합니다.

막혔을 때

가장 먼저 볼 곳은 09-troubleshooting.md입니다. 첫 실행에서 흔히 부딪히는 증상은 거의 거기에 정리돼 있습니다.

거기에도 같은 증상이 없으면 에러 메시지를 그대로 복사해서 Claude Code에 붙여 넣고 “이거 어떻게 고쳐?” 라고 물어 보세요. 다음에 시도할 만한 방법이 보통 따라옵니다.

그래도 풀리지 않으면 GitHub 이슈를 열거나 팀 Slack에 글을 올립니다. 세 가지를 함께 적어 주세요.

• 어디서 막혔는지 적습니다 (어느 파일, 어느 명령인지).
• 에러 메시지 전체를 붙입니다.
• 환경 정보를 적습니다 (운영체제, Node 버전, Docker 버전).

처음 한 번이 가장 느립니다. 환경이 한 번 잡히고 나면 다음 SaaS를 만들 때는 1단계를 통째로 건너뛰게 되고, 전체 흐름이 눈에 띄게 짧아집니다.

매뉴얼은 어디까지 다루고 base 는 어디부터 맡나

이 단계 표가 다루는 것은 base가 자동으로 챙겨주는 기능입니다. 자동 안전망과 컨텍스트 복구, 시나리오 검증, FSD 6레이어 경계 강제, 행 수준 접근 정책 기준 문서, 라이선시 업데이트 채널 같은 차별점이 여기에 들어갑니다. 매뉴얼 본문은 무료로 공개돼 있으니 옆 탭에 두고 따라가시면 됩니다.

실제 base 코드와 .claude/ 풀셋(에이전트, 스킬, 훅)은 Solo 1인 라이선스에 1년 업데이트 채널을 더한 형태로 곧 공개합니다. 가격과 결제 채널이 정해지면 이 페이지와 랜딩에 같이 안내합니다. 매뉴얼을 따라가다 “이 자동화가 들어 있는 실제 코드가 어디에 있나” 가 궁금해지는 시점이 라이선스를 받아 fork 할 때입니다.