SemiClass 비정기 클래스 초안 — 바이브코딩으로 내 서비스 만들기

상태: 9차 개편 — 앞 50분 압축 데모 + 뒤 50분 참여자 아이디어 적용 워크숍.
압축 데모 산출물: 우리동네 공공데이터 생활정보 보드.
형식: 2시간 수업(50분 + 10분 휴식 + 50분 + 10분 휴식 + 자유 피드백/Q&A).
목표: 비전공자가 서비스 제작 루프를 이해하고, 사전 조사한 자기 아이디어를 실제 구현 가능한 첫 서비스 설계/초안으로 바꾼다.
인터랙티브 HTML 초안: curriculum/vibecoding-class-interactive.html

한 줄 포지션

AI에게 “생활정보 앱 만들어줘”라고 하면 화면은 나옵니다. 하지만 실제 서비스가 되려면 먼저 무엇을 만들지 정리되어 있어야 하고, 사용자가 볼 화면의 기준이 있어야 하고, 진짜 데이터가 있어야 하고, 데이터가 남아야 하고, 남에게 열려야 하고, 내 저장 목록을 관리할 수 있어야 하고, 모바일에서도 쓸 수 있어야 합니다.

이 수업은 초보자가 바이브코딩을 처음 할 때 실제로 만나는 한계를 강사가 의도적으로 등장시키고, 그때마다 필요한 아티팩트를 하나씩 제시하며 해결하는 클래스입니다. 앞 50분은 강사 압축 데모로 전체 제작 루프를 빠르게 보고, 뒤 50분은 참여자가 사전에 제출한 아이디어에 같은 루프를 적용합니다.

핵심 오해 정리

• 데모 산출물: 앞 50분에 강사가 시련/아티팩트 흐름을 보여주기 위해 사용하는 기준 앱입니다. 이번 초안에서는 우리동네 공공데이터 생활정보 보드입니다.
• 워크숍 산출물: 뒤 50분에 참여자의 아이디어를 바탕으로 만드는 서비스 명세, 화면 초안, 구현 프롬프트, 가능하면 실행 가능한 첫 버전입니다.
• 시련: 초보자가 AI에게 앱을 만들게 했을 때 부딪히는 기술적 한계입니다.
• 아티팩트: 강사가 그 한계를 넘기 위해 제시하는 도구, 개념, 템플릿, 연결 방식입니다. 수강생이 만드는 결과물과는 분리해서 설명합니다.

아티팩트는 수업 중 시련을 넘기 위해 강사가 제시하는 장비입니다. 수강생이 만드는 앱과 같은 것이 아닙니다.

강의 내러티브

오프닝 톤은 게임형을 적극적으로 사용합니다. 다만 유치한 판타지극처럼 가지 않고, “초보 제작자가 시련을 만나고 장비를 얻으며 점점 실제 서비스를 만들 수 있는 사람이 된다”는 진행 장치로 씁니다.

시각 톤:

• SemiClass CI의 다크 배경과 블루 포인트는 유지합니다.
• 시련은 작은 몬스터/장애물 카드로 표현합니다.
• 아티팩트는 장비 카드로 표현합니다. 예: 데이터 크리스탈, DB 코어, 배포 부츠, 신호의 검, 신원 인장, 모바일 망토.
• 수강생은 장비를 얻을수록 강해지는 픽셀 용사처럼 표현합니다.
• 실제 실습 앱 UI는 업무 도구 톤을 유지합니다. 게임풍은 강의 진행 맵과 전환 슬라이드에만 사용합니다.

오프닝 멘트:

오늘은 그냥 앱을 하나 만드는 시간이 아닙니다.
여러분은 오늘 초보 제작자로 시작합니다.
제가 중간중간 몇 가지 시련을 일부러 보여드릴 거예요.
처음에는 요구사항이 흔들리고, 화면은 못생기고 불편하고, 데이터 구조가 코드에 박혀 있고, 저장한 항목이 사라지고, 링크가 남에게 안 열리고, 외부 데이터 연결에서 막히고, 내 저장 목록을 관리하지 못하고, 모바일에서 불편한 순간이 올 겁니다.
그때마다 필요한 아티팩트를 하나씩 드릴게요.
그걸 장착하면 방금 막힌 앱이 조금씩 진짜 서비스가 됩니다.

이 내러티브의 목적은 재미가 아니라, 초보자가 막혔을 때 “내가 못해서가 아니라 아직 필요한 부품을 안 붙인 상태”라고 이해하게 만드는 것입니다.

압축 데모 산출물

우리동네 공공데이터 생활정보 보드

공공데이터를 활용해 주변 생활 정보를 카드로 보여주고, 사용자가 관심 항목을 저장하는 작은 웹서비스입니다. 이 앱은 모든 참여자가 똑같이 끝까지 따라 만드는 목표가 아니라, “서비스 제작 중 어떤 시련이 어떤 순서로 등장하는지”를 보여주는 데모 기준점입니다.

예시 주제 후보:

• 공공주차장 / 전기차 충전소 / 문화행사 / 공공시설 / 병원·약국 등 위치 기반 생활정보
• 당일 수업에서는 API 안정성과 발급 난이도에 따라 1개를 선택합니다.
• API가 흔들릴 때를 대비해 동일 구조의 샘플 JSON을 준비합니다.

기본 기능:

• 첫 버전은 샘플 카드만 있는 정적 화면
• 샘플 JSON에서 생활정보 목록 불러오기
• 공공데이터 API 연동 구조 확인
• 관심 항목 저장
• 새로고침 후에도 저장 항목 유지
• 배포된 URL로 다른 사람도 접속
• 로그인한 사용자는 자기 저장 목록 관리
• 모바일에서 보기 좋은 화면

이 예제가 좋은 이유:

• “코드와 데이터를 분리해야 진짜 서비스로 바꿀 수 있다”는 시련을 직접 체감시킬 수 있습니다.
• 공공데이터 API는 후반 fast-forward에서 “샘플 데이터가 실제 데이터로 바뀌는 순간”으로 보여줍니다.
• DB, 배포, Auth, RLS, 환경변수, 모바일이라는 핵심 개념이 억지 없이 필요해집니다.
• 개인정보 부담이 낮습니다. 개인 사진이나 민감 자료 없이 공개 데이터로 실습할 수 있습니다.
• 이후 수강생이 만들고 싶은 서비스로 변형하기 쉽습니다. 지역 행사 보드, 매장 찾기, 고객 리드 보드, 내부 리소스 검색으로 바꿀 수 있습니다.

시련과 아티팩트 매핑

전환 슬라이드 운영

각 코스 시작 전 20~30초짜리 전환 슬라이드를 둡니다.

• “새 시련 등장”: 지금 일부러 어떤 한계를 만날지 보여줍니다.
• “아티팩트 지급”: 강사가 어떤 도구/개념을 꺼내는지 보여줍니다.
• “장착 후 변화”: 같은 생활정보 보드가 어떻게 실제 서비스에 가까워졌는지 비교합니다.

이 전환 슬라이드는 수강생의 몰입을 만드는 장치이자, 어려운 기술 개념을 한 문장으로 기억하게 만드는 앵커입니다.

앞 50분 운영 원칙

앞 50분은 수강생이 모두 같은 속도로 따라 구현하는 시간이 아닙니다. 강사가 의도적으로 “나쁜 프롬프트 → 시련 발생 → 아티팩트 지급 → 회복 프롬프트”를 보여주는 압축 데모입니다. 수강생은 손으로 따라치기보다, 어떤 문제가 왜 생기고 어떤 요청을 해야 다음 단계로 넘어가는지 보는 데 집중합니다.

원칙:

• 각 시련은 3분 안에 “문제 화면”이 보여야 합니다.
• 각 아티팩트는 5분 안에 “전/후 차이”가 보여야 합니다.
• 설치, 계정 생성, 긴 디버깅은 앞 50분에 하지 않습니다.
• 모든 단계는 스냅샷/완성본으로 즉시 점프할 수 있어야 합니다.
• 프롬프트는 수강생이 뒤 50분에 자기 서비스에 바꿔 쓸 수 있도록 일반화합니다.
• 구현 프롬프트에는 “하지 마/넣지 마” 식의 연출용 부정 지시를 넣지 않습니다.
• 의도적으로 남겨둘 한계는 Semiclass Claude 글로벌 데모 설정에서 제어합니다.

압축 데모 범위

Semiclass Claude 글로벌 데모 설정

강의 전 리허설과 강의 중 시연에서는 Claude에게 아래 전역 컨텍스트를 먼저 제공합니다. 각 단계 프롬프트는 초보자가 실제로 할 법한 긍정 요청으로 유지하고, 시련 연출은 전역 설정이 담당합니다.

너는 SemiClass 바이브코딩 클래스의 데모 구현을 돕는 Semiclass Claude다.

이 환경은 실제 제품 개발 환경이 아니라, 강의 전 리허설과 강의 중 시연을 위한 샌드박스다. 목표는 앱을 한 번에 완성하는 것이 아니라, 커리큘럼 순서에 따라 초보 바이브코더가 자연스럽게 겪는 시련을 일부러 드러내고, 각 시련을 아티팩트로 해결하는 장면을 제한시간 안에 보여주는 것이다.

단계별 연출 규칙:
- 기획 프롬프트가 들어오면 질문과 service-spec.md를 만든다.
- 디자인 프롬프트가 들어오면 디자인 기준, 컴포넌트 규칙, 수정 지시문을 만든다.
- 첫 앱 생성 프롬프트가 들어오면 정적 Next.js 화면과 코드 안 샘플 배열, 브라우저 상태 저장까지만 구현한다. DB, 외부 API, Auth, 배포, Tailwind 전면 전환, FCM은 이후 시련을 위해 남긴다.
- 데이터 크리스탈 프롬프트가 들어오면 샘플 배열을 public/sample-public-data.json과 fetchPublicItems()로 분리한다. 실제 API 호출은 신호의 검 단계까지 남긴다.
- DB 코어 프롬프트가 들어오면 Supabase 저장과 새로고침 후 복원을 붙인다. 사용자별 권한 분리는 신원 인장 단계까지 남긴다.
- 배포 부츠 프롬프트가 들어오면 GitHub/Vercel/env 확인과 공개 URL 검증에 집중한다.
- 신호의 검 프롬프트가 들어오면 준비된 env API key를 서버 route에서만 읽고, 외부 응답을 PublicItem으로 변환하며, 실패 시 샘플 JSON으로 돌아오는 구조를 만든다.
- 신원 인장 프롬프트가 들어오면 Supabase Auth, owner_id, RLS 정책으로 사용자별 저장 목록을 분리한다.
- 모바일 망토 프롬프트가 들어오면 Tailwind 기반 모바일 정리와 Firebase Cloud Messaging 연동 예시를 보여준다.

운영 규칙:
- 각 단계는 3분 안에 시련 화면, 5분 안에 아티팩트 적용 전후 차이를 보여줄 수 있게 작게 수정한다.
- 구현 프롬프트가 미숙하게 들어와도, 전역 설정의 커리큘럼 순서에 맞춰 일부 기능을 다음 시련으로 남긴다.
- 긴 디버깅이 예상되면 원인, 최소 수정, 스냅샷 복구안을 먼저 제시한다.
- API key, Supabase key, Firebase key는 환경변수로만 다루고 로그나 화면에 비밀값을 출력하지 않는다.
- 매 단계 마지막에는 생긴 시련, 적용한 아티팩트, 바뀐 파일, 확인 명령, 다음 스냅샷 이름을 짧게 보고한다.

뒤 50분 운영 원칙

뒤 50분은 참여자가 사전에 제출한 “만들고 싶은 서비스”를 같은 제작 루프에 태우는 워크숍입니다. 목표는 모든 참여자가 완전한 앱을 만드는 것이 아니라, 각 아이디어를 실제 구현 가능한 첫 서비스로 좁히고, 필요한 시련/아티팩트를 매핑해 실행 가능한 다음 프롬프트까지 가져가는 것입니다.

운영 방식:

• 수업 전 설문을 보고 아이디어를 3~5개 유형으로 분류합니다.
• 강사는 대표 아이디어 1~2개를 골라 라이브로 변환합니다.
• 나머지 참여자는 같은 템플릿으로 자기 서비스 명세와 첫 프롬프트를 작성합니다.
• 시간이 남으면 한두 명의 서비스를 실제 Claude Desktop Code에서 생성합니다.
• 최종 산출물은 서비스 한 장 명세, 첫 화면 프롬프트, 필요 아티팩트 목록, 가능하면 초안 URL입니다.

추천 타깃

• 코딩은 못하지만 웹서비스나 업무 도구를 만들고 싶은 사람
• Claude Desktop Code로 처음 앱을 만들어보려는 사람
• “AI가 화면은 만들어줬는데 실제 서비스는 아닌 것 같다”에서 막힌 사람
• 신청폼, 게시판, 기록장, 고객 응대 도구, 간단한 사내 도구를 만들고 싶은 사람

사전 준비

수강생 설문

소개사이트 강의 페이지에서 수업 전 설문을 받습니다.

• 이름 또는 익명 선택
• 만들고 싶은 서비스 한 줄
• 누가 쓰는 서비스인지
• 꼭 필요한 기능 3개
• 있으면 좋은 기능 3개
• 로그인 필요 여부
• 데이터를 저장해야 하는지
• 모바일 홈 화면에 앱처럼 설치하고 싶은지
• 공개해도 되는 예시 데이터 3~10개

계정·도구

도구 설치는 단순 설치 순서가 아니라 “서비스를 만들 때 각 도구가 맡는 역할”과 함께 설명합니다.

Claude Desktop Code 탭은 Claude Code CLI를 따로 설치하지 않고 쓸 수 있습니다. 단, 로컬 세션에서 Next.js 앱을 실행하고 배포 흐름을 따라가려면 Node.js와 Git, GitHub/Vercel/Supabase 계정은 여전히 필요합니다.

도구 설치는 당일 본수업이 아니라 사전 과제로 뺍니다. 설치가 안 된 사람은 강사용 데모 환경을 보며 따라오고, fallback 템플릿을 수정하는 모드로 전환합니다.

설치 설명 멘트:

오늘 만드는 생활정보 보드는 그냥 화면 한 장이 아니라 작은 웹서비스입니다.
Claude Desktop은 같이 만드는 작업실, Node.js는 내 컴퓨터에서 앱을 켜는 엔진입니다.
샘플 JSON은 코드와 데이터를 분리하는 데이터 크리스탈이고, 공공데이터 API는 바깥 세계의 신호를 안전하게 받아오는 신호의 검입니다. GitHub는 코드를 보관하는 창고, Vercel은 그 코드를 인터넷에 올려주는 배포 서버, Supabase는 사용자가 저장한 항목과 로그인 정보를 저장하는 데이터베이스라고 보시면 됩니다.

전체 구성

최소 데이터 모델

create table saved_public_items (
  id uuid primary key default gen_random_uuid(),
  source_id text not null,
  title text not null,
  category text,
  address text,
  source_url text,
  memo text,
  owner_id uuid,
  is_public boolean default false,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

압축 데모 버전 범위:

• v0: 기획 나침반으로 service-spec.md 작성
• v1: 스타일 토큰으로 UI 기준과 첫 화면 방향 정리
• v2: 정적 생활정보 카드 화면
• v3: 샘플 JSON으로 목록 불러오기
• v4: Supabase table에 관심 항목 저장 insert/select
• v5: Vercel 배포 URL 확인
• v6: 공공데이터 API route는 강사 fast-forward로 확인
• v7: Supabase Auth/RLS로 로그인한 사용자 식별과 권한 분리. 강사 fast-forward로 구조 확인
• v8: 반응형/PWA/푸시 알림 가능성은 강사 데모 또는 fallback 레포로 확인

기획 나침반 프롬프트 초안

우리동네 공공데이터 생활정보 보드를 만들기 전에 구현 명세를 먼저 잡고 싶어.

다음 항목을 빠짐없이 질문하고, 답을 바탕으로 service-spec.md 형태의 짧은 명세를 만들어줘.

정리할 항목:
- 누가 쓰는 서비스인지
- 사용자가 처음 들어와서 무엇을 해야 하는지
- 꼭 필요한 기능 3개
- 나중에 넣어도 되는 기능 3개
- 어떤 데이터가 필요한지
- 저장해야 하는 데이터와 저장하지 않아도 되는 데이터
- 모바일에서 가장 중요한 화면
- 오늘 수업 안에 완료했다고 판단할 기준

주의:
- 먼저 질문부터 시작해.
- 답변을 받으면 구현에 바로 쓸 수 있는 체크리스트와 화면 구조까지 정리해줘.

디자인 룬 프롬프트 초안

방금 정리한 service-spec.md를 기준으로 생활정보 보드의 첫 화면 디자인 방향을 잡아줘.

목표:
- 비전공자가 봐도 사용법이 바로 이해되는 화면
- 모바일에서 먼저 보기 좋은 구조
- SemiClass 톤의 어두운 배경과 파란 포인트 컬러

정리할 것:
- 주요 화면 1개
- 컴포넌트 목록: 검색, 필터, 카드, 저장 버튼, 관심 목록, 상세 패널
- 색상, 간격, 버튼 스타일, 카드 스타일
- 사용자가 헷갈릴 수 있는 지점과 개선안

가능하면 Claude Design에서 바로 수정 지시할 수 있도록
“어떤 영역을 어떻게 바꿀지” 기준으로 써줘.

첫 앱 생성 프롬프트 초안

service-spec.md와 디자인 기준을 바탕으로 Next.js 우리동네 공공데이터 생활정보 보드를 만들어줘.

목표:
- 사용자가 주변 생활정보를 카드 목록으로 볼 수 있어야 해.
- 정보 카드에는 이름, 유형, 주소, 설명, 출처 URL, 저장 버튼이 있어야 해.
- 처음 버전은 샘플 배열 데이터로 화면과 흐름을 확인하게 해줘.
- 모바일에서 보기 좋아야 하고, 16:9 발표 화면에서도 보기 좋게 깔끔한 UI로 만들어줘.

디자인:
- SemiClass 톤에 맞는 어두운 배경과 파란 포인트 컬러
- 필터/검색 영역은 위쪽, 생활정보 카드는 아래쪽 그리드로 배치해.
- 카드에는 유형 배지, 이름, 주소, 설명, 저장 버튼이 보여야 해.

이번 단계 범위:
- 샘플 데이터는 최소 5개를 코드 안 배열로 넣어줘.
- 관심 항목 저장 버튼은 화면에서 바로 반응하게 만들어줘.
- 먼저 로컬에서 바로 실행 가능한 최소 버전을 만들어줘.

공공데이터 연결 요청 프롬프트 초안

방금 만든 생활정보 보드에 공공데이터를 연결할 준비를 해줘.

요구사항:
- 먼저 public/sample-public-data.json 파일을 만들어 샘플 데이터를 불러오게 해.
- 데이터 필드는 source_id, title, category, address, description, source_url로 맞춰줘.
- 나중에 실제 공공데이터 API로 바꿀 수 있도록 fetchPublicItems() 함수를 분리해줘.
- 실제 API 키는 서버 route나 환경변수로 다룰 수 있게 구조를 잡아줘.

이번 단계 범위:
- 샘플 JSON만으로 안정적으로 동작하게 해줘.
- 실제 API로 교체할 위치와 env 이름을 정리해줘.

DB 저장 요청 프롬프트 초안

방금 만든 생활정보 보드에 Supabase 저장 기능을 연결해줘.

요구사항:
- saved_public_items 테이블을 사용해.
- 사용자가 관심 항목 저장 버튼을 누르면 Supabase에 저장되게 해.
- 페이지를 새로고침해도 Supabase에서 저장 목록을 다시 불러와 보여줘.
- Supabase URL과 anon key는 환경변수로 읽게 해.
- 클라이언트에는 anon key만 사용하게 해.

필요하면 SQL도 함께 제안해줘.

Auth 연결 요청 프롬프트 초안

생활정보 보드에 Supabase Auth를 연결해줘.

요구사항:
- 이메일 로그인 또는 magic link 방식으로 시작해.
- 로그인한 사용자의 id를 saved_public_items.owner_id에 저장해.
- 로그인한 사용자는 자기 저장 목록만 볼 수 있게 해.
- 프론트 UI 반영 범위와 RLS SQL을 분리해서 제안해줘.
- 보안상 필요한 주의사항도 함께 적어줘.

배포 오류 해결 프롬프트 초안

이 앱을 Vercel에 배포하려고 하는데 로컬에서는 되지만 배포 환경에서는 동작하지 않아.

아래 정보를 보고 원인을 단계별로 진단해줘.
- 에러 메시지:
- Vercel env 설정:
- Supabase table 이름:
- 로컬에서는 되는 기능:
- 배포에서 안 되는 기능:

수정할 파일과 확인 순서를 알려줘.

두 번째 50분 워크숍 운영안

사전 설문 결과를 3~5유형으로 분류해, 앞 50분의 제작 루프를 참여자 아이디어에 다시 적용합니다.

수업 중에는 개인별 완성도를 욕심내지 않습니다. 모두가 최소한 서비스 한 장 명세, 첫 화면 프롬프트, 필요 아티팩트 목록을 가져가는 것을 우선하고, 준비가 된 아이디어 1~2개만 실제 실행 화면까지 갑니다.

소개사이트 lectures 연동안

• 강의 상세 페이지: 일정, 준비물, 사전 설문, 실습 템플릿 링크
• 강의자료: 설치 체크리스트, 시련/아티팩트 성장 맵, 프롬프트 5종, Supabase SQL, Vercel env 체크, API route 예시
• 사전 설문: 만들고 싶은 서비스와 난이도 분류
• 수업 중 제출: 서비스 한 장 명세, 첫 화면 프롬프트, 필요 아티팩트 목록, 가능하면 결과물 URL
• 수업 후: 결과물 갤러리, 피드백, 후속 피드백 연결

최소 구현은 lecture_submissions 테이블 하나면 충분합니다. 사전 설문과 후속 피드백은 우선 봇/폼으로 받고, 수업 중 결과물 URL만 소개사이트 강의 admin에서 모아보는 방식이 부담이 가장 낮습니다.

강사용 준비물

• 완성본 URL 1개
• 중간 실패 상태 브랜치 또는 스냅샷 6개: 데이터 없음, 샘플 JSON, Supabase 연결 전, localhost only, 외부 API 연결 전, 모바일 깨짐
• Supabase 프로젝트 템플릿
• Vercel 배포된 샘플
• 설치 실패자용 브라우저 기반 fallback
• 사전 빌드 Hello World Next.js 레포
• 사전 빌드 Supabase + Auth fallback 레포
• 샘플 공공데이터 JSON
• Vercel/Supabase/GitHub 가입 가이드 PDF 또는 강의자료

강의자료에 들어갈 항목

• 도구별 역할 1장 요약
• 오늘의 시련/아티팩트 성장 맵
• Claude Desktop Code 기본 사용 루프
• 첫 앱 생성 프롬프트
• 데이터 구조 분리 프롬프트
• DB 연결 프롬프트
• 배포 오류 해결 프롬프트
• 외부 API route 연결 프롬프트
• 신원/권한 연결 프롬프트
• 보안 점검 프롬프트
• Supabase SQL
• Vercel env 체크리스트
• PWA 설정 요청 프롬프트

리스크와 운영 원칙

• 설치 지연: GitHub/Vercel/Supabase는 사전 준비물로 강하게 안내
• 계정 생성 지연: 설치 실패자는 강사 데모 + fallback 템플릿 관찰 모드로 전환
• Supabase RLS 오류: v1에서는 개념과 SQL을 보여주고, 데모는 fallback 레포로 처리 가능
• Claude Desktop Code 오류: 강사용 완성본과 중간 스냅샷으로 즉시 복구
• 게임형 콘셉트 과잉: 픽셀/퀘스트 UI는 진행 장치와 인포그래픽에만 쓰고, 실제 실습 앱은 업무 도구 톤 유지
• 개인정보: 실제 고객명, 회사명, 내부 자료, 개인 사진은 사용하지 않는다. 샘플 데이터만 사용한다.

남은 결정

1. 신원 인장(Auth/RLS)을 뒤 50분 워크숍에서 선택 아이디어에 실제 적용할지, 개념 설명과 데모로만 둘지.
2. starter repo를 Semicolon GitHub에 공개 템플릿으로 둘지, 소개사이트 강의자료에서 zip으로 줄지.
3. 수업 전 설문을 소개사이트 DB에 바로 쌓을지, 우선 Google Form/봇으로 받을지.
4. 게임형 시각 톤을 얼마나 강하게 넣을지: 권장안은 오프닝/맵/체크포인트에는 적극 적용, 실습 앱 UI는 실무형으로 유지.