jayabdulraman/setup-prototype-project

Setup Prototype Project (프로토타입 프로젝트 설정)

아이디어를 실제로 작동하는 웹 앱으로 만들고, 라이브 링크로 공유하세요. 사용자는 방향과 판단을 제공하고, 당신은 기술 작업을 수행합니다.

기술 스택

계층	기본 도구
인터페이스 (사용자가 보고 클릭하는 부분)	Next.js (App Router) + TypeScript + Tailwind + shadcn/ui (기본 UI, 중립 테마, Lucide 아이콘, Sera 스타일) - 하나의 shadcn 프리셋 사용
서버 작업 (비밀 키, 외부 API, AI 호출)	Next.js Server Actions
데이터	브라우저 내 IndexedDB (Dexie). Supabase CLI는 나중을 위해 설치
호스팅 및 공유	Vercel
설정 및 자동화	공식 CLI (vercel, supabase, gh, shadcn) + 이 스킬의 스크립트

IndexedDB가 우선입니다: 계정 불필요, 키 불필요, 오프라인 작동. 데이터를 여러 사람이나 기기 간에 공유해야 하거나, 로그인이 필요하거나, 서버/예약 작업이 데이터를 읽어야 할 때만 Supabase로 이동하세요 (references/7-extend.md 참조).

항상 최신 안정 버전 사용 (허락 불필요)

• 업그레이드는 승인이 필요하지 않습니다. 단, 한 가지 예외가 있습니다: 서드파티 Homebrew 탭(예: supabase/tap)에서 가져온 도구. 이러한 탭을 신뢰하기 전과 설정 중 탭에서 업그레이드할 때마다 승인을 요청하세요(이전에 승인받았더라도 다시 요청).
• 그 외에는 모든 CLI와 패키지를 최신 안정 버전으로 업데이트하세요: npm i -g <cli>@latest, brew upgrade, winget upgrade, Node.js 최신 LTS, 프로젝트 내에서는 npm outdated --json | jq -r 'keys[] + "@latest"' | xargs npm i. 업그레이드한 내용을 한 줄로 알려주세요.
• 사용자가 요청하지 않는 한 canary, beta, rc, next 태그를 사용하지 마세요. 기억이나 이 문서에서 버전을 고정하지 마세요.
• 업그레이드 후 검사(lint, typecheck, build)를 실행하세요. 실패하면 오류를 읽고 문제를 일으킨 패키지를 찾아 해당 패키지만 이전 메이저의 최신 릴리스로 다운그레이드(npm i -D <pkg>@^<major-1>)하고 다시 실행하세요. 고정 사유와 함께 PROTOTYPE.md Decisions에 기록하세요. 예: TypeScript 7이 ESLint의 TypeScript 플러그인을 깨뜨리면 typescript@^6을 고정하고 나머지는 최신 상태 유지.
• 기존 프로토타입을 재개할 때도 새 작업 전에 동일한 업그레이드-및-검사 과정을 수행하세요.

단계별 빌드 과정

해당 단계의 참조 파일에 도달했을 때 읽으세요. 미리 모든 파일을 읽지 마세요.

단계	사용자 작업	당신의 작업	참조
1. 설정	폴더 선택	도구 및 의존성 확인, 누락된 항목 설치, 앱 스캐폴딩	references/1-setup.md
2. 연결	승인, 브라우저에서 한 번 로그인	각 CLI 로그인 실행, 작동 확인, 앱 키를 OS 자격 증명 저장소에 저장	references/2-connect.md
3. 명세	아이디어 구체화	짧은 질문 라운드 진행, SPEC.md 작성	references/3-spec.md
4. 빌드	반응, 방향 제시	한 번에 하나의 기능 빌드, 실행 상태 보여주기	references/4-build.md
5. 테스트	직접 사용해보기	검사 실행, 실제 브라우저에서 테스트, 수정	references/5-test.md
6. 배포	승인, 공유	Vercel에 키 동기화, 배포, 링크 전달	references/6-ship.md
언제든지	새 기능 요청	도구의 CLI 또는 스킬 찾기, 설치 및 연결 요청	references/7-extend.md

결과: localhost에서 작동하는 앱, 그 다음 누구나 열 수 있는 라이브 링크.

플랫폼

	macOS	Windows	Linux
이 스킬 스크립트용 셸	Terminal (zsh/bash)	Git Bash (Git for Windows에 포함)	bash
CLI용 패키지 매니저	Homebrew	winget (Supabase는 Scoop)	Linux용 Homebrew, 또는 npm
앱 키 저장 위치	Keychain	자격 증명 관리자	Secret Service (secret-tool); 없으면 git이 무시하는 .env.local

• bash <절대 경로>로 스크립트를 실행하세요. Windows에서 PowerShell 또는 cmd에서 bash를 바로 실행하면 WSL이 시작될 수 있습니다. 대신 & "$env:ProgramFiles\Git\bin\bash.exe" <스크립트>를 사용하세요. Windows의 Claude Code는 이미 Git Bash에서 셸을 실행합니다.
• WSL은 Linux로 간주되지만, secrets.sh는 Windows 자격 증명 관리자에 접근 가능할 때 powershell.exe를 통해 사용합니다.
• 클라우드 동기화 폴더(Dropbox, OneDrive, iCloud, Google Drive)도 괜찮습니다. Dropbox 폴더에서 스캐폴딩 직후 bash SKILL/scripts/ignore-sync.sh <project>를 실행하여 Dropbox가 node_modules, .next 및 테스트 출력을 동기화하지 않도록 하세요.

진행 파일

모든 프로토타입은 루트에 PROTOTYPE.md(템플릿: templates/PROTOTYPE.md)를 가집니다. 단계 체크리스트, 도구 목록(도구, 버전, 전역 또는 프로젝트 설치), 키 이름(값은 절대 안 됨), 결정 사항, 링크를 보관합니다.

• 각 단계가 끝날 때와 도구가 추가될 때마다 업데이트하세요.
• 기존 프로토타입 내에서 호출되면 먼저 PROTOTYPE.md를 읽고 첫 번째 체크되지 않은 단계부터 재개하세요. 사용자가 단계를 명명하면(예: "배포하자") 해당 단계로 이동하되, 먼저 해당 단계의 검사를 실행하세요.
• 모든 단계가 완료되었고 사용자가 새로운 것을 원하면: SPEC.md(필수 사항 + 수용 테스트)와 PROTOTYPE.md의 Features에 추가하고, 새 도구가 필요하면 references/7-extend.md를 실행한 후 해당 기능에 대해 Build → Test → Ship 루프를 반복하세요.

당신이 모든 명령을 실행합니다

사용자는 방향과 승인을 제공합니다. 당신이 모든 명령을 직접 실행하세요. 사용자에게 명령을 입력하거나 붙여넣도록 요청하지 마세요.

• 승인 불필요: 정보 조회, 업그레이드(위 참조), 사용자가 프로토타입을 요청한 후 기본 스택 및 의존성 설치. 설치하는 내용과 이유를 한 줄로 알린 후 실행하세요.
• 먼저 요청 (한 문장으로 이유를 설명하고, 예스가 나오면 직접 실행하세요. 하나의 예스로 나열된 배치를 승인할 수 있습니다):
  • CLI에 로그인
  • 보안 설정 변경(예: Homebrew 탭 신뢰(brew trust supabase/tap), 서드파티 탭에서 도구 업그레이드)
  • 기본 스택 외 도구 설치(references/7-extend.md)
  • 클라우드 리소스 생성(Vercel 프로젝트, Supabase 프로젝트, GitHub 저장소, 마켓플레이스 통합)
  • 프로덕션 배포
  • 명세 확정 및 Spec에서 Build로 이동
• 사용자의 요청이 이미 "라이브 링크까지 가져가라"와 같이 최종 단계까지를 포함한다면, 그것이 Vercel 프로젝트 및 프로덕션 배포에 대한 승인입니다. 그래도 실행 전에 무엇을 할 것인지 한 줄로 말하세요.

명령이 사용자의 상호작용(브라우저 로그인, 인증 코드, 관리자 비밀번호)을 필요로 할 때:

1. 어떤 일이 발생하고 사용자가 무엇을 보게 될지 설명하세요.
2. 사용자가 보고 응답할 수 있는 곳에서 실행하세요: 에이전트 앱의 터미널 패널("run in terminal" 도구)이 있다면 거기서. 각 로그인에 이름을 딴 새 탭("Vercel 로그인", "GitHub 로그인")을 할당하세요. 다른 용도의 탭을 재사용하지 마세요. 해당 탭으로 터미널 패널을 표시("show pane" 도구)하고 메시지에서 탭을 링크하세요. 패널이 없으면 사용자를 위해 터미널 창을 여세요(macOS: osascript -e 'tell application "Terminal" to do script "cd <project> && <command>"', Windows: start "" "%ProgramFiles%\Git\git-bash.exe" -c "<command>; read").
3. 사용자가 "완료"라고 말할 때까지 기다린 후 직접 확인하세요(vercel whoami, gh auth status, ...). 사용자의 말만으로 단계 완료를 표시하지 마세요.

비밀 (API 키, 토큰) 처리 순서:

1. 자동 우선: Vercel Marketplace 통합 (키가 Vercel에 도착한 후 secrets.sh pull-vercel), 또는 제공자 CLI의 키 출력을 secrets.sh set NAME --stdin으로 직접 파이프. 사용자는 키를 보거나 붙여넣지 않습니다.
2. 대화형 마지막 수단: 서비스가 위 두 가지를 모두 제공하지 않을 때만 bash SKILL/scripts/secrets.sh ask NAME "찾을 수 있는 위치"를 실행하세요. 사용자 화면에 입력이 숨겨진 대화상자를 열고 값을 OS 자격 증명 저장소에 저장합니다. 어떤 정보도 채팅이나 출력을 통과하지 않습니다. 먼저 대화상자가 나타날 것과 이유를 사용자에게 알리세요. 절대 채팅으로 비밀을 요구하지 말고, 출력하지 말고, 코드나 커밋된 파일에 작성하지 마세요.

셸의 작업 디렉토리는 호출 사이에 재설정될 수 있습니다: 모든 프로젝트 명령을 cd "<project>" &&로 시작하세요. 장기 실행 명령(npm run dev)은 백그라운드로 보내세요.

사용자와 대화하는 방법

• 각 작업 전에, 그 작업이 사용자에게 어떤 이점을 주는지 한 문장으로 설명: "목록이 방문 사이에 저장되도록 브라우저 데이터베이스를 추가합니다."
• 각 단계 후에, 2-3줄의 요약: 이제 무엇이 작동하는지, 무엇을 시도해볼 수 있는지, 다음 단계는 무엇인지.
• 실제 선택 사항이 있을 때는 2-3개의 옵션과 추천을 제시하세요. 그 외에는 합리적인 기본값을 선택하고 무엇을 선택했는지 말하세요.
• 보여주고 설명하지 마세요: 모든 눈에 보이는 변경 후에 localhost(또는 스크린샷)를 여세요.
• 오류: 먼저 직접 수정하세요. 결정, 승인, 또는 로그인/비밀번호/키를 위한 사용자의 도움이 필요할 때만 사용자를 참여시키세요.

번들 파일

• scripts/preflight.sh [dir] — 도구, 의존성, 설치된 버전과 최신 버전 비교, 로그인 상태, 폴더 확인
• scripts/secrets.sh — OS 자격 증명 저장소(ask는 입력이 숨겨진 대화상자 열기), 키로 실행, .env.local 내보내기, Vercel 푸시/풀 (help 사용법 참조)
• scripts/ignore-sync.sh <project> — Dropbox가 node_modules, .next 및 테스트 출력을 동기화하지 않도록 설정
• scripts/wincred.ps1 — secrets.sh에서 사용하는 Windows 자격 증명 관리자 도우미 (직접 호출 금지)
• scripts/discover.sh <tool> — 새 도구의 CLI, npm 패키지, 스킬에 대한 초기 조회
• scripts/install.sh — 이 스킬을 전역으로 설치 (실패 시 프로젝트 수준으로 대체)
• templates/ — PROTOTYPE.md, SPEC.md, AGENTS.section.md, db.ts, actions.ts, smoke.spec.ts, playwright.config.ts

이 문서에서 SKILL은 이 스킬의 폴더를 의미합니다(예: ~/.agents/skills/setup-prototype-project). 스크립트를 실행할 때는 절대 경로로 확장하세요: bash ~/.agents/skills/setup-prototype-project/scripts/preflight.sh.

일반적인 실수

실수	대신
사용자에게 명령을 실행하거나 붙여넣도록 요청	설명하고, 승인을 받고, 직접 실행 (로그인 시 터미널을 보이게).
사용자가 완료했다고 해서 로그인 완료 처리	CLI로 직접 확인 (vercel whoami, gh auth status, supabase projects list).
Dropbox가 node_modules 동기화하도록 방치	스캐폴딩 직후 ignore-sync.sh 실행.
의존하는 도구를 먼저 설치하지 않고 CLI 설치	1-setup.md의 설치 순서 따르기 (패키지 매니저 → git → Node.js → npm CLIs).
기억에서 설치 (npm i next@15)	@latest 안정 버전 사용; 검사 실패 시에만 하나의 패키지 다운그레이드.
첫날부터 Supabase 사용	IndexedDB로 시작; 공유나 로그인이 필수가 될 때 업그레이드.
Server Component나 Server Action에서 IndexedDB 호출	IndexedDB는 브라우저에만 존재. "use client" 컴포넌트에서 사용.
API 키를 NEXT_PUBLIC_ 변수에 저장	NEXT_PUBLIC_은 모든 방문자에게 전달. Server Actions에서 키를 서버 측에 유지.
아무것도 보여주기 전에 모든 기능 빌드	한 번에 하나의 기능, 실행 상태를 보여주고 반응.
키 동기화 없이 배포	모든 배포 전에 secrets.sh diff-vercel 실행.
IndexedDB를 읽는 예약 작업 설정	서버 작업은 브라우저 데이터를 볼 수 없음. 먼저 데이터를 Supabase로 이동 (7-extend.md).
로그아웃 상태로 열어보지 않고 링크 전달	공유 전에 프로덕션 URL이 200을 반환하는지 확인 (6-ship.md).
검색 결과에서 도구를 게시자 확인 없이 설치	공급업체의 공식 CLI, 패키지 또는 스킬 선호. 요청 시 게시자 표시.