Initial Setting

Supabase DB Setting

Supabase 프로젝트에서 DB 스키마 기반 개발환경을 한 번에 세팅한다. 에이전트가 4000줄+ 타입 파일을 직접 읽지 않고도 스키마를 효과적으로 파악할 수 있게 하는 것이 핵심 목적이다.

세팅 항목 요약

Step 0: 프로젝트 분석

세팅 전 아래를 파악한다:

분석 대상:
├─ package.json — 패키지 매니저 판별
├─ @supabase/ssr 또는 @supabase/supabase-js 설치 여부
├─ tsconfig.json — path alias (@/ 등)
├─ database.types.ts 기존 위치
├─ supabase client/server 파일 위치
├─ CLAUDE.md 존재 여부 및 기존 DB 섹션
└─ supabase 프로젝트 연결 여부

패키지 매니저 판별:

• pnpm-lock.yaml → pnpm / yarn.lock → yarn / bun.lockb → bun / 기본 → npm

Step 1: DB 스키마 CLI 스크립트 설치

이 스킬의 scripts/db-schema.sh를 {project-root}/scripts/db-schema.sh에 복사한다.

순수 bash 스크립트로 tsx/node 설치 없이 바로 실행 가능하다. DB_TYPES_PATH 환경변수로 타입 파일 위치를 오버라이드할 수 있고, 기본적으로 src/types/, types/, lib/types/ 등을 자동 탐색한다.

복사 후 chmod +x scripts/db-schema.sh 실행 권한을 부여한다. 이미 scripts/db-schema.ts (TypeScript 버전)가 있으면 bash 버전으로 교체를 제안한다.

CLI 지원 명령어

Step 2: package.json 스크립트 추가

{
  "scripts": {
    "db:schema": "bash scripts/db-schema.sh",
    "update-type": "supabase gen types typescript --linked --debug > {TYPES_PATH}"
  }
}

• {TYPES_PATH}: Step 0에서 파악한 database.types.ts 경로
• 기존에 동일 스크립트가 있으면 덮어쓰지 않고 확인

Step 3: Supabase client/server 타입 바인딩

기존 Supabase client와 server 파일을 찾아 Database 제네릭 타입을 바인딩한다. 이미 <Database> 제네릭을 사용하고 있으면 스킵한다.

필요한 import 추가:

import type { Database } from '{TYPES_IMPORT_PATH}';

제네릭 적용:

• createBrowserClient<Database>(...) — client.ts
• createServerClient<Database>(...) — server.ts

파일이 없으면 이 스킬의 scripts/client.ts.template, scripts/server.ts.template을 참고하여 생성한다 (위치는 유저에게 확인).

@supabase/ssr 대신 @supabase/supabase-js만 사용하는 프로젝트는 import를 맞춰 조정한다. middleware.ts에도 Supabase client가 있으면 동일하게 타입 바인딩한다.

Step 4: CLAUDE.md에 DB 섹션 추가

CLAUDE.md에 아래 섹션을 추가한다. 이미 DB 관련 섹션이 있으면 병합한다.

이 섹션은 세 가지 역할을 한다:

1. 에이전트에게 마이그레이션 규칙을 알려줌 (MCP로 DDL 실행 방지)
2. 테이블/뷰/함수 목록을 핵심 메모리로 제공 (매번 CLI 안 돌려도 됨)
3. 스키마 CLI 사용법 안내 (상세 스키마가 필요할 때)

추가할 내용 템플릿

## Database Schema Tools

### 마이그레이션 규칙 (CRITICAL)

- **마이그레이션은 반드시 Supabase CLI로만 생성/적용한다.** MCP `apply_migration`은 절대 사용하지 않는다.
- MCP Supabase 도구는 **데이터 조회/삽입/삭제에만** 사용하며, 유저가 명시적으로 요청한 경우에만 사용한다.
- 스키마 변경(DDL) 워크플로우:

\```bash
npx supabase migration new <name>         # 1. 마이그레이션 파일 생성
# 생성된 .sql 파일에 DDL 작성
npx supabase db push --linked             # 2. 원격 DB에 적용
{PKG_RUN} update-type                     # 3. TypeScript 타입 재생성
\```

### Type 동기화

DB 스키마 변경(마이그레이션 적용) 후 반드시 타입을 재생성해야 한다:

\```bash
{PKG_RUN} update-type    # Supabase → {TYPES_PATH} 재생성
\```

### 테이블 목록 ({N}개)

| 테이블 | 목적 |
|--------|------|
| `{table_name}` | {한 줄 설명} |
| ... | ... |

### 뷰 목록

| 뷰 | 목적 |
|----|------|
| `{view_name}` | {한 줄 설명} |

### RPC 함수

| 함수 | Args | Returns | 목적 |
|------|------|---------|------|
| `{function_name}` | `{args}` | `{returns}` | {한 줄 설명} |

### Schema CLI (CRITICAL)

**`{TYPES_PATH}`를 직접 읽지 말 것.** 대신 CLI로 필요한 부분만 조회:

\```bash
{PKG_RUN} db:schema tables                 # 전체 테이블 목록
{PKG_RUN} db:schema table {example_table}  # 특정 테이블 스키마 (Row/Insert/Update)
{PKG_RUN} db:schema views                  # 전체 뷰 목록
{PKG_RUN} db:schema view {example_view}    # 특정 뷰 스키마
{PKG_RUN} db:schema functions              # 전체 RPC 함수 목록 (시그니처 포함)
{PKG_RUN} db:schema function {example_fn}  # 특정 함수 상세 (Args/Returns)
{PKG_RUN} db:schema enums                  # 전체 enum 목록
{PKG_RUN} db:schema enum {example_enum}    # 특정 enum 값
{PKG_RUN} db:schema search {keyword}       # 테이블/뷰/함수/enum 통합 검색
\```

테이블/뷰/함수 목록 작성 방법

CLI를 실행하여 목록을 수집한 뒤, 유저에게 각 항목의 목적을 확인하거나 테이블 컬럼명/컨텍스트로 추론한다. 이 목록은 에이전트의 핵심 메모리 역할을 하므로 간결하되 정확해야 한다.

동적 값:

• {PKG_RUN}: npm run / pnpm run / yarn / bun run
• {TYPES_PATH}: 실제 database.types.ts 경로
• {N}: 테이블 개수
• 테이블/뷰/함수 예시는 실제 프로젝트 것으로 교체

Step 5: 타입 생성 안내

Supabase 타입 생성은 supabase login이 필요하므로 직접 실행하지 않는다. 세팅 완료 후 아래를 출력한다:

✅ Supabase DB 세팅 완료!

다음 단계를 진행해 주세요:

1. Supabase CLI 로그인 (아직 안 했다면):
   npx supabase login

2. 프로젝트 연결 (아직 안 했다면):
   npx supabase link --project-ref <your-project-ref>

3. 타입 생성:
   {PKG_RUN} update-type

4. 스키마 CLI 테스트:
   {PKG_RUN} db:schema tables

세팅된 항목:
  ✓ scripts/db-schema.sh — DB 스키마 CLI (bash, tables/views/functions/enums)
  ✓ package.json — db:schema, update-type 스크립트
  ✓ CLAUDE.md — 마이그레이션 규칙 + 테이블/뷰/함수 목록 + CLI 가이드
  ✓ {client_path} — Database 제네릭 타입
  ✓ {server_path} — Database 제네릭 타입

Edge Cases

• database.types.ts가 이미 존재: 덮어쓰지 않음. update-type 스크립트만 추가
• client.ts/server.ts가 없는 프로젝트: 유저에게 생성 위치 확인 후 템플릿에서 생성
• @supabase/supabase-js만 사용: createClient import를 맞춰 조정
• middleware.ts에도 Supabase client 존재: 동일하게 타입 바인딩
• 모노레포: 앱 디렉토리 기준으로 경로 설정
• Views/Functions 없는 프로젝트: CLAUDE.md에서 해당 섹션 생략