create-saas-starter-workspace 0.1.0

package/templates/workspace/web/AGENTS.md

@@ -0,0 +1,103 @@
+# my-space
+
+무료 티어 기반 웹 SaaS 스타터. Owner는 결정하고 confirm하며, 실행은 AI가 한다.
+
+<!-- BEGIN:nextjs-agent-rules -->
+## Next.js 주의: 학습 데이터와 다름
+
+이 버전은 breaking change가 있다. API·관례·파일 구조가 학습 데이터와 다를 수 있으니, 코드를 쓰기 전 `node_modules/next/dist/docs/`의 관련 문서를 읽는다. deprecation 경고를 따른다.
+<!-- END:nextjs-agent-rules -->
+
+## 배포 시나리오 (v1)
+
+1. `/warmup` — 외부 CLI 로그인 검증, 의존성 install·audit
+2. `/go-live` — 클라우드 리소스(GitHub·Vercel·Supabase dev/prod·Sentry) 생성, 첫 배포, 보안 진단
+3. `/probe <아이디어>` — 적응형 인터뷰로 요구사항 도출
+4. `/sketch` — shadcn과 프로젝트 디자인 컨벤션 기반 시안
+5. TDD 개발 — Vitest 테스트 작성, 통과, 커밋을 반복
+6. `git push` — CI 통과 시 Vercel 자동 배포
+
+`node_modules/`가 없으면 `/warmup`을, `.vercel/`이 없으면 `/go-live`를 먼저 실행한다.
+
+## AI 도구 (CLI)
+
+AI는 아래 CLI로 클라우드를 직접 조작한다. 가역성 등급에 따라 자동 실행하거나 Owner confirm을 받는다.
+
+| CLI | 주요 작업 | 가역성 |
+| --- | --- | --- |
+| `gh` | repo·visibility·secrets·secret scanning·PR·이슈 | 대부분 자동, repo 삭제·public 전환은 확인 |
+| `vercel` | env vars·project link·deploy·logs·domains | 자동, prod env 삭제·도메인 변경은 확인 |
+| `pnpm exec supabase` (web/에서) | projects·migration·db push·gen types·link | dev 자동, prod `db push`·`db reset`은 확인 |
+| `sentry-cli` | organization·project 조회/생성, sourcemap·release | 자동 |
+| `pnpm` | install·add·remove·audit·dlx | 자동, major 업그레이드는 확인 |
+| `curl` + Supabase Management API | Auth redirect URL 등 CLI 미커버 항목 | 자동 (PAT = `supabase login`이 저장한 토큰, `/warmup`이 로그인을 점검) |
+| `git` | 표준 | 자동, force push·hard reset은 확인 |
+
+비가역·고위험은 반드시 Owner confirm: prod DB 마이그레이션, prod env 삭제, repo public 전환, prod `db reset`, main force push.
+
+Owner가 직접(CLI 미지원, AI는 안내만): 카드 결제, 도메인 DNS 변경, Supabase Personal Access Token 발급, Sentry Auth Token 발급(대시보드 Settings → Auth Tokens).
+
+## 핵심 코드 규칙
+
+- TDD 우선: 새 기능은 Vitest 테스트를 작성하고 통과시킨 뒤 커밋한다. 테스트는 `tests/`에 누적한다.
+- 로그(서버): `lib/logger.ts`를 쓴다. 에러는 Sentry로, 감사 로그는 Supabase `logs` 테이블로 보낸다.
+- 로그(클라이언트): 에러는 `Sentry.captureException()`(browser SDK), 영속 이벤트는 server action을 거쳐 `lib/logger.ts`, 일시 디버그는 `console.log`. `lib/logger.ts`는 server-only라 클라이언트에서 직접 import하지 않는다.
+- env: 클라이언트·일반 코드는 `import { env } from "@/lib/env"`(NEXT_PUBLIC_ 만). 서버 전용 키(SUPABASE_SECRET_KEY 등)는 `import { env } from "@/lib/env.server"`(server-only 가드). `process.env.X` 직접 접근은 빌드 시점 설정 파일(`next.config.*`, `sentry.{server,edge}.config.ts`, `instrumentation.ts`, `instrumentation-client.ts`, `vercel.json`)에서만 허용한다.
+- 보안 경계 (RLS 기본 + 서버측 처리):
+  - 노출되는 모든 테이블은 RLS를 켠다. 새 Supabase 테이블은 RLS 정책을 같은 마이그레이션 파일에 동봉한다(동봉하지 않으면 거부).
+  - 쓰기와 민감한 읽기는 서버측에서 한다(Server Component·Action의 쿠키 기반 user-scoped 클라이언트). queries·actions는 `repository.ts`에만 의존한다.
+  - realtime 구독과 storage signed-upload는 client-direct 경로를 유지한다.
+  - `service_role`은 server-only 관리 경로 전용이다. 여기서 '서버측'은 user-scoped 클라이언트를 뜻하며 `service_role`과 다르다.
+- secret key: `lib/supabase/admin.ts`에서만 쓴다(server-only 가드). `NEXT_PUBLIC_*` 접두사를 붙이지 않는다. auth 흐름에서 `admin.ts`를 import하지 않는다(RLS·세션 우회 위험).
+- Supabase Auth: `@supabase/ssr`을 쓴다. `@supabase/auth-helpers-nextjs`(deprecated)는 쓰지 않는다.
+- 환경 분기: 서버 코드는 `import { env } from "@/lib/env.server"` 후 `env.APP_ENV`를 비교한다(값: `production` | `preview` | `development`). `APP_ENV`는 벤더 중립 신호다. Vercel은 `VERCEL_ENV`를 여기 매핑하고, 그 외 호스트는 `APP_ENV`를 직접 설정한다(`lib/app-env.ts`).
+- 의존성 정책: caret range, `pnpm-lock.yaml` 커밋, CI `--frozen-lockfile`. `.npmrc`의 `minimum-release-age=14d`로 갓 나온 npm 패키지는 cooldown 후에만 설치한다. 의존성 변경은 lockfile과 같은 커밋에 포함한다.
+
+## 폴더 구조 (FSD-light)
+
+```
+app/                       # Next.js 라우트만 (page·layout·route handler)
+  ├── sketch/<feature>/    # /sketch 임시 시안 — 채택안만 남기고 정리
+  ├── api/cron/<job>/      # cron route handler
+  └── <route>/_components/ # 라우트 전용 UI (underscore = private)
+features/<feature>/        # 도메인 모듈 (자기완결)
+  ├── components/          # 이 기능 전용 UI
+  ├── repository.ts        # 이 기능의 모든 Supabase 호출 소유 (데이터 접근 seam)
+  ├── actions.ts           # server actions — repository.ts에만 의존
+  ├── queries.ts           # 데이터 쿼리 — repository.ts에만 의존
+  ├── schema.ts            # zod (form·경계 검증) — DB schema와 정합 유지
+  └── index.ts             # public API — 외부 import는 여기만
+supabase/migrations/       # DB schema SSOT (.sql + RLS)
+components/ui/             # shadcn primitives (글로벌 재사용)
+lib/                       # cross-cutting 인프라
+  ├── supabase/{server,client,admin}.ts
+  ├── supabase/types.ts    # DB→TS 자동 생성 (gen types, read-only)
+  ├── env.ts               # 클라이언트·일반 코드용 (NEXT_PUBLIC_ 만)
+  ├── env.server.ts        # server-only (SUPABASE_SECRET_KEY 등)
+  ├── app-env.ts           # 벤더 중립 배포 환경(APP_ENV) 해석 (순수 함수)
+  ├── logger.ts utils.ts
+sentry.{server,edge}.config.ts  # server/edge SDK init (instrumentation.ts가 register)
+instrumentation.ts         # server/edge Sentry register + onRequestError
+instrumentation-client.ts  # browser SDK init (Next가 자동 인식)
+tests/<feature>/           # Vitest 회귀 (feature 미러)
+docs/{ENVIRONMENTS,LIMITS}.md   # 레퍼런스
+```
+
+## 폴더 규칙
+
+- `app/`은 얇다: 비즈니스 로직을 두지 않고 `features/`를 조합만 한다.
+- 의존은 단방향이다: `app → features → lib`. feature끼리는 다른 feature의 `index.ts`(public API)만 import한다(내부 직접 import 금지 = 캡슐화). `lib`은 `features`를 import하지 않는다(ESLint로 강제).
+- 두 feature가 서로를 import하게 되면, 공통 책임을 상위 feature로 추출한다(예: cart + payment → `features/checkout/`).
+- 여러 페이지가 공유하는 복합 UI(Header, Shell)는 `features/layout/components/`에 둔다.
+- 여러 feature가 공유하는 schema(Money, Address)는 우선 `lib/schemas/`에 둔다. 반복 패턴이 분명해지면 `entities/<entity>/`를 정식 도입한다.
+- 큰 복합 UI가 쌓이면 `widgets/<widget>/`를 정식 도입한다.
+- schema 3층: DB(`supabase/migrations/*.sql`, SSOT) → TS 타입(`lib/supabase/types.ts`, 자동 생성) → zod(`features/<feature>/schema.ts`, form·경계 검증). DB가 SSOT이고, 변경 시 나머지 두 층을 동기화한다.
+
+## 환경 분리
+
+dev/prod를 서로 다른 Supabase 프로젝트로 격리한다. 매트릭스는 [`docs/ENVIRONMENTS.md`](docs/ENVIRONMENTS.md), 무료 티어 한도는 [`docs/LIMITS.md`](docs/LIMITS.md).
+
+- dev: `<repo>-dev` Supabase + Sentry `env=development`(송출 off) + Vercel preview·localhost
+- prod: `<repo>-prod` Supabase + Sentry `env=production` + Vercel production
+
+코드 분기는 서버에서 `env.APP_ENV`(`@/lib/env.server`)로 한다. 빌드 시점 파일(`sentry.{server,edge}.config.ts`·`instrumentation*.ts`·`next.config.ts`)은 env 모듈보다 먼저 실행되므로 `process.env`를 직접 읽고 `lib/app-env.ts`로 APP_ENV를 해석한다.

package/templates/workspace/web/CLAUDE.md

@@ -0,0 +1,2 @@
+<!-- AGENTS.md를 그대로 불러옵니다. 이 repo의 에이전트 규칙은 AGENTS.md에서 단일 관리합니다. -->
+@AGENTS.md

package/templates/workspace/web/DESIGN.md

@@ -0,0 +1,18 @@
+# DESIGN
+
+프로젝트의 디자인 언어(컬러·타이포그래피·간격·컴포넌트 규칙)를 여기 적는다. `/sketch`가 이 파일을 디자인 컨벤션으로 읽는다. 비어 있어도 동작하며, 채울수록 시안이 프로젝트 톤에 맞는다.
+
+## Colors
+<!-- 예: --primary, --bg, --text -->
+
+## Typography
+<!-- 폰트, 크기 스케일, 굵기 -->
+
+## Spacing & Layout
+<!-- 간격 단위, 그리드, 브레이크포인트 -->
+
+## Components
+<!-- 버튼, 카드, 입력창 규칙 -->
+
+## 참고
+- 마크다운으로 디자인 언어를 적는 포맷 예시: [getdesign.md](https://getdesign.md/), [awesome-design-md](https://github.com/VoltAgent/awesome-design-md)

package/templates/workspace/web/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 시스템설계자
+
+This template is distributed to students of the author's course
+(brand: 시스템설계자).
+
+You may use it as the starting point for any of your own projects —
+personal or commercial. You may modify it freely, ship products built
+with it, and you keep all rights to the work you create on top.
+
+You may not redistribute the template itself, repackage it as a course
+or book, or include it in any dataset used to train machine learning
+models. Access is part of the course.
+
+THE TEMPLATE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED. THE AUTHOR SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM OR IN CONNECTION WITH THE TEMPLATE OR ITS
+USE.

package/templates/workspace/web/README.md

@@ -0,0 +1,48 @@
+# my-space
+
+무료 티어로 실제 운영되는 웹 SaaS를 만드는 스타터 템플릿입니다. Owner는 결정하고, AI가 CLI·코드 작업을 합니다.
+
+## 스택
+
+Next.js (App Router) · TypeScript · Tailwind v4 · shadcn/ui · Supabase · Vercel · Sentry · Vitest. 모두 무료 티어 안에서 동작합니다.
+
+## 빠른 시작
+
+이 폴더는 워크스페이스의 `web/` 서브프로젝트입니다. 명령(스킬)은 워크스페이스 루트의 `.claude/`에 있으므로, AI 에이전트는 루트에서 엽니다. `web/`에는 도구가 없습니다(순수 코드). 아래 표는 그 흐름의 참고용입니다.
+
+| 단계 | 명령 | AI가 하는 일 | Owner가 하는 일 |
+| --- | --- | --- | --- |
+| 1. 환경 점검 | `/warmup` | 외부 CLI·로그인 검증, 의존성 install·audit | 부족한 로그인 안내 따르기 |
+| 2. 첫 배포 | `/go-live` | GitHub·Vercel·Supabase dev/prod·Sentry 프로비저닝, env 동기화, 첫 배포, 보안 진단 | 비가역 작업 confirm |
+| 3. 기획 | `/probe <아이디어>` | 인터뷰로 요구사항 도출 | 질문에 답변 |
+| 4. 디자인 | `/sketch` | shadcn과 프로젝트 디자인 컨벤션 기반 UI | 원하면 DESIGN.md 채우기 |
+| 5. 개발 | "X 기능 만들어줘" | TDD로 개발, Vitest 통과까지 반복 | 요구사항 명시·검토 |
+| 6. 푸시 | `git push` | CI 통과 시 Vercel 자동 배포 | URL 확인 |
+
+코드 규칙·폴더 구조·환경 분기 규약은 [`AGENTS.md`](AGENTS.md)에 있습니다.
+
+## 사전 준비물
+
+`/warmup`이 안내하지만, 미리 가입·설치하면 빠릅니다.
+
+- [Node.js](https://nodejs.org/) 현재 LTS
+- [pnpm](https://pnpm.io/) 최신
+- [GitHub](https://github.com) 계정 + `gh auth login`
+- [Vercel](https://vercel.com) 계정 + `vercel login` (GitHub OAuth 권장)
+- [Supabase](https://supabase.com) 계정 + `pnpm exec supabase login`(이 폴더에서) + [Personal Access Token](https://supabase.com/dashboard/account/tokens)
+- [Sentry](https://sentry.io) 계정 + `sentry-cli login`
+
+## 의존성 정책
+
+- 버전: caret range(`^x.y.z`). 보안 패치는 자동으로, major는 고정.
+- 결정성: `pnpm-lock.yaml` 커밋 + CI `--frozen-lockfile`.
+- 공급망: `.npmrc`의 `minimum-release-age=14d`로 갓 나온 패키지는 cooldown 후 설치.
+- CVE: CI에서 `pnpm audit --prod --audit-level=high`.
+
+## 환경 분리
+
+dev/prod를 서로 다른 Supabase 프로젝트로 격리합니다(무료 슬롯 2개 사용). 로컬 `pnpm dev`와 Vercel preview는 dev DB에, Vercel production(`main`)은 prod DB에 붙습니다. 매트릭스는 [`docs/ENVIRONMENTS.md`](docs/ENVIRONMENTS.md), 한도는 [`docs/LIMITS.md`](docs/LIMITS.md).
+
+## 라이선스
+
+강의 수강생용 템플릿입니다. [LICENSE](LICENSE).

package/templates/workspace/web/app/error.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import * as Sentry from "@sentry/nextjs";
+import { useEffect } from "react";
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    Sentry.captureException(error);
+  }, [error]);
+
+  return (
+    <main className="mx-auto flex max-w-2xl flex-1 flex-col items-start justify-center gap-4 px-6">
+      <h2 className="text-xl font-semibold">문제가 발생했어요</h2>
+      <button
+        onClick={reset}
+        className="rounded bg-primary px-3 py-1.5 text-sm text-primary-foreground"
+      >
+        다시 시도
+      </button>
+    </main>
+  );
+}

package/templates/workspace/web/app/global-error.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import * as Sentry from "@sentry/nextjs";
+import NextError from "next/error";
+import { useEffect } from "react";
+
+export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
+  useEffect(() => {
+    Sentry.captureException(error);
+  }, [error]);
+
+  return (
+    <html lang="ko">
+      <body>
+        <NextError statusCode={0} />
+      </body>
+    </html>
+  );
+}

package/templates/workspace/web/app/globals.css

@@ -0,0 +1,130 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-geist-mono);
+  --font-heading: var(--font-sans);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.87 0 0);
+  --chart-2: oklch(0.556 0 0);
+  --chart-3: oklch(0.439 0 0);
+  --chart-4: oklch(0.371 0 0);
+  --chart-5: oklch(0.269 0 0);
+  --radius: 0.625rem;
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.87 0 0);
+  --chart-2: oklch(0.556 0 0);
+  --chart-3: oklch(0.439 0 0);
+  --chart-4: oklch(0.371 0 0);
+  --chart-5: oklch(0.269 0 0);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+  html {
+    @apply font-sans;
+  }
+}

package/templates/workspace/web/app/layout.tsx

@@ -0,0 +1,33 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "my-space",
+  description: "무료티어 기반 웹 SaaS 스타터",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html
+      lang="ko"
+      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
+    >
+      <body className="min-h-full flex flex-col">{children}</body>
+    </html>
+  );
+}

package/templates/workspace/web/app/not-found.tsx

@@ -0,0 +1,12 @@
+import Link from "next/link";
+
+export default function NotFound() {
+  return (
+    <main className="mx-auto flex max-w-2xl flex-1 flex-col items-start justify-center gap-4 px-6">
+      <h2 className="text-xl font-semibold">페이지를 찾을 수 없어요</h2>
+      <Link href="/" className="text-sm text-muted-foreground underline-offset-4 hover:underline">
+        홈으로
+      </Link>
+    </main>
+  );
+}

package/templates/workspace/web/app/page.tsx

@@ -0,0 +1,11 @@
+export default function Home() {
+  return (
+    <main className="mx-auto flex max-w-2xl flex-1 flex-col items-start justify-center gap-4 px-6">
+      <h1 className="text-3xl font-semibold tracking-tight">my-space</h1>
+      <p className="text-muted-foreground">
+        템플릿 부트스트랩 완료. <code className="rounded bg-muted px-1.5 py-0.5 text-sm">/probe</code>로
+        아이디어를 요구사항으로 정제한 뒤 개발을 시작하세요.
+      </p>
+    </main>
+  );
+}

package/templates/workspace/web/components/ui/button.tsx

@@ -0,0 +1,58 @@
+import { Button as ButtonPrimitive } from "@base-ui/react/button"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+  "group/button inline-flex shrink-0 items-center justify-center rounded-lg border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground [a]:hover:bg-primary/80",
+        outline:
+          "border-border bg-background hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
+        ghost:
+          "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
+        destructive:
+          "bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default:
+          "h-8 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+        sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+        lg: "h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        icon: "size-8",
+        "icon-xs":
+          "size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+        "icon-sm":
+          "size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
+        "icon-lg": "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function Button({
+  className,
+  variant = "default",
+  size = "default",
+  ...props
+}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) {
+  return (
+    <ButtonPrimitive
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Button, buttonVariants }

package/templates/workspace/web/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-nova",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

package/templates/workspace/web/docs/ENVIRONMENTS.md

@@ -0,0 +1,102 @@
+# 환경 분리 매트릭스 (dev / prod)
+
+dev와 prod를 서로 다른 Supabase 프로젝트로 완전히 격리한다. Owner의 로컬 작업이 실 서비스에 닿지 않게 하기 위해서다.
+
+## 매트릭스
+
+| 자원 | dev | prod | 분리 방식 |
+|---|---|---|---|
+| Next.js 실행 | `pnpm dev`(localhost:3000) + Vercel preview(feature 브랜치) | Vercel production(main 푸시) | 같은 코드, 런타임에 `APP_ENV`로 분기 |
+| Supabase DB | `<repo>-dev` 프로젝트 | `<repo>-prod` 프로젝트 | 별개의 URL·key |
+| Supabase Auth | dev project, redirect URL `localhost:3000`·`*.vercel.app` | prod project, prod 도메인 redirect | 사용자 계정도 별개 |
+| Sentry | 1 프로젝트, `environment=development` 태그 | 같은 프로젝트, `environment=production` 태그 | env 태그 + 송출 가드 |
+| Sentry 송출 | off (`APP_ENV !== "production"`) | on | 5k/월 한도 보호. preview에서도 송출하지 않음 |
+| Vercel Cron | preview·dev에서 실행 안 함(`APP_ENV === "production"` 가드) | 정상 실행 | 코드 분기 |
+| env vars 소스 | `vercel env pull --environment=development` → `.env.local` | Vercel "Production" 슬롯(자동 주입) | gitignored |
+| GitHub Actions CI | PR·main 모두 같은 GH Secrets로 컴파일·테스트(앱 런타임 실행은 없음) | 동일 | CI는 dev/prod를 구분하지 않는다. 런타임 분기는 Vercel이 담당 |
+| Supabase 마이그레이션 | AI 자동: `--project-ref <dev>` | AI가 Owner confirm 후: `--project-ref <prod>` | Owner 결정점 |
+| 배포 환경 신호 | `APP_ENV=development`(로컬)·`preview`(Vercel preview) | `APP_ENV=production` | Vercel은 `VERCEL_ENV`를 `APP_ENV`로 매핑 |
+
+## 분기 값: APP_ENV
+
+코드 분기의 기준 값은 `APP_ENV`다(`production` | `preview` | `development`). Vercel은 빌드 시 `VERCEL_ENV`를 주입하고, `lib/app-env.ts`가 이를 `APP_ENV`로 해석한다. 그 외 호스트는 `APP_ENV`를 직접 설정한다. 서버 코드는 언제나 `APP_ENV`를 보고, `VERCEL_ENV`를 직접 보지 않는다.
+
+## 일상 흐름
+
+```
+[로컬 dev]
+$ pnpm dev → localhost:3000
+  .env.local(dev 슬롯 값) 사용
+  → Supabase DEV
+  → Sentry 송출 off
+
+[feature 브랜치]
+$ git push origin feature-x
+  → GHA CI (typecheck·lint·test·build)
+  → 통과 시 Vercel preview URL 생성
+  → Supabase DEV
+  → Sentry env=development
+
+[production]
+$ git push origin main
+  → GHA CI
+  → Vercel Deployment Checks 통과
+  → Vercel production 자동 promote
+  → Supabase PROD (실 사용자)
+  → Sentry env=production (이벤트 송출)
+```
+
+## 코드에서 환경 분기
+
+```ts
+// 런타임 서버 코드 — env.server (server-only 가드)
+import { env } from "@/lib/env.server";
+
+if (env.APP_ENV === "production") {
+  // 결제 처리, 외부 알림 등
+}
+
+// Vercel Cron route handler 가드
+export async function GET(req: Request) {
+  if (env.APP_ENV !== "production") {
+    return Response.json({ skipped: "non-prod" });
+  }
+  // 실제 cron 로직
+}
+
+// 클라이언트 코드 — NEXT_PUBLIC_ 만
+import { env } from "@/lib/env";
+const url = env.NEXT_PUBLIC_SUPABASE_URL;
+```
+
+```ts
+// 예외: 빌드 시점 설정 파일(sentry.{server,edge}.config.ts·instrumentation*.ts·next.config.ts)은
+// env 모듈보다 먼저 실행되므로 process.env를 직접 읽는다.
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  enabled: process.env.VERCEL_ENV === "production",
+  environment: process.env.VERCEL_ENV ?? "development",
+  tracesSampleRate: 0,
+});
+```
+
+## 마이그레이션 워크플로 (AI 주도)
+
+1. `npx supabase migration new <name>`로 파일 생성
+2. SQL 작성 (RLS 정책 동봉 필수)
+3. `npx supabase db push --project-ref $SUPABASE_DEV_REF`로 dev 적용 (자동)
+4. dev에서 검증한 뒤 Owner에게 보고: "dev 적용·검증 완료. 변경 요약: ___. prod에도 적용할까요?"
+5. Owner confirm
+6. `npx supabase db push --project-ref $SUPABASE_PROD_REF`로 prod 적용
+
+`$SUPABASE_DEV_REF`·`$SUPABASE_PROD_REF`는 `/go-live`가 `.env.local`과 Vercel env에 저장한다.
+
+## 비용·한도
+
+무료 티어 숫자는 [`LIMITS.md`](LIMITS.md)가 SSOT다. 핵심만: dev/prod 분리에 Supabase 무료 슬롯 2개를 모두 쓰고, Sentry는 prod만 송출해 한도를 보호한다. Vercel 로그 보존은 1시간이라, 그 너머는 Sentry와 Supabase `logs` 테이블에서 조회한다.
+
+## 다루지 않는 것
+
+- stage 환경: dev/prod 2환경으로 충분하다. 더 필요하면 Vercel preview를 stage로 쓴다.
+- Supabase 로컬 Docker: 입문자 진입장벽을 피한다.
+- CD 자동 prod 마이그레이션: prod 변경은 항상 Owner confirm을 거치고, CI에서 자동 실행하지 않는다.