바이브코딩 완벽 매뉴얼

Claude 4종 완벽 가이드, Supabase, Vercel, GitHub, VS Code 사용법을 한곳에서 확인하세요.

🤖

Claude

모바일-앱, 웹, 데스크톱-앱, Code 4종 완벽 가이드. 설치부터 활용까지.
🐱

GitHub

Git 명령어, 저장소 관리, GitHub Flow, 마크다운, Actions까지.
⚡

Supabase

PostgreSQL 기반 BaaS. DB, Auth, Storage, 벡터 DB & AI까지.
▲

Vercel

AI Cloud 배포 플랫폼. 프레임워크, Functions, AI SDK까지.
📝

VS Code

코드 편집기. 확장 프로그램과 단축키로 생산성 극대화.

설치 순서 로드맵

1

VS Code 설치

코드 편집기가 모든 개발의 시작점입니다. 터미널, Git, 확장 프로그램을 한 곳에서 사용합니다.

winget install Microsoft.VisualStudioCode
자세히 보기 →
2

Node.js 설치

JavaScript 런타임. npm(패키지 매니저)이 함께 설치되어 Claude Code, Vercel CLI 등을 설치할 수 있습니다.

winget install OpenJS.NodeJS.LTS
설치 확인: node -v && npm -v
3

Git 설치

버전 관리 시스템. GitHub 연동과 코드 이력 관리에 필수입니다.

winget install Git.Git
설치 확인: git --version
자세히 보기 →
4

GitHub 계정 생성 & 설정

코드 호스팅 플랫폼. 계정 생성 후 Git 사용자 정보와 SSH 키를 설정합니다.

git config --global user.name "이름"
git config --global user.email "이메일"
자세히 보기 →
5

Claude Code 설치

AI 코딩 어시스턴트. Node.js가 설치된 상태에서 npm으로 설치합니다.

npm install -g @anthropic-ai/claude-code
실행: claude
자세히 보기 →
6

Supabase 프로젝트 생성

백엔드 서비스. 웹에서 회원가입 후 프로젝트를 생성하고, 클라이언트 라이브러리를 설치합니다.

npm install @supabase/supabase-js
자세히 보기 →
7

Vercel 연결 & 배포

배포 플랫폼. GitHub 저장소를 연결하면 push마다 자동 배포됩니다.

npm install -g vercel
로그인: vercel login → 배포: vercel --prod
자세히 보기 →
8

개발 시작!

모든 도구가 준비되었습니다. VS Code에서 터미널을 열고 claude를 실행하면 AI와 함께 개발을 시작할 수 있습니다.

code . && claude
Claude

Claude 4종 소개

Claude는 모바일-앱, 웹, 데스크톱-앱, Claude Code 4가지 접근방식을 제공합니다.

왜 Claude인가?

Claude는 Anthropic이 만든 AI 어시스턴트로, 헌법적 AI(Constitutional AI) 철학에 기반한 안전하고 유용한 도구입니다. 모바일-앱이 가위라면 Claude Code는 다기능 공구입니다. 4가지 접근방식을 모두 활용하면 강력한 통합 AI 작업환경을 구축할 수 있습니다.

4종 비교

기능 모바일-앱 웹 데스크톱-앱 Claude Code
기본 AI 대화OOOO
대화 기록 동기화OOOX
음성 입력OXXX
카메라 연동OXXX
Artifacts 표시OOOX
파일 생성/다운로드XOOO
로컬 파일 접근XXO (MCP)O
시스템 명령 실행XXXO
프로그램 자동 설치XXXO
Git 명령 실행XX일부O

각 접근방식 특징

통합 작업환경 구성

모든 도구를 유기적으로 연결하면 강력한 AI 워크스테이션이 됩니다:

3가지 모델 체계

Claude

설치 가이드 (7단계)

Claude 4종과 VS Code를 단계별로 설치합니다. 약 3시간이면 모두 완료됩니다.

1단계: 모바일-앱 설치

  1. App Store(iOS) 또는 Google Play(Android)에서 "Claude" 검색
  2. "Claude by Anthropic" 앱 설치
  3. 이메일 주소 입력 → 인증 코드 6자리 입력 → 로그인 완료

2단계: 웹 설치

  1. https://claude.ai 접속
  2. PWA 설치: Chrome 주소창 우측 "앱에서 열기" 아이콘 클릭 → 작업 표시줄에 고정
  3. 동일 계정으로 로그인하면 모바일-앱과 대화 기록 자동 동기화

3단계: 데스크톱-앱 설치

  1. https://claude.ai/download 접속
  2. 운영체제에 맞는 설치 파일 다운로드 (Windows / Windows arm64)
  3. 설치 파일 더블클릭 → 자동 설치 → 바탕화면 바로가기 생성
  4. 빠른 호출: Ctrl+Alt+Space로 어디서든 Claude 창 호출

4단계: 공통 프로그램 설치

Node.js 설치 (Claude Code와 MCP 서버 실행에 필수)

# https://nodejs.org 에서 LTS 버전 다운로드 후 설치
node --version
npm --version

Git 설치 (버전 관리, npm 패키지 의존성)

# https://git-scm.com/downloads/win 에서 다운로드 후 설치
git --version

5단계: Claude Code 설치

# Claude Code 설치
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

# 실행
claude

최초 실행 시 로그인 방식을 선택합니다:

웹 브라우저에서 인증 승인 후 로그인이 완료됩니다.

6단계: 데스크톱-앱에 MCP 연결

MCP(Model Context Protocol)는 데스크톱-앱이 로컬 파일과 프로그램에 접근할 수 있게 해주는 연결 도구입니다.

설치할 MCP 서버 3종:

가장 쉬운 방법: Claude Code에게 요청

"내부 MCP 서버 3종을 설치하고 설정해줘"

수동 설치:

# Filesystem & Memory 서버 설치
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-memory

설정 파일 위치: C:\Users\[사용자]\AppData\Roaming\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "node.exe",
      "args": ["...server-filesystem/dist/index.js", "G:\\내 드라이브\\MyTask"]
    },
    "memory": {
      "command": "node.exe",
      "args": ["...server-memory/dist/index.js"]
    },
    "anthropic": {
      "command": "node.exe",
      "args": ["C:\\AnthropicMCP\\dist\\index.js"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-api03-..." }
    }
  }
}

설정 후 데스크톱-앱을 재시작하면 MCP 연결이 활성화됩니다.

7단계: VS Code 설치

  1. https://code.visualstudio.com에서 다운로드
  2. 설치 시 모든 옵션 체크 (PATH 추가, 우클릭 메뉴 등)
  3. 한국어 설정: 확장 프로그램에서 Korean Language Pack 설치
  4. Claude Code 연동: Ctrl + `로 터미널 열고 claude 실행
Claude Code

기본 사용법

일상적으로 사용하는 핵심 기능들입니다.

주요 슬래시 명령어

주요 CLI 플래그

파일 작업 요청

# 파일 수정 요청
"login 함수에 에러 핸들링 추가해줘"

# 새 파일 생성
"사용자 인증 미들웨어 만들어줘"

# 버그 수정
"이 에러 원인 찾아서 고쳐줘"

권한 모드

주요 에러 메시지 및 해결법

Claude Code 사용 중 자주 만나는 에러 메시지와 해결 방법입니다.

Claude Code

고급 기능

생산성을 높이는 고급 활용법입니다.

비대화형 모드

# 한 번에 명령 실행
claude -p "이 프로젝트의 구조 설명해줘"

# 파이프 입력
cat error.log | claude -p "이 에러 분석해줘"

CLAUDE.md 설정

프로젝트 루트에 CLAUDE.md 파일을 만들어 프로젝트 컨텍스트를 제공합니다:

# CLAUDE.md
이 프로젝트는 Next.js 14 + Supabase 기반입니다.
- 컴포넌트는 src/components에 위치
- API 라우트는 src/app/api에 위치
- Supabase 클라이언트는 src/lib/supabase.ts

MCP 서버 연동

MCP(Model Context Protocol)는 "AI를 위한 USB-C"로, 외부 시스템과 AI를 표준화된 방식으로 연결합니다.

# .claude/settings.json
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"]
    }
  }
}

연결 가능한 외부 MCP 서버: GitHub, Google Drive, Slack, PostgreSQL, Docker, Puppeteer, Notion, Jira 등

서브 에이전트 시스템

복잡한 작업을 전문 영역별로 분해하여 독립된 컨텍스트에서 병렬 처리합니다.

작업 모드 3가지

주요 도구 목록

/tools 명령어로 확인 가능:

Claude

VS Code 연동

VS Code와 Claude Code를 결합하면 AI 지원 통합 개발 환경이 완성됩니다.

VS Code에서 Claude Code 사용하기

# 1. VS Code 내장 터미널 열기: Ctrl + ` (백틱)
# 2. Claude Code 실행
claude

# 3. 원하는 폴더에서 VS Code 열기
code .

필수 확장 프로그램

한국어 지원

AI 어시스턴트

공통 도구

개발 전용

권장 설정

Claude

사용료 체계

6가지 요금제와 5시간 리셋 시스템을 이해합니다.

요금제 비교

플랜 가격 5시간당 메시지 모델 Claude Code
Free무료10~15개자동 선택X
Pro$20/월45개Haiku/Sonnet/OpusO
Max 5x$100/월225개전체O
Max 20x$200/월900개전체O
Team$30/월/인~225개전체Premium Seat
Enterprise맞춤 견적맞춤전체 + 커스텀Premium Seat

5시간 리셋 시스템

Claude는 첫 메시지 시점부터 5시간 단위로 사용량이 리셋됩니다.

토큰이란?

AI가 텍스트를 처리하는 기본 단위입니다. 1토큰 ≈ 영어 3~5글자 ≈ 한글 2~3글자

출력 토큰은 입력 토큰보다 5배 비쌉니다. AI가 텍스트를 생성하는 것이 이해하는 것보다 계산적으로 더 복잡하기 때문입니다.

모델별 토큰 요금 (백만 토큰당)

모델 입력 출력 특징
Haiku$0.80$4.00가장 저렴, 빠름
Sonnet$3.00$15.00균형형 (기본 추천)
Opus$15.00$75.00최고 성능 (Haiku 대비 19배)

플랜 추천

Claude

토큰 절감 방안 9가지

토큰 사용량을 줄여 비용을 절약하는 실전 방법입니다.

1. 대화 및 컨텍스트 관리

매번 질문할 때마다 이전 대화 전체가 토큰으로 계산됩니다. 10~15개 메시지마다 새 대화를 시작하고, 20개 메시지 후 핵심을 5줄로 요약하여 새 대화에 복사하세요.

효과: 토큰 사용량 80% 감소

2. 파일 업로드 최소화

100페이지 PDF 통째 업로드 대신, 필요한 페이지/섹션만 텍스트로 복사-붙여넣기 하세요.

효과: 토큰 사용량 95% 감소

3. 모델 선택 전략

효과: 단순 작업에 Haiku 사용 시 Opus 대비 19배 절감

4. 템플릿 활용

반복 작업(코드 리뷰, 일일 보고서 등)을 템플릿으로 저장하고 변경 부분만 수정하세요.

효과: 월 135,000 토큰 절감

5. 이미지 사용 최소화

이미지 1장 = 텍스트 5페이지 토큰. 핵심 부분만 캡처한 1~2장 + 텍스트 설명으로 대체하세요.

효과: 토큰 사용량 76% 감소

6. 프롬프트 간소화

인사말 없이 핵심만 간결하게. 구조화된 형식(작업/언어/목적/코드)으로 작성하세요.

효과: 토큰 사용량 25% 감소

7. 병렬 처리 활용

한 대화에서 여러 프로젝트 혼재 대신, 프로젝트별 독립 세션으로 분리하세요.

효과: 토큰 사용량 30% 감소

8. 배치 처리 (API 전용)

대량 작업(1,000개 리뷰 분석 등)을 배치로 일괄 처리하면 50% 할인됩니다. 최대 10,000개/배치.

효과: 토큰 사용량 50% 감소

9. 프롬프트 캐싱 (API 전용)

자주 사용하는 시스템 프롬프트를 캐시하면 5분간 재사용 가능. 캐시 읽기는 기본 가격의 10%만 소요.

효과: 토큰 사용량 최대 90% 감소

Claude

Anthropic 이야기

기업가치 254조원, 창업 4년 3개월 만에 비상장기업 세계 4위에 오른 회사의 이야기.

창업 스토리 (2021년 6월)

OpenAI 핵심 연구진 7명이 AI 안전성에 대한 철학 차이로 독립하여 설립. Dario Amodei(연구 담당 부사장)와 Daniela Amodei(안전/정책 부사장) 남매가 이끌었습니다.

회사 명칭 'Anthropic'은 그리스어 'anthropos(인간)'에서 유래하여 "인간 중심적 AI"라는 철학을 담고 있습니다. 공익법인(PBC) 형태로 설립되었습니다.

헌법적 AI (Constitutional AI)

2022년 12월 발표한 혁신적 기술. AI가 명확한 원칙('헌법')에 따라 스스로를 평가하고 개선합니다.

Claude의 진화

투자 유치와 성장

시기 라운드 금액 주요 투자자
2021.9Series A$1.24억Lightspeed, General Catalyst
2022.4Series B$5.8억FTX (이후 파산)
2023.5Series C$4.5억Google, Salesforce, SK텔레콤
2023.9Series D$40억Amazon (총 $80억, 최대 단일 투자자)
2025.3Series E$35억Lightspeed, Fidelity (기업가치 $615억)
2025.9Series F$130억ICONIQ, BlackRock, GIC (기업가치 $1,830억 = 254조원)

총 투자 유치: 256억 달러 | 비상장기업 가치 세계 4위 (SpaceX, OpenAI, TikTok 다음)

수익 성장

기업 AI 시장 점유율 32% (OpenAI 25%), 코딩 분야 42% (OpenAI 21%)

한국 시장

한국의 AUI(1인당 Claude 사용 지수)는 3.73으로 세계 5위, 미국(3.62)보다 높습니다.

핵심 기술 11가지

Tier 1 - 차별화 핵심: 헌법적 AI, 대규모 컨텍스트 처리 (200K~1M 토큰), Computer Use

Tier 2 - 핵심 기능: Tool Use/Function Calling, Artifacts, Vision, 서브 에이전트

Tier 3 - 효율성: Prompt Caching (비용 90% 절감), Projects, Message Batches API

Tier 4 - 생태계: MCP (AI를 위한 USB-C, 200+ 커뮤니티 서버)

저자 소개

이 가이드북은 현직 공인회계사이자 스타트업 엑셀러레이터인 써니(선웅규)님이 5개월간의 실사용 경험을 바탕으로 제작했습니다. Claude를 프롬프터로, Claude가 집필자로 참여한 협업 결과물입니다.

문의: wksun999@hanmail.net | 카카오톡 채널: @Claude

GitHub

소개 및 설정

GitHub는 Git 기반의 코드 호스팅 및 협업 플랫폼입니다. 전 세계 1억 명 이상의 개발자가 사용합니다.

GitHub란?

계정 유형

플랜 가격 저장소 주요 기능
Free무료무제한(공개/비공개)Actions 2,000분/월
Pro$4/월무제한고급 인사이트, 위키
Team$4/인/월무제한팀 관리, Actions 3,000분
Enterprise$21/인/월무제한SAML SSO, Advanced Security

Git 설치

# 설치 확인
git --version

# Windows
winget install Git.Git

# macOS
brew install git

# Linux (Ubuntu/Debian)
sudo apt install git

초기 설정 (필수)

# 사용자 정보 설정 (커밋에 기록됨)
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

# 기본 브랜치명 설정
git config --global init.defaultBranch main

# 기본 편집기 설정
git config --global core.editor "code --wait"

# 줄 끝 처리 (Windows)
git config --global core.autocrlf true

# 줄 끝 처리 (macOS/Linux)
git config --global core.autocrlf input

# 설정 확인
git config --list

인증 설정

# SSH 키 생성 (권장)
ssh-keygen -t ed25519 -C "your@email.com"

# 공개키 복사 → GitHub > Settings > SSH Keys에 등록
cat ~/.ssh/id_ed25519.pub

# SSH 연결 테스트
ssh -T git@github.com

GitHub CLI (gh)

# 설치
brew install gh          # macOS
winget install GitHub.cli  # Windows

# 로그인
gh auth login

# 상태 확인
gh auth status

# 자동완성 설정 (bash)
eval "$(gh completion -s bash)"
GitHub

Git 핵심 명령어

Git의 핵심 명령어를 익혀 버전 관리의 기본을 다집니다.

기본 워크플로우

# 1. 작업 디렉토리 초기화
git init

# 2. 파일 상태 확인
git status

# 3. 변경사항 스테이징 (추적 시작)
git add index.html          # 특정 파일
git add .                   # 모든 변경사항
git add -p                  # 변경사항 일부만 선택

# 4. 커밋 (스냅샷 저장)
git commit -m "feat: 로그인 기능 추가"

# 5. 원격 저장소에 푸시
git push origin main

커밋 메시지 규칙 (Conventional Commits)

이력 조회

# 커밋 로그 보기
git log

# 한 줄로 보기
git log --oneline

# 그래프로 보기
git log --oneline --graph --all

# 특정 파일 이력
git log -- index.html

# 변경 내용 비교
git diff                    # 스테이징 전 변경사항
git diff --staged           # 스테이징된 변경사항
git diff main..feature      # 브랜치 간 비교

되돌리기

# 스테이징 취소 (파일 유지)
git restore --staged index.html

# 작업 디렉토리 변경 취소
git restore index.html

# 마지막 커밋 메시지 수정
git commit --amend -m "수정된 메시지"

# 특정 커밋으로 되돌리기 (새 커밋 생성)
git revert abc1234

# 커밋 이력 초기화 (주의: 되돌릴 수 없음)
git reset --hard abc1234

Stash (임시 저장)

# 현재 변경사항 임시 저장
git stash

# 메시지와 함께 저장
git stash save "로그인 작업 중"

# 저장 목록 보기
git stash list

# 가장 최근 stash 복원
git stash pop

# 특정 stash 복원
git stash apply stash@{1}

# stash 삭제
git stash drop stash@{0}

.gitignore (파일 무시)

# .gitignore 파일 예시
node_modules/
.env
.env.local
*.log
dist/
.DS_Store
*.pyc
__pycache__/
.vscode/settings.json

태그

# 태그 생성
git tag v1.0.0

# 주석 태그 생성
git tag -a v1.0.0 -m "첫 번째 릴리스"

# 태그 목록
git tag -l

# 태그 푸시
git push origin v1.0.0
git push origin --tags       # 모든 태그
GitHub

저장소 관리

저장소 생성부터 브랜치, Pull Request까지 협업의 핵심을 다룹니다.

저장소 생성

# GitHub CLI로 생성 (권장)
gh repo create my-project --public --clone
gh repo create my-project --private --clone

# 웹에서 생성 후 클론
git clone git@github.com:username/repo.git

# 기존 프로젝트를 GitHub에 연결
git init
git add .
git commit -m "Initial commit"
git remote add origin git@github.com:username/repo.git
git push -u origin main

원격 저장소 관리

# 원격 저장소 확인
git remote -v

# 원격 저장소 추가
git remote add origin git@github.com:user/repo.git

# 원격 저장소 URL 변경
git remote set-url origin git@github.com:user/new-repo.git

# 원격 저장소 삭제
git remote remove origin

# 원격 변경사항 가져오기 (병합 안 함)
git fetch origin

# 원격 변경사항 가져와서 병합
git pull origin main

브랜치 관리

# 브랜치 생성
git branch feature/login

# 브랜치 생성 + 이동
git checkout -b feature/login
git switch -c feature/login       # 최신 방식

# 브랜치 이동
git checkout main
git switch main                   # 최신 방식

# 브랜치 목록
git branch            # 로컬
git branch -r         # 원격
git branch -a         # 전체

# 브랜치 삭제
git branch -d feature/login       # 병합된 브랜치
git branch -D feature/login       # 강제 삭제

# 원격 브랜치 삭제
git push origin --delete feature/login

병합 (Merge)

# feature 브랜치를 main에 병합
git checkout main
git merge feature/login

# 충돌 발생 시
# 1. 충돌 파일 수동 편집
# 2. 충돌 해결 후
git add .
git commit -m "fix: 병합 충돌 해결"

# 병합 취소
git merge --abort

Pull Request (PR)

# PR 생성
gh pr create --title "feat: 로그인 기능" --body "설명"

# PR 생성 (대화형)
gh pr create

# PR 목록
gh pr list

# PR 상세 보기
gh pr view 123

# PR 체크아웃 (로컬에서 테스트)
gh pr checkout 123

# PR 머지
gh pr merge 123
gh pr merge 123 --squash    # 스쿼시 머지
gh pr merge 123 --rebase    # 리베이스 머지

# PR 닫기
gh pr close 123

이슈 관리

# 이슈 생성
gh issue create --title "버그: 로그인 오류" --body "설명"

# 이슈 목록
gh issue list

# 이슈 상세 보기
gh issue view 45

# 이슈 닫기
gh issue close 45

# 이슈를 PR에 연결 (커밋 메시지에)
git commit -m "fix: 로그인 오류 수정 (closes #45)"

Fork & 오픈소스 기여

# 저장소 Fork
gh repo fork owner/repo --clone

# upstream 원본 저장소 추가
git remote add upstream git@github.com:owner/repo.git

# 원본 최신 코드 동기화
git fetch upstream
git merge upstream/main

# 기여 워크플로우
# 1. Fork → 2. Clone → 3. Branch 생성
# 4. 수정 → 5. Push → 6. PR 생성
GitHub

GitHub Flow

GitHub Flow는 간단하고 효과적인 분기 기반 협업 워크플로우입니다.

6단계 워크플로우

단계 작업 설명
1브랜치 생성main에서 설명적인 이름의 브랜치 생성 (예: add-login-page)
2변경 작업코드 수정 후 설명적인 커밋 메시지로 커밋·푸시
3PR 생성Pull Request를 만들어 변경사항 요약 및 관련 이슈 연결
4코드 리뷰팀원이 코드를 검토하고 피드백, 필요시 추가 커밋
5병합승인 후 PR을 main 브랜치에 병합
6브랜치 삭제병합 완료 후 작업 브랜치 삭제 (필요시 복원 가능)

실전 예시

# 1. 브랜치 생성
git switch -c feature/add-login-page

# 2. 코드 수정 및 커밋
git add .
git commit -m "feat: 로그인 페이지 UI 구현"
git push -u origin feature/add-login-page

# 3. PR 생성
gh pr create --title "feat: 로그인 페이지 추가" \
  --body "## 변경사항
- 로그인 폼 UI 구현
- 이메일/비밀번호 유효성 검사

Closes #12"

# 4. 리뷰 반영 후 추가 커밋
git add .
git commit -m "fix: 리뷰 피드백 반영"
git push

# 5. PR 병합
gh pr merge --squash

# 6. 로컬 브랜치 정리
git switch main
git pull
git branch -d feature/add-login-page

브랜치 이름 규칙

코드 리뷰 체크리스트

GitHub

마크다운 문법

GitHub에서 이슈, PR, README 등을 작성할 때 사용하는 마크다운 문법입니다.

텍스트 서식

# 제목 (h1 ~ h6)
# 제목 1
## 제목 2
### 제목 3

# 텍스트 스타일
**굵게**
*기울임*
~~취소선~~
**_굵은 기울임_**
<sub>아래첨자</sub>
<sup>위첨자</sup>

링크 & 이미지

# 링크
[표시 텍스트](https://example.com)

# 이미지
![대체 텍스트](image-url.png)

# 상대 경로 링크
[문서 보기](./docs/guide.md)

리스트

# 순서 없는 리스트
- 항목 1
- 항목 2
  - 하위 항목

# 순서 있는 리스트
1. 첫 번째
2. 두 번째
3. 세 번째

# 체크리스트 (이슈/PR에서 활용)
- [x] 완료된 작업
- [ ] 미완료 작업

코드

# 인라인 코드
`변수명` 또는 `함수()`

# 코드 블록 (언어 지정)
```javascript
function hello() {
  console.log("Hello!");
}
```

# diff 표시
```diff
- 삭제된 줄
+ 추가된 줄
```

테이블

| 기능 | 설명 | 상태 |
|------|------|------|
| 로그인 | 이메일 인증 | 완료 |
| 회원가입 | 소셜 로그인 | 진행중 |

# 정렬
| 왼쪽 | 가운데 | 오른쪽 |
|:-----|:------:|------:|
| L    | C      | R     |

인용 & 알림

# 인용
> 인용 텍스트입니다.

# 알림 (GitHub 전용)
> [!NOTE]
> 참고할 내용

> [!TIP]
> 유용한 팁

> [!WARNING]
> 경고 메시지

> [!CAUTION]
> 주의 사항

README.md 템플릿

# 프로젝트 이름

프로젝트에 대한 간단한 설명

## 기능
- 주요 기능 1
- 주요 기능 2

## 설치
```bash
npm install
npm run dev
```

## 사용법
사용 방법 설명

## 기여
기여 방법 안내

## 라이선스
MIT License
GitHub

GitHub Actions

CI/CD 자동화 워크플로우를 설정하여 빌드, 테스트, 배포를 자동화합니다.

핵심 개념

기본 구조

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 코드 체크아웃
        uses: actions/checkout@v4

      - name: Node.js 설정
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: 의존성 설치
        run: npm ci

      - name: 빌드
        run: npm run build

      - name: 테스트
        run: npm test

배포 워크플로우

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build

      - name: Vercel 배포
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.ORG_ID }}
          vercel-project-id: ${{ secrets.PROJECT_ID }}
          vercel-args: '--prod'

주요 트리거

# 다양한 이벤트 트리거
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 9 * * 1'        # 매주 월요일 9시
  workflow_dispatch:             # 수동 실행 버튼
  release:
    types: [published]

Secrets & 환경변수

Settings > Secrets and variables > Actions에서 관리합니다.

# 워크플로우에서 Secrets 사용
env:
  SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
  SUPABASE_KEY: ${{ secrets.SUPABASE_KEY }}

# 환경변수 직접 설정
env:
  NODE_ENV: production
  CI: true

유용한 Actions

GitHub CLI로 Actions 관리

# 워크플로우 목록
gh workflow list

# 워크플로우 실행
gh workflow run ci.yml

# 실행 상태 확인
gh run list

# 실행 로그 보기
gh run view 12345 --log
Supabase

소개 및 설정

Supabase는 PostgreSQL 기반의 오픈소스 BaaS(Backend as a Service) 플랫폼으로, Firebase의 오픈소스 대안입니다.

Supabase란?

Supabase vs Firebase

항목 Supabase Firebase
데이터베이스PostgreSQL (관계형)Firestore (NoSQL)
쿼리SQL, JOIN 지원제한적 쿼리
오픈소스O (자체 호스팅 가능)X (Google 종속)
벡터 DBpgvector 내장별도 서비스 필요
서버리스 함수Edge Functions (Deno)Cloud Functions (Node)

요금제

항목 Free Pro ($25/월) Team ($599/월)
DB 크기500MB8GB무제한
스토리지1GB100GB무제한
프로젝트2개무제한무제한
백업없음매일PITR
비활성 일시정지1주일 후 정지없음없음

회원가입 & 프로젝트 생성

  1. supabase.com 접속 → Start your project 클릭
  2. GitHub 또는 이메일로 회원가입 (이메일 인증 10분 내 완료)
  3. New Project 클릭
  4. 프로젝트명 입력
  5. DB 비밀번호 설정 (12자 이상, 대소문자+숫자+특수문자)
  6. Region: Northeast Asia (Seoul) 선택
  7. Create new project 클릭
Supabase 대시보드

API 키 확인

Project Settings → API에서 확인합니다:

Supabase API 키

환경변수 설정

# .env.local
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIs...  # 서버 전용!

클라이언트 설치 & 초기화

# 설치
npm install @supabase/supabase-js

# 초기화 (lib/supabase.js)
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL
const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY

export const supabase = createClient(supabaseUrl, supabaseKey)

대시보드 주요 메뉴

Supabase

데이터베이스

PostgreSQL 기반 테이블 생성, CRUD, 필터링, 실시간 구독을 다룹니다.

테이블 생성 (SQL Editor)

-- todos 테이블 생성
CREATE TABLE public.todos (
  id uuid DEFAULT gen_random_uuid() NOT NULL,
  created_at timestamp with time zone DEFAULT now() NOT NULL,
  task text NOT NULL,
  is_complete boolean DEFAULT false NOT NULL,
  user_id uuid REFERENCES auth.users(id),
  CONSTRAINT todos_pkey PRIMARY KEY (id)
);

-- RLS 활성화
ALTER TABLE public.todos ENABLE ROW LEVEL SECURITY;

또는 Table Editor에서 GUI로 생성할 수 있습니다:

Table Editor

데이터 조회 (SELECT)

// 전체 조회
const { data, error } = await supabase
  .from('todos')
  .select('*')

// 정렬 + 페이징
const { data } = await supabase
  .from('todos')
  .select('*')
  .order('created_at', { ascending: false })
  .range(0, 9)   // 0~9번째 (10개)

// 특정 컬럼만
const { data } = await supabase
  .from('todos')
  .select('id, task, is_complete')

// 관계 테이블 JOIN
const { data } = await supabase
  .from('todos')
  .select('*, profiles(username, avatar_url)')

필터링

// 같음
.eq('is_complete', true)

// 같지 않음
.neq('status', 'deleted')

// 비교
.gt('score', 80)       // >
.gte('score', 80)      // >=
.lt('score', 50)       // <
.lte('score', 50)      // <=

// 포함
.in('status', ['active', 'pending'])

// 텍스트 검색
.like('task', '%공부%')
.ilike('task', '%supabase%')    // 대소문자 무시

// NULL 체크
.is('deleted_at', null)

// 복합 조건
.or('is_complete.eq.true, task.ilike.%긴급%')

데이터 삽입 (INSERT)

// 단일 삽입
const { data, error } = await supabase
  .from('todos')
  .insert({ task: 'Supabase 공부하기', user_id: userId })
  .select()    // 삽입된 데이터 반환

// 다중 삽입
const { data, error } = await supabase
  .from('todos')
  .insert([
    { task: '할 일 1' },
    { task: '할 일 2' },
    { task: '할 일 3' }
  ])
  .select()

데이터 수정 (UPDATE)

const { data, error } = await supabase
  .from('todos')
  .update({ is_complete: true })
  .eq('id', '특정-uuid')
  .select()

데이터 삭제 (DELETE)

const { error } = await supabase
  .from('todos')
  .delete()
  .eq('id', '삭제할-uuid')

실시간 구독

// 테이블 변경 실시간 감지
const channel = supabase
  .channel('todos-changes')
  .on('postgres_changes',
    { event: '*', schema: 'public', table: 'todos' },
    (payload) => {
      console.log('변경 유형:', payload.eventType)
      console.log('새 데이터:', payload.new)
      console.log('이전 데이터:', payload.old)
    }
  )
  .subscribe()

// 특정 이벤트만 감지
.on('postgres_changes',
  { event: 'INSERT', schema: 'public', table: 'todos' },
  (payload) => console.log('새 할 일:', payload.new)
)

// 구독 해제
supabase.removeChannel(channel)

SQL Editor에서 직접 실행

-- 기본 CRUD
INSERT INTO todos (task, user_id) VALUES ('할 일', '...');
SELECT * FROM todos WHERE is_complete = false;
UPDATE todos SET is_complete = true WHERE id = '...';
DELETE FROM todos WHERE id = '...';
Supabase

인증 (Auth)

이메일, OAuth, 매직링크 등 다양한 인증 방법을 지원합니다.

지원 인증 방식

이메일 회원가입

const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'securePassword123!',
  options: {
    data: {
      username: '홍길동',    // 추가 메타데이터
      avatar_url: 'https://...'
    }
  }
})

// data.user - 생성된 사용자 정보
// data.session - 세션 정보 (이메일 확인 전에는 null)

로그인

// 이메일/비밀번호 로그인
const { data, error } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'securePassword123!'
})

// 매직링크 로그인 (이메일 링크)
const { error } = await supabase.auth.signInWithOtp({
  email: 'user@example.com'
})

OAuth (소셜 로그인)

대시보드 > Authentication > Providers에서 원하는 프로바이더를 활성화합니다.

// Google 로그인
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: 'https://your-site.com/callback'
  }
})

// GitHub 로그인
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'github'
})

// Kakao 로그인
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'kakao'
})

세션 관리

// 현재 사용자 확인
const { data: { user } } = await supabase.auth.getUser()

// 현재 세션 확인
const { data: { session } } = await supabase.auth.getSession()

// 로그아웃
await supabase.auth.signOut()

// 인증 상태 변화 감지
supabase.auth.onAuthStateChange((event, session) => {
  console.log(event)   // SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED 등
  console.log(session)
})

비밀번호 재설정

// 재설정 이메일 발송
const { error } = await supabase.auth.resetPasswordForEmail(
  'user@example.com',
  { redirectTo: 'https://your-site.com/reset-password' }
)

// 새 비밀번호 설정 (리다이렉트 후)
const { error } = await supabase.auth.updateUser({
  password: 'newSecurePassword!'
})
Supabase

스토리지

파일 업로드, 다운로드, 이미지 변환 등 스토리지 기능을 다룹니다.

버킷 생성

대시보드 > Storage에서 New bucket을 클릭하거나 코드로 생성합니다:

// 공개 버킷 생성
const { data, error } = await supabase.storage.createBucket('avatars', {
  public: true,
  fileSizeLimit: 1024 * 1024 * 2  // 2MB 제한
})

// 비공개 버킷 생성
const { data, error } = await supabase.storage.createBucket('documents', {
  public: false
})

파일 업로드

// 파일 업로드
const { data, error } = await supabase.storage
  .from('avatars')
  .upload('public/avatar.png', file, {
    cacheControl: '3600',
    upsert: true    // 같은 이름이면 덮어쓰기
  })

// 업로드 + 고유 파일명
const fileName = `${Date.now()}-${file.name}`
const { data, error } = await supabase.storage
  .from('avatars')
  .upload(fileName, file)

파일 URL 가져오기

// 공개 URL (공개 버킷)
const { data } = supabase.storage
  .from('avatars')
  .getPublicUrl('public/avatar.png')
// data.publicUrl → "https://xxx.supabase.co/storage/v1/object/public/..."

// 임시 URL (비공개 버킷, 60초 유효)
const { data, error } = await supabase.storage
  .from('documents')
  .createSignedUrl('secret.pdf', 60)

파일 다운로드 & 삭제

// 다운로드
const { data, error } = await supabase.storage
  .from('avatars')
  .download('public/avatar.png')

// 파일 삭제
const { error } = await supabase.storage
  .from('avatars')
  .remove(['public/avatar.png'])

// 여러 파일 삭제
const { error } = await supabase.storage
  .from('avatars')
  .remove(['file1.png', 'file2.png'])

파일 목록 조회

const { data, error } = await supabase.storage
  .from('avatars')
  .list('public', {
    limit: 100,
    offset: 0,
    sortBy: { column: 'created_at', order: 'desc' }
  })

이미지 변환 (Pro 플랜)

// 리사이즈된 이미지 URL
const { data } = supabase.storage
  .from('avatars')
  .getPublicUrl('avatar.png', {
    transform: {
      width: 200,
      height: 200,
      resize: 'cover'
    }
  })
Supabase

RLS & 보안

Row Level Security(RLS)로 데이터베이스 보안을 설정합니다. Supabase 보안의 핵심입니다.

RLS란?

PostgreSQL의 행 수준 보안 기능으로, 테이블의 각 행에 대해 누가 읽기/쓰기할 수 있는지 정책(Policy)으로 제어합니다. Supabase에서 테이블을 생성하면 기본적으로 RLS가 활성화되어 정책이 없으면 아무도 접근할 수 없습니다.

RLS 설정

RLS 활성화/비활성화

-- RLS 활성화
ALTER TABLE public.todos ENABLE ROW LEVEL SECURITY;

-- RLS 비활성화 (개발 중에만! 프로덕션에서는 절대 비활성화 금지)
ALTER TABLE public.todos DISABLE ROW LEVEL SECURITY;

읽기 정책 (SELECT)

-- 누구나 읽기 허용 (공개 데이터)
CREATE POLICY "공개 읽기" ON public.todos
  FOR SELECT USING (true);

-- 본인 데이터만 읽기
CREATE POLICY "본인 데이터 읽기" ON public.todos
  FOR SELECT USING (auth.uid() = user_id);

-- 로그인한 사용자만 읽기
CREATE POLICY "인증된 사용자 읽기" ON public.todos
  FOR SELECT TO authenticated USING (true);

쓰기 정책 (INSERT / UPDATE / DELETE)

-- 로그인한 사용자만 생성 (본인 user_id로만)
CREATE POLICY "본인 데이터 생성" ON public.todos
  FOR INSERT TO authenticated
  WITH CHECK (auth.uid() = user_id);

-- 본인 데이터만 수정
CREATE POLICY "본인 데이터 수정" ON public.todos
  FOR UPDATE TO authenticated
  USING (auth.uid() = user_id)
  WITH CHECK (auth.uid() = user_id);

-- 본인 데이터만 삭제
CREATE POLICY "본인 데이터 삭제" ON public.todos
  FOR DELETE TO authenticated
  USING (auth.uid() = user_id);

자주 쓰는 RLS 패턴

-- 전체 CRUD (본인 데이터만)
CREATE POLICY "본인 전체 권한" ON public.todos
  FOR ALL TO authenticated
  USING (auth.uid() = user_id)
  WITH CHECK (auth.uid() = user_id);

-- 관리자 전체 접근
CREATE POLICY "관리자 전체 권한" ON public.todos
  FOR ALL USING (
    EXISTS (
      SELECT 1 FROM profiles
      WHERE profiles.id = auth.uid()
      AND profiles.role = 'admin'
    )
  );

정책 관리

-- 정책 삭제
DROP POLICY "정책 이름" ON public.todos;

-- 정책 목록 확인
SELECT * FROM pg_policies WHERE tablename = 'todos';

보안 체크리스트

Supabase

벡터 DB & AI

pgvector 확장으로 벡터 데이터베이스를 구축하고, RAG(검색 증강 생성) 시스템을 만듭니다.

pgvector란?

PostgreSQL에서 벡터(임베딩) 데이터를 저장하고 유사도 검색을 수행하는 확장입니다. 별도의 벡터 DB 서비스(Pinecone 등) 없이 Supabase 하나로 관계형 데이터와 AI 기능을 동시에 처리할 수 있습니다.

pgvector 활성화

대시보드 > Database > Extensions에서 "vector" 검색 후 Enable:

-- 또는 SQL로 활성화
CREATE EXTENSION IF NOT EXISTS vector;
pgvector 활성화

문서 테이블 생성

CREATE TABLE documents (
  id serial PRIMARY KEY,
  title text NOT NULL,
  content text NOT NULL,
  embedding vector(1536),    -- OpenAI text-embedding-3-small 차원
  metadata jsonb,
  created_at timestamptz DEFAULT now()
);

-- 검색 성능을 위한 인덱스
CREATE INDEX ON documents
  USING ivfflat (embedding vector_cosine_ops)
  WITH (lists = 100);

유사도 검색 함수

CREATE OR REPLACE FUNCTION match_documents (
  query_embedding vector(1536),
  match_threshold float,
  match_count int
)
RETURNS TABLE (
  id bigint,
  title text,
  content text,
  similarity float
)
LANGUAGE sql STABLE
AS $$
  SELECT
    documents.id,
    documents.title,
    documents.content,
    1 - (documents.embedding <=> query_embedding) as similarity
  FROM documents
  WHERE 1 - (documents.embedding <=> query_embedding) > match_threshold
  ORDER BY documents.embedding <=> query_embedding
  LIMIT match_count;
$$;

Node.js RAG 구현

import OpenAI from 'openai'
import { supabase } from './lib/supabase'

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

// 1. 문서 임베딩 → 저장
async function embedAndStore(title, content) {
  const response = await openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: content
  })
  const embedding = response.data[0].embedding

  const { data, error } = await supabase
    .from('documents')
    .insert({ title, content, embedding })
  return data
}

// 2. 유사 문서 검색
async function searchDocs(query) {
  const response = await openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: query
  })
  const { data } = await supabase.rpc('match_documents', {
    query_embedding: response.data[0].embedding,
    match_threshold: 0.7,
    match_count: 5
  })
  return data
}

// 3. RAG 기반 답변 생성
async function generateAnswer(question) {
  const docs = await searchDocs(question)
  const context = docs.map(d => d.content).join('\n\n')

  const completion = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [
      { role: 'system', content: '제공된 문서를 기반으로 정확하게 답변하세요.' },
      { role: 'user', content: `문서:\n${context}\n\n질문: ${question}` }
    ]
  })
  return completion.choices[0].message.content
}

활용 사례

Vercel

소개 및 배포

Vercel은 프론트엔드 및 풀스택 애플리케이션을 위한 클라우드 배포 플랫폼입니다. Git push만으로 자동 배포됩니다.

Vercel이란?

요금제

항목 Hobby (무료) Pro ($20/인/월) Enterprise
대상개인 프로젝트팀·비즈니스대규모 조직
대역폭100GB/월1TB/월커스텀
빌드 시간6,000분/월24,000분/월커스텀
서버리스 실행100GB-시간1,000GB-시간커스텀
팀 기능X역할·권한 관리SSO, SAML
지원커뮤니티이메일전담 매니저, SLA

계정 생성 & 프로젝트 연결

  1. vercel.com/signup에서 회원가입 (GitHub/GitLab/이메일)
  2. Add New Project → GitHub 저장소 선택
  3. 프레임워크 자동 감지 → Deploy 클릭
  4. 배포 완료! 이후 git push마다 자동 배포

Vercel CLI 설치

# 설치
npm install -g vercel

# 로그인
vercel login

# 현재 폴더 배포 (프리뷰)
vercel

# 프로덕션 배포
vercel --prod

# 로컬 개발 서버 (환경변수 포함)
vercel dev

# 프로젝트 정보 확인
vercel inspect

# 배포 목록
vercel ls

배포 환경

즉시 롤백

# 이전 배포로 즉시 롤백
vercel rollback

# 특정 배포로 롤백
vercel rollback [deployment-url]
Vercel

프레임워크

Vercel은 다양한 프레임워크를 자동 인식하고 최적화합니다. 별도 설정 없이 배포할 수 있습니다.

지원 프레임워크 & 기능

프레임워크 SSR ISR Middleware 이미지 최적화 스트리밍
Next.js✓✓✓✓✓
SvelteKit✓✓✓✓✓
Nuxt✓✓✓✓✗
Astro✓✓✓✓✓
Remix✓✗✓✗✓
Vite / ReactN/AN/A✓N/AN/A
TanStack✓✗✓N/A✓

주요 프레임워크 특징

Next.js 프로젝트 생성 & 배포

# Next.js 프로젝트 생성
npx create-next-app@latest my-app
cd my-app

# 로컬 개발
npm run dev

# GitHub에 푸시
git init && git add . && git commit -m "Initial commit"
gh repo create my-app --public --push --source=.

# Vercel에서 자동 배포 (GitHub 연동 후)
# 또는 CLI로 배포
vercel --prod

정적 사이트 배포 (Vite)

# Vite + React 프로젝트
npm create vite@latest my-site -- --template react
cd my-site && npm install

# vercel.json (선택)
{
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

# 배포
vercel --prod
Vercel

Functions & API

Vercel Functions로 서버 없이 API 라우트와 서버사이드 로직을 실행합니다.

Vercel Functions란?

API 라우트 생성 (Next.js App Router)

// app/api/hello/route.ts
export function GET(request: Request) {
  return Response.json({ message: 'Hello from Vercel!' })
}

export async function POST(request: Request) {
  const body = await request.json()
  return Response.json({ received: body })
}

API 라우트 (api/ 디렉토리 - 범용)

// api/hello.ts (프레임워크 무관)
export default {
  fetch(request: Request) {
    return new Response('Hello from Vercel!')
  }
}

// api/users.ts - HTTP 메서드별
export function GET(request: Request) {
  return Response.json([{ id: 1, name: '홍길동' }])
}

export async function POST(request: Request) {
  const { name } = await request.json()
  return Response.json({ id: 2, name }, { status: 201 })
}

Middleware

요청이 처리되기 전에 실행되는 코드로, 인증 체크·리다이렉트·헤더 수정 등에 사용합니다.

// middleware.ts (프로젝트 루트)
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  // 인증 체크
  const token = request.cookies.get('auth-token')
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }

  // 응답 헤더 추가
  const response = NextResponse.next()
  response.headers.set('X-Custom-Header', 'hello')
  return response
}

export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*']
}

ISR (Incremental Static Regeneration)

// app/blog/[slug]/page.tsx
export const revalidate = 60  // 60초마다 재생성

export default async function BlogPost({ params }) {
  const post = await fetch(`https://api.example.com/posts/${params.slug}`)
    .then(r => r.json())

  return <article>{post.title}</article>
}

// 또는 온디맨드 재검증
// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache'

export function POST(request: Request) {
  revalidatePath('/blog')
  return Response.json({ revalidated: true })
}

Functions 설정

// vercel.json
{
  "functions": {
    "api/**/*.ts": {
      "memory": 1024,         // MB (128~3008)
      "maxDuration": 60       // 초 (Hobby: 10, Pro: 300)
    }
  },
  "regions": ["icn1"]         // 서울 리전
}
Vercel

설정 및 도메인

프로젝트 설정, 커스텀 도메인, 리다이렉트 등을 관리합니다.

vercel.json 주요 설정

{
  "buildCommand": "npm run build",
  "outputDirectory": ".next",
  "framework": "nextjs",
  "regions": ["icn1"],

  "rewrites": [
    { "source": "/api/:path*", "destination": "/api/:path*" }
  ],

  "redirects": [
    { "source": "/old-page", "destination": "/new-page", "permanent": true }
  ],

  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" },
        { "key": "Cache-Control", "value": "s-maxage=86400" }
      ]
    }
  ]
}

커스텀 도메인 연결

  1. Vercel 대시보드 > Settings > Domains
  2. 도메인 입력 후 Add
  3. DNS 레코드 설정:
    • CNAME: cname.vercel-dns.com (서브도메인용)
    • A 레코드: 76.76.21.21 (루트 도메인용)
  4. SSL 인증서 자동 발급 (Let's Encrypt)

도메인 CLI 관리

# 도메인 추가
vercel domains add example.com

# 도메인 목록
vercel domains ls

# 도메인 삭제
vercel domains rm example.com

# DNS 레코드 확인
vercel dns ls example.com

리전 목록 (자주 사용)

보안 기능

Vercel

환경변수 관리

환경별 변수 설정으로 API 키와 설정값을 안전하게 관리합니다.

대시보드에서 설정

Settings > Environment Variables에서 추가합니다. 환경별로 다른 값을 설정할 수 있습니다:

변수명 용도 환경
NEXT_PUBLIC_SUPABASE_URLSupabase 프로젝트 URL전체
NEXT_PUBLIC_SUPABASE_ANON_KEYSupabase 공개 키전체
SUPABASE_SERVICE_ROLE_KEYSupabase 서버 키 (비공개)Production
OPENAI_API_KEYOpenAI API 키Production

CLI로 관리

# 환경변수 추가 (대화형)
vercel env add SUPABASE_SERVICE_ROLE_KEY

# 환경 지정 추가
vercel env add API_KEY production

# 환경변수 목록
vercel env ls

# 로컬로 가져오기 (.env.local 생성)
vercel env pull

# 환경변수 삭제
vercel env rm API_KEY production

환경별 구분

주의사항

Vercel

AI 인프라

Vercel의 AI SDK, AI Gateway, v0 등을 활용해 AI 애플리케이션을 구축합니다.

Vercel AI 도구 모음

AI SDK 설치 & 사용

# 설치
npm install ai @ai-sdk/openai

# app/api/chat/route.ts
import { openai } from '@ai-sdk/openai'
import { streamText } from 'ai'

export async function POST(req: Request) {
  const { messages } = await req.json()

  const result = streamText({
    model: openai('gpt-4o'),
    messages,
  })

  return result.toDataStreamResponse()
}

클라이언트에서 사용

// app/page.tsx
'use client'
import { useChat } from 'ai/react'

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat()

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          <b>{m.role}:</b> {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
        <button type="submit">전송</button>
      </form>
    </div>
  )
}

AI SDK 지원 프로바이더

도구 호출 (Tool Use)

import { openai } from '@ai-sdk/openai'
import { generateText, tool } from 'ai'
import { z } from 'zod'

const result = await generateText({
  model: openai('gpt-4o'),
  tools: {
    weather: tool({
      description: '특정 도시의 날씨를 가져옵니다',
      parameters: z.object({
        city: z.string().describe('도시 이름')
      }),
      execute: async ({ city }) => {
        // 실제 API 호출
        return { city, temp: 22, condition: '맑음' }
      }
    })
  },
  prompt: '서울 날씨 알려줘'
})

AI Gateway 설정

// vercel.json
{
  "ai": {
    "providers": [
      {
        "id": "openai",
        "type": "openai",
        "apiKey": "@openai-api-key"
      },
      {
        "id": "anthropic",
        "type": "anthropic",
        "apiKey": "@anthropic-api-key"
      }
    ]
  }
}
VS Code

소개 및 설치

Visual Studio Code는 Microsoft가 만든 무료 코드 편집기로, 전 세계 개발자들이 가장 많이 사용하는 IDE입니다.

VS Code란?

설치 방법

# 공식 사이트: https://code.visualstudio.com

# Windows (winget)
winget install Microsoft.VisualStudioCode

# macOS (Homebrew)
brew install --cask visual-studio-code

# Linux (Ubuntu/Debian)
sudo apt install code
# 또는 snap
sudo snap install code --classic

CLI 명령어

# 현재 폴더를 VS Code로 열기
code .

# 특정 파일 열기
code index.html

# 특정 파일의 특정 줄로 열기
code -g index.html:42

# 새 창으로 열기
code -n .

# 파일 차이점 비교
code --diff file1.js file2.js

# 확장 프로그램 설치
code --install-extension ms-python.python

# 설치된 확장 목록
code --list-extensions

# 설정 초기화
code --user-data-dir /tmp/vscode-test

웹 버전

VS Code

UI 구조 & 편집

VS Code의 인터페이스 구조를 이해하고, 편집 기능을 마스터합니다.

UI 구성 요소

영역 위치 역할
Activity Bar왼쪽 끝탐색기, 검색, Git, 디버그, 확장 등 뷰 전환
Side Bar왼쪽선택한 뷰의 상세 정보 (파일 트리, 검색 결과 등)
Editor중앙코드 편집 영역. 탭으로 여러 파일, 분할 가능
Panel하단터미널, 출력, 문제, 디버그 콘솔
Status Bar맨 아래언어, 인코딩, 줄/열, Git 브랜치, 에러 수

편집기 분할

# 에디터 분할 단축키
Ctrl+\         → 세로 분할 (macOS: Cmd+\)
Ctrl+K Ctrl+\  → 가로 분할

# 분할 에디터 간 이동
Ctrl+1, Ctrl+2, Ctrl+3  → 1번, 2번, 3번 그룹

# 탭을 다른 그룹으로 이동
Ctrl+Alt+→     → 오른쪽 그룹으로 이동

IntelliSense (자동완성)

코드 탐색

# 정의로 이동
F12            또는 Ctrl+Click

# 미리보기 (팝업)
Alt+F12        → Peek Definition

# 모든 참조 찾기
Shift+F12

# 심볼로 이동 (현재 파일)
Ctrl+Shift+O

# 심볼로 이동 (워크스페이스)
Ctrl+T

# 특정 줄로 이동
Ctrl+G

리팩토링

멀티 커서 & 선택

# 멀티 커서
Alt+Click              → 클릭 위치에 커서 추가
Ctrl+Alt+↑/↓           → 위/아래에 커서 추가
Ctrl+D                 → 같은 단어 선택 (반복 가능)
Ctrl+Shift+L           → 같은 단어 모두 선택

# 선택 확장/축소
Shift+Alt+→            → 선택 확장
Shift+Alt+←            → 선택 축소

# 열 선택 (박스 선택)
Shift+Alt+드래그        → 직사각형 영역 선택

터미널

VS Code

확장 프로그램

Visual Studio Marketplace의 수만 개 확장으로 VS Code를 맞춤 개발 환경으로 만듭니다.

확장 설치 방법

한국어 지원

AI 어시스턴트

확장 특징 무료
GitHub Copilot인라인 자동완성, 채팅, 에이전트, 커밋 메시지 생성무료 티어 있음
Claude Code터미널 기반 AI 코딩, 파일 편집, 명령 실행유료
Continue오픈소스, 여러 AI 모델 동시 활용무료
Cody (Sourcegraph)코드베이스 이해, 코드 검색, 설명무료 티어 있음

필수 공통 도구

웹 개발

언어별 필수 확장

테마 추천

확장 관리 CLI

# 설치
code --install-extension ms-python.python

# 특정 버전 설치
code --install-extension ms-python.python@2024.0.1

# 설치 목록 확인
code --list-extensions

# 목록을 파일로 저장 (팀 공유용)
code --list-extensions > extensions.txt

# 파일에서 일괄 설치
cat extensions.txt | xargs -L 1 code --install-extension

# 제거
code --uninstall-extension ms-python.python

# 모든 확장 비활성화로 실행 (문제 해결)
code --disable-extensions
VS Code

Git & 소스 제어

VS Code에 내장된 Git 기능으로 터미널 없이도 버전 관리를 수행합니다.

필수 요구사항

# Git 2.0 이상 설치 필요
git --version

# 사용자 설정
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

소스 제어 뷰 열기

기본 워크플로우 (GUI)

  1. 변경사항 확인 - 소스 제어 뷰에서 수정 파일 클릭 → Diff 보기
  2. 스테이징 - 파일 옆 + 아이콘 클릭 (또는 전체 스테이징)
  3. 커밋 메시지 입력 - 상단 텍스트 박스에 메시지 작성
  4. 커밋 - Ctrl+Enter 또는 체크마크 클릭
  5. Push - Status Bar의 동기화 아이콘 클릭

브랜치 관리

병합 충돌 해결

충돌 발생 시 VS Code가 자동으로 충돌 영역을 표시합니다:

Git 단축키

기능 단축키
소스 제어 뷰 열기Ctrl+Shift+G
변경사항 스테이징파일 옆 +
커밋Ctrl+Enter
인라인 Diff 열기거터의 색상 표시 클릭
Git 명령 팔레트Ctrl+Shift+P → "Git:"

추천 Git 확장

VS Code

디버깅

VS Code의 강력한 디버거로 코드 문제를 효율적으로 찾고 해결합니다.

디버깅 시작

  1. 디버깅할 파일 열기
  2. 브레이크포인트 설정 - 줄 번호 왼쪽 클릭 또는 F9
  3. F5 키로 디버깅 시작 (또는 Run and Debug 뷰)
  4. 디버거 선택 (Node.js, Python 등)

디버그 작업

작업 단축키 설명
계속/일시정지F5다음 브레이크포인트까지 실행
Step OverF10현재 줄 실행 (함수 안으로 들어가지 않음)
Step IntoF11함수 내부로 진입
Step OutShift+F11현재 함수에서 빠져나옴
재시작Ctrl+Shift+F5디버깅 세션 재시작
중지Shift+F5디버깅 종료

브레이크포인트 종류

데이터 검사

launch.json 설정

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Node.js 실행",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/index.js",
      "console": "integratedTerminal"
    },
    {
      "name": "Python 실행",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    },
    {
      "name": "Chrome 디버깅",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}/src"
    }
  ]
}

기본 지원 언어

VS Code

설정 및 단축키

자주 사용하는 단축키와 권장 설정으로 작업 속도를 극대화합니다.

핵심 단축키 (Windows / macOS)

기능 Windows macOS
명령 팔레트Ctrl+Shift+PCmd+Shift+P
파일 빠르게 열기Ctrl+PCmd+P
설정 열기Ctrl+,Cmd+,
내장 터미널Ctrl+`Cmd+`
사이드바 토글Ctrl+BCmd+B
전체 검색Ctrl+Shift+FCmd+Shift+F
줄 복사Alt+Shift+↓Opt+Shift+↓
줄 이동Alt+↑/↓Opt+↑/↓
줄 삭제Ctrl+Shift+KCmd+Shift+K
멀티 커서Alt+ClickOpt+Click
같은 단어 선택Ctrl+DCmd+D
찾기 & 바꾸기Ctrl+HCmd+H
정의로 이동F12F12
브레이크포인트F9F9
디버깅 시작F5F5

권장 설정 (settings.json)

{
  // 편집기
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.wordWrap": "on",
  "editor.formatOnSave": true,
  "editor.bracketPairColorization.enabled": true,
  "editor.minimap.enabled": false,
  "editor.linkedEditing": true,
  "editor.stickyScroll.enabled": true,
  "editor.inlineSuggest.enabled": true,

  // 파일
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000,
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,

  // 터미널
  "terminal.integrated.fontSize": 13,
  "terminal.integrated.defaultProfile.windows": "PowerShell",

  // 워크벤치
  "workbench.colorTheme": "One Dark Pro",
  "workbench.iconTheme": "material-icon-theme",
  "workbench.startupEditor": "none",

  // Git
  "git.autofetch": true,
  "git.confirmSync": false,
  "git.enableSmartCommit": true
}

설정 열기 방법

유용한 설정 동기화

워크스페이스 설정 (.vscode/)

프로젝트/
├── .vscode/
│   ├── settings.json      # 프로젝트별 설정
│   ├── launch.json        # 디버그 설정
│   ├── tasks.json         # 빌드/실행 태스크
│   └── extensions.json    # 권장 확장 프로그램
├── src/
└── package.json

# extensions.json (팀원에게 확장 추천)
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-python.python"
  ]
}
사용자 매뉴얼

시작하기

Vibe Coding Manual 사이트의 사용 방법을 안내합니다.

Vibe Coding Manual이란?

Vibe Coding Manual은 현대 웹 개발에 필요한 5가지 핵심 도구(Claude Code, GitHub, Supabase, Vercel, VS Code)의 사용법을 한곳에 모은 종합 바이브코딩 완벽 매뉴얼입니다. 초보자부터 실무 개발자까지 단계별로 학습할 수 있도록 구성되어 있습니다.

사용 방법

권장 학습 순서

  1. VS Code 설치 - 코드 편집기가 모든 개발의 시작점입니다. winget install Microsoft.VisualStudioCode
  2. Node.js 설치 - JavaScript 런타임과 npm을 설치합니다. winget install OpenJS.NodeJS.LTS
  3. Git & GitHub 설정 - 버전 관리 환경을 구축합니다. winget install Git.Git
  4. Claude Code 설치 - AI 코딩 어시스턴트를 활용합니다. npm install -g @anthropic-ai/claude-code
  5. Supabase & Vercel - 백엔드와 배포 환경을 설정합니다. npm install -g vercel
사용자 매뉴얼

화면 구성

Vibe Coding Manual의 인터페이스 구성 요소를 설명합니다.

상단 내비게이션 바

화면 최상단에 위치한 내비게이션 바입니다. 각 도구별 버튼을 클릭하면 해당 섹션으로 빠르게 이동할 수 있습니다.

좌측 사이드바

각 도구의 세부 메뉴가 카테고리별로 정리되어 있습니다. 원하는 항목을 클릭하면 우측 콘텐츠 영역에 해당 내용이 표시됩니다.

우측 콘텐츠 영역

선택한 항목의 상세 내용이 표시되는 메인 영역입니다. 설명, 코드 예제, 이미지 등이 포함되어 있으며, 코드 블록에는 복사 버튼이 제공됩니다.

하단 푸터

사이트 정보, 포함된 가이드 목록, 관련 링크 등이 표시됩니다.

사용자 매뉴얼

주요 기능

Vibe Coding Manual에서 제공하는 5가지 핵심 가이드를 소개합니다.

Claude Code

Anthropic이 개발한 AI 코딩 어시스턴트입니다. 모바일, 웹, 데스크톱, CLI 4가지 방식으로 사용할 수 있으며, 코드 생성, 디버깅, 리팩토링 등 개발 전반을 지원합니다.

GitHub

세계 최대의 코드 호스팅 플랫폼입니다. Git을 기반으로 버전 관리, 협업, CI/CD를 지원합니다.

Supabase

오픈소스 Firebase 대안으로, PostgreSQL 기반의 백엔드 서비스를 제공합니다.

Vercel

프론트엔드 배포에 최적화된 클라우드 플랫폼입니다. Git 연동으로 자동 배포를 지원합니다.

VS Code

Microsoft가 개발한 무료 코드 에디터로, 확장 프로그램을 통해 다양한 개발 환경을 구성할 수 있습니다.

사용자 매뉴얼

자주 묻는 질문 (FAQ)

Vibe Coding Manual 사용 중 자주 묻는 질문과 답변입니다.

Q. 이 매뉴얼은 누구를 위한 것인가요?

프로그래밍 초보자부터 실무 개발자까지 모두를 대상으로 합니다. 각 도구의 기초부터 고급 활용법까지 단계별로 설명하고 있어 자신의 수준에 맞는 내용을 선택하여 학습할 수 있습니다.

Q. 모든 도구를 반드시 설치해야 하나요?

아닙니다. 자신의 프로젝트에 필요한 도구만 선택적으로 설치하면 됩니다. 다만, VS Code와 Git은 대부분의 개발 환경에서 필수이므로 우선 설치를 권장합니다.

Q. 설치 순서가 중요한가요?

네, 권장 설치 순서가 있습니다. VS Code → Node.js → Git & GitHub → Claude Code → Supabase & Vercel 순으로 설치하면 의존성 문제 없이 원활하게 환경을 구축할 수 있습니다.

Q. Claude Code 사용료가 발생하나요?

Claude Code는 유료 서비스입니다. 자세한 사용료 체계는 Claude 섹션의 "사용료 체계" 페이지에서 확인할 수 있으며, "토큰 절감 방안" 페이지에서 비용을 절약하는 방법도 안내하고 있습니다.

Q. 오프라인에서도 사용할 수 있나요?

이 매뉴얼 페이지 자체는 HTML 파일로 되어 있어 다운로드 후 오프라인에서 열람할 수 있습니다. 단, 일부 외부 이미지는 인터넷 연결이 필요할 수 있습니다.

Q. 매뉴얼에 오류가 있거나 개선 사항이 있으면 어떻게 하나요?

푸터에 있는 연락처로 문의해 주시면 확인 후 반영하겠습니다.