바이브코딩 완벽 매뉴얼

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

Git for Windows 설치 확인

Git이 이미 설치되어 있는지 확인합니다. 버전이 나오면 OK, 오류가 나오면 먼저 설치하세요.

git --version
✅ git version ... 이 나오면 OK
❌ 오류 나오면 👉 https://git-scm.com/download/win 에서 먼저 설치하세요
2

Claude Code 설치

PowerShell에서 아래 명령어를 실행합니다. 설치 중 메시지가 쭉 나올 텐데 결과를 복붙해서 알려주세요.

irm https://claude.ai/install.ps1 | iex
설치 완료 후:
1️⃣ PowerShell 완전히 닫기
2️⃣ PowerShell 새로 열기
3️⃣ claude 입력
자세히 보기 →
3

VS Code 설치

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

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

Node.js 설치

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

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

Git 설치

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

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

GitHub 계정 생성 & 설정

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

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

Claude Code 설치

AI 코딩 어시스턴트. PowerShell에서 아래 명령어로 설치합니다.

irm https://claude.ai/install.ps1 | iex
설치 완료 후 PowerShell 재시작 → claude
자세히 보기 →
8

글로벌 스크린샷 도구 설치

puppeteer-core를 글로벌 설치하면 Claude Code가 브라우저를 제어하여 웹페이지 스크린샷을 촬영하고 UI를 검증할 수 있습니다.

npm install -g puppeteer-core
설치 확인: npm list -g puppeteer-core
9

Supabase 프로젝트 생성

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

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

Vercel 연결 & 배포

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

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

개발 시작!

모든 도구가 준비되었습니다. 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. 매뉴얼에 오류가 있거나 개선 사항이 있으면 어떻게 하나요?

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

🧠 옵시디언

Obsidian 소개 & 개요

Obsidian은 로컬 기반의 강력한 노트 작성 및 지식 관리 플랫폼입니다. AI 통합과 플러그인을 통해 개인 지식 베이스를 구축합니다.

Obsidian이란?

Obsidian은 마크다운 기반의 강력한 로컬 노트 작성 앱으로, 폴더와 마크다운 파일로 지식을 저장하고 관리합니다. 클라우드에만 의존하지 않고, 로컬 컴퓨터에 모든 데이터를 보관합니다.

주요 특징

Obsidian의 4가지 핵심 가치

📚 지식 관리

개인 위키처럼 구조화된 지식 베이스를 구축하고 유지보수합니다.

🧠 AI 협력

Claude, ChatGPT와 통합하여 스마트한 콘텐츠 작성과 분석을 합니다.

🔧 개인화

36개 이상의 플러그인으로 자신의 워크플로우에 맞게 커스터마이징합니다.

🔍 검색 최적화

Omnisearch와 Google 통합으로 정보 검색 속도와 정확성을 극대화합니다.

학습 순서 로드맵

  1. 아키텍처 & 조직화 — 폴더 구조와 문서 체계 설계
  2. AI 통합 도구 — Claude, ChatGPT와의 연동
  3. 기술 설정 — 플러그인 설치와 단축키 커스터마이징
  4. 콘텐츠 관리 — 마크다운 문법과 외부 라이브러리 연동
🧠 옵시디언

아키텍처 & 조직화

효과적인 지식 관리를 위한 폴더 구조 설계와 문서 체계 구축 방법입니다.

시스템 프레임워크와 폴더 구조

Obsidian 지식 베이스의 기본이 되는 폴더 구조입니다. 확장성과 유지보수성을 고려한 설계입니다:

My Vault/
├── 00-Inbox/           # 새로운 노트를 임시로 저장
├── 01-Projects/        # 진행 중인 프로젝트들
├── 02-Areas/           # 관심 영역별 지식 (업무, 학습 등)
├── 03-Resources/       # 참고 자료와 외부 콘텐츠
├── 04-Archive/         # 완료되거나 보관된 항목
├── Templates/          # 노트 작성 템플릿
├── Attachments/        # 이미지와 파일 저장소
└── README.md           # 전체 구조 설명

테이블 오브 컨텐츠 (TOC) 계층 구조

효과적인 네비게이션을 위한 목차 시스템:

양방향 링크 (Backlinks) 활용

노트들을 서로 연결하여 지식의 관계를 표현합니다:

[[프로젝트명]] — 다른 노트로의 링크
[[프로젝트명|Custom Label]] — 표시명 커스터마이징
#태그 — 주제별 분류

그래프 뷰 (Graph View)

연결된 노트들의 관계를 시각화하여 전체 지식 구조를 파악합니다:

문서 체계 설계 원칙

🧠 옵시디언

AI 통합 & 도구

Claude Code, ChatGPT, Smart Connections 플러그인을 활용한 AI 협력 워크플로우입니다.

Claude Code 시스템 파일 활용

Obsidian 노트를 Claude Code의 시스템 파일로 활용하여 스마트한 작성 지원을 받습니다:

AI 모델 선택 기준

작업 추천 모델 특징
콘텐츠 생성 Claude Opus 4.7 고품질 생성, 맥락 이해도 높음
빠른 작성 Claude Sonnet 4.6 속도와 품질의 균형
단순 요약 Claude Haiku 4.5 빠르고 경제적
인터넷 검색 Perplexity AI 최신 정보 검색 및 인용

Smart Connections 플러그인

AI를 활용한 자동 링크 제안:

커스텀 시스템 프롬프트

Obsidian과 AI의 협력을 위한 시스템 프롬프트 예시:

당신은 Obsidian 지식 베이스 관리 전문가입니다.
- 노트는 원자성(한 개념 = 한 노트)을 유지합니다
- 양방향 링크로 관련 노트를 연결합니다
- MOC(Map of Contents)로 상위 개념을 정의합니다
- 마크다운 형식을 준수합니다
- 태그는 #분류/세부분류 형식을 사용합니다

AI 기반 콘텐츠 자동화

🧠 옵시디언

기술 설정

36개 이상의 권장 플러그인, 단축키 설정, 검색 최적화를 위한 기술 가이드입니다.

필수 플러그인 (36개 권장)

📝 편집 & 작성

  • Obsidian Editor
  • Templater (템플릿 자동화)
  • Recall (노트 상기)
  • Various Complements
  • Code Editor Syntax Highlighter

🔍 검색 & 탐색

  • Omnisearch (고급 검색)
  • Google Search (Google 통합)
  • Quick Switcher++
  • Recent Files (최근 파일)
  • Backlinks in Document

🧠 AI & 스마트

  • Smart Connections (AI 링크)
  • Prompt (프롬프트 실행)
  • Waypoint (AI 네비게이션)
  • Llm (LLM 통합)

📊 데이터 & 시각화

  • Dataview (데이터 쿼리)
  • Excalidraw (다이어그램)
  • Charts (그래프)
  • Canvas (캔버스)

🎨 테마 & UI

  • Theme Browser
  • Icon Folder (폴더 아이콘)
  • Hider (UI 요소 숨기기)
  • Custom Frames

⚙️ 자동화 & 동기

  • Obsidian Git (버전 관리)
  • Sync (클라우드 동기)
  • Save Search (검색 저장)
  • Tag Wrangler (태그 관리)
  • Calendar (달력 통합)

핵심 단축키 설정

기능 추천 단축키 용도
빠른 열기 Ctrl+K 노트 검색 및 빠른 이동
명령 팔레트 Ctrl+P 모든 명령 실행
검색 Ctrl+F 노트 내 검색
전역 검색 Ctrl+Shift+F 전체 볼트 검색
새 노트 Ctrl+N 신규 노트 생성
템플릿 삽입 Ctrl+Alt+T 미리 정의된 템플릿 적용

Omnisearch & Google 통합

고급 검색 기능으로 정보 검색을 최적화합니다:

테마 커스터마이징

시각적 환경을 개인화하여 생산성을 향상합니다:

🧠 옵시디언

콘텐츠 관리

마크다운 문법, 외부 라이브러리 통합, AI 기반 콘텐츠 자동화입니다.

마크다운 문법 (연구자용)

Obsidian에서 지원하는 마크다운 문법 완전 가이드:

# H1 제목
## H2 부제목
### H3 소제목

**굵은 글씨** / *이탤릭* / ~~취소선~~

- 불릿 항목
  - 중첩 항목
1. 번호 항목

[[노트명]] — 내부 링크
[[노트명|표시명]] — 커스텀 라벨
#태그 — 태그 분류
#분류/세부분류 — 계층적 태그

> 인용문
>> 중첩 인용

```javascript
코드 블록
```

| 표 | 헤더 |
|----|-----|
| 셀 | 내용 |

---

Eagle Library 연동

외부 이미지 라이브러리 (Eagle)와 Obsidian 통합:

AI 기반 콘텐츠 자동화

ChatGPT 자동 작성

  • 프롬프트 기반 콘텐츠 생성
  • 자동 요약 및 번역
  • 구조화된 데이터 생성

Claude 스마트 조합

  • 맥락 기반 작성
  • 일관성 있는 톤 유지
  • 지식 베이스 기반 보강

외부 라이브러리 통합

Obsidian과 함께 사용할 수 있는 외부 도구들:

도구 기능 통합 방식
Eagle 이미지 라이브러리 직접 삽입
ReadWise 웹 클리핑 자동 임포트
Notion 데이터베이스 양방향 동기
Google Drive 파일 저장소 링크 삽입
Claude Code AI 시스템 파일 시스템 프롬프트

모범 사례 (Best Practices)

시작 체크리스트

Make

Make (구 Integromat) 소개

Make는 코드 없이 앱과 서비스를 연결하는 비주얼 자동화 플랫폼입니다. 드래그 & 드롭으로 복잡한 워크플로우를 구축할 수 있습니다.

Make란 무엇인가?

Make(구 Integromat)는 노코드 자동화 플랫폼으로, 수백 개의 앱과 서비스를 시각적으로 연결하여 자동화 시나리오를 만들 수 있습니다.

핵심 개념

Make vs Zapier 비교

항목MakeZapier
인터페이스비주얼 캔버스 (드래그&드롭)리스트 기반 (단순)
분기/조건라우터 + 필터 (복잡한 로직 가능)Path (제한적)
가격무료 1,000 ops/월무료 100 tasks/월
에러 핸들링Break, Resume, Rollback 등 상세기본적
데이터 변환내장 함수 풍부Formatter 앱 필요
적합 대상복잡한 자동화, 개발자 친화적단순 자동화, 비개발자

시작하기

  1. make.com 접속 → 무료 계정 가입
  2. 대시보드에서 Create a new scenario 클릭
  3. 트리거 모듈 추가 (예: Webhook, Gmail, Google Sheets)
  4. 액션 모듈 연결 (예: Slack 알림, 데이터베이스 저장)
  5. Run once로 테스트 → Turn on으로 활성화
Make

시나리오 기초

Make 시나리오의 생성, 실행, 스케줄링 방법을 알아봅니다.

시나리오 생성

  1. 대시보드 → + Create a new scenario
  2. 캔버스에서 + 버튼 클릭 → 앱 검색
  3. 트리거 모듈 선택 (시나리오 시작점)
  4. 연결(Connection) 설정 — API 키 또는 OAuth 인증
  5. 다음 모듈 추가하여 파이프라인 구성

트리거 유형

스케줄링

실행 히스토리

시나리오 상세 페이지에서 History 탭을 통해 과거 실행 기록, 입출력 데이터, 에러 로그를 확인할 수 있습니다. 디버깅에 필수적입니다.

데이터 매핑

모듈 간 데이터 전달은 매핑 패널을 통해 이루어집니다. 이전 모듈의 출력값을 다음 모듈의 입력 필드에 드래그하여 연결합니다.

Make

모듈 & 연결

주요 모듈 유형과 외부 앱 연결 방법을 다룹니다.

모듈 유형

유형설명예시
트리거시나리오 시작점. 데이터 감지Gmail: Watch Emails, Webhook
액션데이터 생성/수정/삭제Google Sheets: Add a Row
검색기존 데이터 조회Airtable: Search Records
변환데이터 형식 변환JSON: Parse, CSV: Create
흐름 제어분기/반복/에러 처리Router, Iterator, Error Handler

자주 사용하는 앱 연결

HTTP 모듈 활용

Make에 직접 통합되지 않은 서비스는 HTTP 모듈로 연결할 수 있습니다.

연결(Connection) 관리

  1. 모듈 설정에서 Create a connection 클릭
  2. 앱 인증 (OAuth, API Key, 토큰 등)
  3. 한번 생성된 연결은 여러 시나리오에서 재사용 가능
  4. Connections 메뉴에서 전체 연결 목록 관리
Make

AI & 챗봇 자동화

Make를 활용한 AI 통합과 챗봇 구축 방법을 다룹니다.

AI 챗봇 구축 방법

  1. Webhook 트리거 — 사용자 메시지를 수신하는 엔드포인트 생성
  2. OpenAI / Claude 모듈 — 수신된 메시지를 AI에 전달하여 응답 생성
  3. 응답 전송 — Slack, 카카오톡, 웹채팅 등으로 AI 응답 전달
  4. 대화 기록 저장 — Google Sheets 또는 Supabase에 히스토리 저장

OpenAI 연동

Claude (Anthropic) 연동

HTTP 모듈을 사용하여 Anthropic API에 직접 연결합니다.

AI 자동화 시나리오 예시

시나리오구성
이메일 자동 응답Gmail 트리거 → AI 분석 → 자동 답장 생성 → Gmail 전송
고객문의 분류Webhook 수신 → AI 카테고리 분류 → Notion DB 저장 → Slack 알림
콘텐츠 생성Google Sheets 키워드 → AI 글 생성 → WordPress 포스팅
번역 파이프라인Google Drive 파일 감지 → AI 번역 → 번역본 저장 → 알림
SNS 자동화RSS 피드 → AI 요약 → 이미지 생성 → Instagram/X 포스팅
Make

고급 기능

라우터, 에러 핸들링, 데이터 스토어 등 고급 기능을 다룹니다.

라우터 (Router)

하나의 데이터 흐름을 조건에 따라 여러 갈래로 분기합니다.

에러 핸들링

핸들러동작용도
Resume대체값으로 실행 계속선택적 실패 허용
Rollback전체 시나리오 롤백트랜잭션 보장
Commit실행 중단 + 완료 처리부분 실행 허용
Ignore에러 무시하고 계속비핵심 모듈 실패 허용
Break미완료 실행 큐에 저장재시도 필요 시

데이터 스토어 (Data Store)

Make 내장 간이 데이터베이스입니다. 시나리오 간 데이터 공유에 활용합니다.

웹훅 (Webhook) 심화

유용한 내장 함수

Make

템플릿 & 실전 활용

바로 사용 가능한 자동화 템플릿과 실전 활용 팁입니다.

추천 자동화 템플릿

이름구성난이도
폼 → 스프레드시트 → 알림Webhook → Google Sheets → Slack초급
이메일 첨부파일 자동 저장Gmail → Google Drive → 알림초급
SNS 예약 발행Google Sheets → 이미지 생성 → Instagram API중급
고객 리뷰 AI 분석Google Forms → OpenAI 분석 → Notion 저장중급
GitHub 이슈 → 프로젝트 관리GitHub 트리거 → Notion/Linear → Slack 알림중급
다국어 콘텐츠 파이프라인원본 → AI 번역(5개 언어) → CMS 배포고급
풀스택 웹훅 APIWebhook → Supabase CRUD → 응답 반환고급

Make + Claude Code 연동 팁

비용 최적화 팁

유용한 리소스

n8n

n8n 자동화 플랫폼 소개

n8n은 오픈소스 워크플로우 자동화 플랫폼으로, 400개 이상의 앱을 연결하고 AI와 통합하여 업무를 자동화합니다.

n8n이란?

n8n은 2019년 독일의 Jan Oberhauser가 창립한 오픈소스 워크플로우 자동화 플랫폼으로, 현재 100,000개 이상의 조직이 사용하고 있습니다.

왜 n8n인가?

n8n vs 경쟁 도구

항목n8nZapierMakePower Automate
가격무료(셀프호스팅)유료($20/월~)유료($9/월~)유료($15/월~)
오픈소스OXXX
코드 지원JavaScript/PythonX제한적제한적
AI 에이전트네이티브 지원부분 지원부분 지원부분 지원
셀프 호스팅OXX부분
적합 대상개발자, 파워유저비개발자복잡한 자동화MS 생태계

핵심 개념

참고 자료

n8n

설치 가이드

n8n Cloud, Docker, npm, Railway 등 다양한 설치 방법을 안내합니다.

설치 방법 비교

방법난이도비용소요 시간적합 대상
n8n Cloud매우 쉬움월 $20~5분빠른 시작, 관리 부담 최소화
Docker Desktop쉬움무료10분로컬 개발/테스트
Docker CLI중간무료15분서버 운영
Railway쉬움$2~5/월1분가성비 클라우드 배포
npm쉬움무료5분Node.js 환경 로컬 테스트

Docker로 설치 (권장)

# 데이터 볼륨 생성
docker volume create n8n_data

# n8n 실행
docker run -d \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Asia/Seoul" \
  -e TZ="Asia/Seoul" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

Docker Compose (운영 환경)

# docker-compose.yml
version: '3.8'
services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - GENERIC_TIMEZONE=Asia/Seoul
      - TZ=Asia/Seoul
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_RUNNERS_ENABLED=true
    volumes:
      - n8n_data:/home/node/.n8n
volumes:
  n8n_data:

n8n Cloud 시작하기

Railway 배포

초기 설정 체크리스트

  1. 관리자 계정 생성 (강력한 비밀번호 설정)
  2. 타임존 Asia/Seoul 설정
  3. 이메일 인증 완료

서버 권장 사양

환경CPURAM용도
프로토타입1-2 코어2-4GB학습, 소규모 테스트
테스트2-4 코어4-8GB팀 개발 환경
프로덕션4+ 코어8-16GB+본격 운영
n8n

핵심 개념 & 노드

노드, 트리거, 데이터 구조, 표현식 등 n8n의 기본 개념을 마스터합니다.

노드 유형

트리거 종류

유형설명예시
Manual Trigger수동 실행테스트용
Schedule TriggerCron 기반 예약매일 오전 9시
Webhook Trigger외부 이벤트 수신폼 제출, 결제 완료
Email TriggerIMAP 이메일 감지새 이메일 수신
앱별 트리거서비스 이벤트Slack 메시지, GitHub PR

Cron 표현식 예시

0 9 * * 1-5     # 평일 오전 9시
0 */2 * * *     # 2시간마다
30 8 1 * *      # 매월 1일 오전 8시 30분
0 0 * * 0       # 매주 일요일 자정

핵심 노드

JSON 데이터 구조

n8n에서 모든 데이터는 아이템 배열로 흐릅니다. 각 아이템은 {json: {실제 데이터}} 구조를 가집니다.

[
  { "json": { "name": "홍길동", "email": "hong@example.com" } },
  { "json": { "name": "김철수", "email": "kim@example.com" } }
]

표현식 (Expressions)

표현식설명
{{ $json.field }}현재 아이템 데이터
{{ $node["이름"].json }}특정 노드 데이터
{{ $input.first().json }}직전 노드 첫 아이템
{{ $env.변수명 }}환경 변수
{{ $now.toFormat('yyyy-MM-dd') }}현재 시간
{{ $json.name ?? "이름 없음" }}null 처리

HTTP Request 노드

가장 범용적인 노드로, 전용 노드가 없는 서비스에 API를 호출할 수 있습니다.

키보드 단축키

단축키기능
Ctrl+S워크플로우 저장
Ctrl+Z실행 취소
Tab노드 추가
Ctrl+Enter워크플로우 실행
D노드 활성화/비활성화
E노드 실행
P데이터 핀
Ctrl+A전체 선택
n8n

워크플로우 구축 & 관리

효과적인 워크플로우 설계 원칙, 분기 처리, 반복, 에러 핸들링을 다룹니다.

5가지 설계 원칙

  1. 목표를 한 문장으로 정의하라 — 무엇을 자동화하는지 명확히
  2. 명확한 이름을 붙여라 — 동작 설명 2~4단어 (예: "이메일 분류", "Slack 알림 전송")
  3. 왼쪽에서 오른쪽으로 흐르게 만들어라 — 일관된 시각적 흐름
  4. 조기 종료로 불필요한 처리를 막아라 — Filter/IF로 초반에 걸러내기
  5. 테스트를 위한 여유를 남겨라 — 20개 노드 이상이면 Sub-Workflow로 분리

데이터 흐름 패턴

패턴설명노드
분기 (Splitting)조건별 경로 분리IF, Switch, Split Out
병합 (Merging)여러 경로 합치기Merge (Append/By Fields/By Position)
반복 (Looping)배치/조건 반복Loop Over Items, Split In Batches
대기 (Waiting)시간/이벤트 대기Wait
서브 워크플로우모듈화 호출Execute Workflow

IF 조건과 Switch

반복 처리

에러 핸들링

방법설명
Stop and Error즉시 중단 (기본값)
Continue에러 무시하고 계속
Continue (error output)성공/실패 경로 분리 (가장 강력)
Retry on Fail자동 재시도 (Max Tries, Wait 설정)
Error Trigger워크플로우 전체 미처리 에러 캐치

HTTP 상태 코드 대응

n8n

AI 에이전트

n8n의 AI Agent 노드, LLM 연동, 프롬프팅 전략, 메모리 관리를 다룹니다.

AI 에이전트란?

AI 에이전트는 목표 수립 후 자율적으로 계획→도구 선택→실행→검증→재시도하는 시스템입니다. n8n은 ReAct 패턴(생각→행동→관찰)을 반복하여 복잡한 작업을 수행합니다.

AI Agent 노드 3대 구성요소

지원 AI 모델 비교

제공업체모델가격 (입/출력 $1M)특징
OpenAIGPT-4o$2.5 / $10범용 최강, 멀티모달
OpenAIGPT-4o-mini$0.15 / $0.6가성비 최고
AnthropicClaude Opus 4$15 / $75최고 추론, 200K 컨텍스트
AnthropicClaude Sonnet 4$3 / $15균형잡힌 성능
AnthropicClaude Haiku 4$0.8 / $4빠른 속도, 저렴
GoogleGemini 1.5 Pro$1.25 / $51M 컨텍스트

모델 선택 가이드

작업 유형추천 모델이유
일반 텍스트GPT-4o mini속도/비용/성능 균형
긴 문서 요약Claude Sonnet 4200K 컨텍스트
이미지 분석GPT-4o / Gemini 1.5 Pro멀티모달
보안 민감Ollama (로컬)외부 전송 없음
복잡한 추론Claude Opus 4최고 정밀도

프롬프팅 전략

Temperature 가이드: 0.0~0.3(데이터 추출), 0.5~0.7(이메일), 0.7~1.0(창의적 콘텐츠)

메모리 유형

유형저장용도특징
Window Buffer임시단기 대화최근 N개 메시지
Postgres Chat영구장기 기록DB 영구 저장
Redis Chat고성능대규모 동시사용TTL 설정 가능
Vector Store의미 기반수백 메시지 검색관련 내용만 추출

LLM Chain vs AI Agent

비용 절약 전략

n8n

실전 프로젝트

Gmail, Slack, Telegram, Google Sheets, Notion, 웹훅 등 주요 서비스 자동화 실습입니다.

Gmail 이메일 자동화

Slack 봇 만들기

Bot Token Scopes: chat:write, channels:read, users:read

Telegram 봇 만들기

BotFather /newbot으로 생성

Google Sheets 자동화

Sheets API + Drive API 활성화, OAuth 2.0 설정

Notion 연동 자동화

Internal Integration Token (ntn_ 또는 secret_ 접두사), 반드시 해당 데이터베이스에 통합 초대 필요

웹훅 기반 자동화

테스트 URL vs 프로덕션 URL — 프로덕션 URL은 워크플로우 활성화 필수

n8n

ChatGPT & Claude AI 자동화

OpenAI GPT, Anthropic Claude 연동과 AI 이메일 분류, 고객 지원 봇, RAG 시스템, 콘텐츠 생성을 다룹니다.

OpenAI GPT 연동

Anthropic Claude 연동

AI 이메일 자동 분류

처리 시간 4시간→10분 단축

AI 고객 지원 봇

24시간 자동 고객 문의 처리 — Claude Sonnet 또는 GPT-4o

RAG 시스템 구축

AI 콘텐츠 생성

8~16시간 → 30분 단축

멀티 에이전트 시스템

n8n

고급 활용 & 보안

Sub-Workflow, 성능 최적화, 보안 모범 사례, 서버 관리를 다룹니다.

Sub-Workflow

성능 최적화

서버 환경 변수

EXECUTIONS_CONCURRENCY_ACTIVE=25
NODE_OPTIONS=--max-old-space-size=4096
EXECUTIONS_DATA_PRUNE=true
EXECUTIONS_DATA_MAX_AGE=336
EXECUTIONS_DATA_SAVE_ON_ERROR=all
EXECUTIONS_DATA_SAVE_ON_SUCCESS=none

보안 7대 영역

영역핵심 조치
인증 & 접근강력한 비밀번호, JWT, 역할 기반 접근, IP 허용 목록
웹훅 보안HMAC 서명 검증, API Key 검증
크리덴셜 보안n8n Credentials 암호화 저장, 환경변수, 하드코딩 금지
데이터 보안민감 데이터 마스킹, GDPR 준수
네트워크 보안HTTPS 강제, Nginx 리버스 프록시, Rate limiting
코드 노드 보안eval 금지, 입력값 검증, 파라미터화된 쿼리
감사 로그누가, 언제, 무엇을, 어디서, 결과 기록

백업 전략

커뮤니티 노드

2,800+ 노드 — npm 또는 n8n UI에서 설치

n8n

MCP & Claude Code 연동

MCP(Model Context Protocol)를 통한 AI-n8n 통합과 Claude Code에서 워크플로우를 생성/실행하는 방법입니다.

MCP란?

MCP(Model Context Protocol)는 AI 모델과 도구 간 표준 통신 프로토콜입니다.

보안 주의사항

n8n-mcp 설정

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code + n8n 연동

Claude Code로 워크플로우 만들기

n8n에서 Claude Code 활용

SSH 노드로 Claude Code CLI 호출

claude -p "prompt" --output-format text

n8n 스킬 설치

git clone https://github.com/czlonkowski/n8n-skills.git
cp -r n8n-skills/skills/* ~/.claude/skills/

설치되는 스킬: n8n-code-javascript, n8n-code-python, n8n-expression-syntax, n8n-mcp-tools-expert, n8n-node-configuration, n8n-validation-expert, n8n-workflow-patterns

n8n

n8n 한 시간 안에 끝내기

박응용 저 — 1시간 만에 실전 블로그 자동 포스팅 워크플로우를 완성합니다.

목표

사용자 입력 → AI 블로그 작성 → 이미지 생성 → 자동 포스팅. 30~60분 걸리는 블로그 작업을 수 분으로 단축

필요한 API Key

API용도비용
Claude API블로그 콘텐츠 생성$5 무료 크레딧
Google Gemini API이미지 생성무료 티어
위키독스 API블로그 포스팅무료

8단계 워크플로우

  1. 사용자 입력 — n8n Form 트리거, topic(제목)과 contents(아이디어) 필드
  2. 클로드 API 호출 — HTTP Request(POST), Claude API에 블로그 작성 요청
  3. JSON 파싱 — Code 노드(JavaScript), AI 응답에서 title/content/tags/image_prompt 추출
  4. 블로그 생성 — HTTP Request(POST), 위키독스 API로 빈 블로그 생성 → ID 획득
  5. 이미지 생성 — Google Gemini 노드, image_prompt 기반 썸네일 생성 (4번과 병렬 실행)
  6. 이미지 업로드 — HTTP Request, Form Data로 이미지 파일 업로드
  7. 블로그 수정 — HTTP Request(PUT), 제목+내용+이미지 URL로 블로그 완성
  8. 결과 출력 — Form Ending 노드, 완료 메시지와 블로그 ID/URL 표시

핵심 코드

// JSON 파싱 (Code 노드)
const text = $input.first().json.content[0].text;
const cleaned = text.replace(/```json\n?/g, '').replace(/```\n?/g, '');
const parsed = JSON.parse(cleaned);
return [{
  json: {
    title: parsed.title,
    content: parsed.content,
    tags: parsed.tags,
    image_prompt: parsed.image_prompt
  }
}];

표현식 참조 예시

Claude Code로 n8n 수정하기 (부록)

다음 단계

검색기등록

사전 준비: SEO 인프라 구축

검색엔진에 등록하기 전에, 크롤러가 사이트를 찾고 읽을 수 있는 인프라를 먼저 구축해야 합니다.

1. robots.txt 생성

크롤러에게 "어디를 방문해도 되는지" 알려주는 파일입니다.

파일 위치: app/robots.ts

import { MetadataRoute } from 'next';

export default function robots(): MetadataRoute.Robots {
  const siteUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://www.geo-aio.com';

  return {
    rules: [
      {
        userAgent: '*',
        allow: '/',
        disallow: ['/api/', '/admin/', '/settings/', '/mypage/'],
      },
      // AI 크롤러 명시적 허용
      { userAgent: 'GPTBot', allow: '/' },
      { userAgent: 'ClaudeBot', allow: '/' },
      { userAgent: 'Google-Extended', allow: '/' },
      { userAgent: 'PerplexityBot', allow: '/' },
      { userAgent: 'Amazonbot', allow: '/' },
    ],
    sitemap: `${siteUrl}/sitemap.xml`,
  };
}

핵심 포인트:

확인 방법: 배포 후 https://사이트주소/robots.txt 접속

2. sitemap.xml 생성

크롤러에게 "사이트에 어떤 페이지들이 있는지" 알려주는 파일입니다.

파일 위치: app/sitemap.ts

import { MetadataRoute } from 'next';

export default function sitemap(): MetadataRoute.Sitemap {
  const siteUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://www.geo-aio.com';
  const now = new Date();

  return [
    { url: siteUrl, lastModified: now, changeFrequency: 'weekly', priority: 1.0 },
    { url: `${siteUrl}/blog`, lastModified: now, changeFrequency: 'daily', priority: 0.9 },
    { url: `${siteUrl}/introduction`, lastModified: now, changeFrequency: 'monthly', priority: 0.8 },
    { url: `${siteUrl}/pricing`, lastModified: now, changeFrequency: 'monthly', priority: 0.7 },
    { url: `${siteUrl}/community`, lastModified: now, changeFrequency: 'weekly', priority: 0.6 },
    { url: `${siteUrl}/resources`, lastModified: now, changeFrequency: 'weekly', priority: 0.6 },
    { url: `${siteUrl}/manual`, lastModified: now, changeFrequency: 'monthly', priority: 0.5 },
  ];
}

핵심 포인트:

3. 메타태그 추가 (layout.tsx)

검색엔진과 SNS에서 사이트 정보를 올바르게 표시하기 위한 메타데이터입니다.

파일 위치: app/layout.tsx

export const metadata: Metadata = {
  title: "GEOAIO - AI 콘텐츠 최적화 대시보드",
  description: "AI Overview 및 Generative Engine 최적화를 위한 콘텐츠 분석 도구",
  metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL || 'https://www.geo-aio.com'),
  verification: {
    google: process.env.NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION,
    other: {
      'naver-site-verification': process.env.NEXT_PUBLIC_NAVER_SITE_VERIFICATION
        ? [process.env.NEXT_PUBLIC_NAVER_SITE_VERIFICATION] : [],
    },
  },
  openGraph: {
    type: 'website', locale: 'ko_KR', siteName: 'GEO-AIO',
    title: 'GEOAIO - AI 콘텐츠 최적화 대시보드',
    description: 'AI Overview 및 Generative Engine 최적화를 위한 콘텐츠 분석 도구',
  },
  robots: { index: true, follow: true, googleBot: { index: true, follow: true } },
};

4. 환경변수 설정

.env.local (로컬 개발용):

NEXT_PUBLIC_SITE_URL=https://www.geo-aio.com
NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION=인증코드
NEXT_PUBLIC_NAVER_SITE_VERIFICATION=인증코드

Vercel 환경변수 (배포용):

  1. Vercel 대시보드 > Settings > Environment Variables
  2. 위 3개 변수를 동일하게 추가
  3. Environment: All (Production, Preview, Development) 선택
중요: .env.local은 로컬 전용이므로, Vercel에도 반드시 추가해야 배포 시 반영됩니다.

5. 빌드 및 배포

# 빌드 확인
npx next build

# 빌드 결과에서 확인:
# ○ /robots.txt     ← 정적 생성 확인
# ○ /sitemap.xml    ← 정적 생성 확인

# Git 커밋 & 푸시 (Vercel 자동 배포)
git add app/robots.ts app/sitemap.ts app/layout.tsx
git commit -m "feat: add SEO infrastructure"
git push origin master
▶ 📄 search_engine.md 원본 (참고용 — 클릭하여 펼치기) 전체 가이드 + 이전 작업 대화 기록 포함 
# 홈페이지 검색엔진 등록 가이드 (Google + 네이버)

대상 사이트: https://www.geo-aio.com | 작성일: 2026-04-01
기술 스택: Next.js (App Router) + Vercel + Supabase

## 1. 사전 준비: SEO 인프라 구축
- robots.txt (app/robots.ts): AI 크롤러 허용, /api/ /admin/ 차단
- sitemap.xml (app/sitemap.ts): 공개 페이지 목록
- layout.tsx: Google/네이버 인증 메타태그, OpenGraph, robots
- 환경변수: NEXT_PUBLIC_SITE_URL, GOOGLE/NAVER_SITE_VERIFICATION
  → .env.local + Vercel 모두 설정 필요

## 2. Google Search Console 등록
1) search.google.com/search-console > 도메인 > geo-aio.com
2) DNS TXT 레코드 추가 (가비아: 타입 TXT, 호스트 @, 값 인증코드)
3) nslookup -type=TXT geo-aio.com 8.8.8.8 으로 확인
4) 사이트맵 제출: sitemap.xml
5) URL 검사 > 주요 URL 색인 생성 요청

## 3. 네이버 서치어드바이저 등록
1) searchadvisor.naver.com > 웹마스터 도구 > https://www.geo-aio.com
   (호스트 단위! 경로 포함하면 에러)
2) 소유확인: HTML 파일 업로드 또는 메타태그
3) 사이트맵 제출: 요청 > 사이트맵 제출 > sitemap.xml

## 4. 블로그 SSR 전환
- 문제: useEffect 데이터 로드 → 크롤러에게 0개 포스트
- 해결: page.tsx(서버) + BlogClient.tsx(클라이언트) 분리
- export const dynamic = 'force-dynamic'
- 결과: 크롤러에게 61개 포스트 전체 노출

## 5. 등록 후 유지보수
- 1~3일: 크롤링 시작 / 1~2주: 검색 노출 / 즉시: Perplexity
- AI 인용 높이기: 독창 데이터, 백링크, E-E-A-T, FAQ형식, 꾸준한 발행

## 6. 파일 목록
app/robots.ts, app/sitemap.ts, app/layout.tsx,
app/blog/page.tsx, app/blog/BlogClient.tsx,
public/naver*.html, .env.local

============================================================
부록: 이전 작업 대화 기록 (2026-03-31)
============================================================
Q1: 블로그 포스팅 → AI 인용 가능? → 인프라 없어서 불가 → 구현 완료
Q2: 실제 인용되나? → 기술 완성, but 도메인 권위/E-E-A-T/독창성 필요
    Perplexity(높음), Google AI(중간), ChatGPT Browse(중간), 기본(낮음)
Q3: Google Search Console 등록 → DNS TXT 인증 → 사이트맵 제출 완료
    + 네이버 서치어드바이저 동일 등록
검색기등록

Google Search Console 등록

Google 검색에 사이트를 등록하고 사이트맵을 제출하는 절차입니다.

1단계: Search Console 접속 및 사이트 추가

  1. https://search.google.com/search-console 접속 (Google 계정 로그인)
  2. 좌측 상단 "속성 추가" 클릭
  3. "도메인" 선택 → geo-aio.com 입력 (www 없이)
"URL 접두어" 방식도 가능하지만, "도메인" 방식이 www/non-www 모두 포함하여 권장됩니다.

2단계: 소유권 인증 (DNS TXT 레코드)

Google이 제공하는 TXT 레코드를 도메인 DNS에 추가합니다.

DNS 네임서버 확인:

nslookup -type=NS geo-aio.com 8.8.8.8

DNS 설정 방법 (가비아 기준):

  1. https://dns.gabia.com 로그인
  2. 도메인 선택
  3. DNS 레코드 추가:
타입 TXT
호스트 @ (또는 빈칸)
값 google-site-verification=인증코드
TTL 3600 (기본값)

DNS 반영 확인 (수 분 소요):

nslookup -type=TXT geo-aio.com 8.8.8.8

결과에 google-site-verification=... 텍스트가 보이면 반영 완료.

Search Console에서 "확인" 버튼 클릭 → 소유권 인증 완료

3단계: 사이트맵 제출

  1. Search Console 좌측 메뉴 > "사이트맵" 클릭
  2. URL 입력: https://www.geo-aio.com/sitemap.xml
  3. "제출" 클릭

4단계: URL 색인 생성 요청

주요 페이지는 개별 색인 요청으로 빠르게 등록할 수 있습니다.

  1. Search Console > "URL 검사" 클릭
  2. 다음 URL을 하나씩 입력 후 "색인 생성 요청" 클릭:
https://www.geo-aio.com
https://www.geo-aio.com/blog
https://www.geo-aio.com/introduction
https://www.geo-aio.com/pricing
신규 사이트는 "URL이 Google에 등록되어 있지 않음"이 정상입니다. 색인 생성 요청 후 수일~2주 내에 등록됩니다.
검색기등록

네이버 서치어드바이저 등록

네이버 검색에 사이트를 등록하고 사이트맵을 제출하는 절차입니다.

1단계: 서치어드바이저 접속 및 사이트 추가

  1. https://searchadvisor.naver.com 접속 (네이버 계정 로그인)
  2. "웹마스터 도구" 클릭
  3. URL 입력: https://www.geo-aio.com (호스트 단위, 경로 없이)
  4. "추가" 클릭
주의: https://www.geo-aio.com/sitemap.xml처럼 경로를 포함하면 "URL을 호스트 단위로 입력해주세요" 에러가 발생합니다.

2단계: 소유확인

두 가지 방법 중 선택합니다.

방법 A: HTML 파일 업로드 (권장)

네이버가 제공하는 HTML 파일을 public/ 폴더에 생성합니다.

# 파일명은 네이버가 제공하는 것을 사용 (예시)
echo "naverf5844d70cb270f32088799b59ad912ad" > public/naverf5844d70cb270f32088799b59ad912ad.html

배포 후 해당 URL로 접근 가능해야 합니다.

방법 B: HTML 메타태그

app/layout.tsx의 metadata에 인증 코드를 환경변수로 설정합니다.

NEXT_PUBLIC_NAVER_SITE_VERIFICATION=인증코드값

이 환경변수가 설정되면 <meta name="naver-site-verification" content="코드값" />이 자동으로 HTML에 포함됩니다.

Vercel 환경변수에도 동일하게 추가 후 재배포 필요.

서치어드바이저에서 "소유확인" 버튼 클릭 → 인증 완료

3단계: 사이트맵 제출

  1. 사이트 목록에서 사이트 클릭 (관리 화면 진입)
  2. 좌측 메뉴 > "요청" > "사이트맵 제출" 클릭
  3. URL 입력: https://www.geo-aio.com/sitemap.xml
  4. "확인" 클릭
검색기등록

블로그 SSR 전환

크롤러가 블로그 콘텐츠를 읽을 수 있도록 서버사이드 렌더링으로 전환합니다.

왜 필요한가?

Next.js에서 'use client' 컴포넌트도 서버에서 초기 렌더링됩니다. 하지만 useEffect로 데이터를 가져오는 경우, 크롤러가 방문할 때 데이터가 비어 있는 HTML을 보게 됩니다.

변경 전 크롤러에게 "총 0개 포스트" (데이터 없음)
변경 후 크롤러에게 "총 61개 포스트" (모든 제목/요약 포함)

해결: 서버 컴포넌트 + 클라이언트 컴포넌트 분리

page.tsx (서버 컴포넌트 — 데이터 fetch):

// app/blog/page.tsx
import { createClient } from '@supabase/supabase-js';
import BlogClient from './BlogClient';

export const dynamic = 'force-dynamic'; // 매 요청마다 최신 데이터

async function getServerBlogData() {
  const supabase = createClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  );
  const { data } = await supabase
    .from('blog_articles')
    .select('*')
    .order('created_at', { ascending: false })
    .limit(200);
  // ... 데이터 가공
  return { posts, categories };
}

export default async function BlogPage() {
  const { posts, categories } = await getServerBlogData();
  return <BlogClient initialPosts={posts} initialCategories={categories} />;
}

BlogClient.tsx (클라이언트 컴포넌트 — 인터랙티브 UI):

// app/blog/BlogClient.tsx
'use client';

import { useState } from 'react';

export default function BlogClient({ initialPosts, initialCategories }) {
  const [posts] = useState(initialPosts);
  // ... 탭 전환, 포스트 클릭 등 인터랙티브 로직
}

핵심 포인트

# 빌드 결과 확인
├ ƒ /blog       ← Dynamic (서버 렌더링) ✅
├ ○ /pricing    ← Static (정적 생성)
검색기등록

등록 후 확인 및 유지보수

색인 반영 일정과 정기 확인 사항, AI 인용 확률을 높이는 방법입니다.

색인 반영 예상 일정

1~3일 Google 크롤링 시작, 일부 페이지 색인
1~2주 주요 페이지 검색 노출 시작
2~4주 Search Console에 실적 데이터 표시 (클릭, 노출)
즉시~수일 Perplexity에서 검색 가능 (실시간 크롤링)

정기 확인 사항 (주 1회)

Google Search Console

네이버 서치어드바이저

새 페이지 추가 시

  1. app/sitemap.ts에 새 경로 추가
  2. 배포
  3. Google Search Console > URL 검사 > 색인 생성 요청

AI 인용 확률을 높이는 5가지 방법

  1. 독창적 데이터 포함 — 자체 조사, 실험 결과, 사례 분석
  2. 외부 백링크 확보 — 브런치, 링크드인 등에서 사이트 URL 언급
  3. E-E-A-T 강화 — 저자 정보, 전문 자격, 실제 경험 데이터 포함
  4. 구조화된 FAQ/How-to 형식 — AI가 답변으로 채택하기 쉬운 구조
  5. 꾸준한 발행 — 도메인 권위 축적
검색기등록

생성/수정된 파일 및 환경변수 목록

검색엔진 등록 과정에서 생성 또는 수정된 모든 파일과 환경변수입니다.

파일 목록

파일 설명 구분
app/robots.ts AI 크롤러 허용 robots.txt 신규
app/sitemap.ts 동적 사이트맵 생성 (7개 페이지) 신규
app/layout.tsx Google/네이버 인증 메타태그, OpenGraph, robots 수정
app/blog/page.tsx 블로그 SSR 서버 컴포넌트 수정
app/blog/BlogClient.tsx 블로그 클라이언트 컴포넌트 신규
public/naver*.html 네이버 소유확인 파일 신규
.env.local 사이트 URL, Google/네이버 인증 코드 수정

환경변수 목록

변수명 값 설정 위치
NEXT_PUBLIC_SITE_URL https://www.geo-aio.com .env.local + Vercel
NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION Google 인증 코드 .env.local + Vercel
NEXT_PUBLIC_NAVER_SITE_VERIFICATION 네이버 인증 코드 .env.local + Vercel

DNS 네임서버 확인 방법

# 도메인의 DNS가 어디서 관리되는지 확인
nslookup -type=NS geo-aio.com 8.8.8.8

# 결과 예시:
# geo-aio.com  nameserver = ns.gabia.co.kr  → 가비아에서 DNS 관리 중
스킬

스킬 목록

Claude Code에서 사용할 수 있는 커스텀 스킬(슬래시 커맨드) 모음입니다. 복사 버튼을 클릭하면 해당 스킬의 MD 파일 전체 내용이 클립보드에 복사됩니다.

/5times-debug-loop-코어3
5회 반복 디버깅 루프 — 문제를 분석하고 수정하고 검증하며 최대 5회 반복. Playwright 스크린샷으로 자동 검증
/api-builder-core
RESTful API 엔드포인트 설계 및 구현 전문 스킬
/api-test-core
API 엔드포인트 기능/성능/보안 테스트 전문 스킬
/architecture-svg
아키텍처 전체구조도 SVG 생성 — V50 스타일 기반 테이블형 다이어그램
/cicd-setup-core
GitHub Actions 기반 CI/CD 파이프라인 구성 및 자동화 스킬
/cpc-add-project
CPC 프로젝트 추가 (소대 등록 + Agent Server 생성)
/cpc-engage
CPC 소대장 자동 인식 + Agent Server 가동
/cpc-setup
CPC (Claude Platoons Control) 인프라 구축 - Supabase + Vercel + 소대 등록 + 연락병 배포
/create-image-core
이미지 생성 종합 시스템 (SVG/HTML/Mermaid/Pillow)
/db-schema-core
Supabase(PostgreSQL) 데이터베이스 스키마 설계 및 마이그레이션 전문 스킬
/deploy-skill-core
최강 스킬 조합 편성 및 장착 전략
/deploy-subagent-core
최정예 서브에이전트(분대원) 편성 및 복합 투입 전략
/design-theme-analyzer
웹사이트 URL 입력 → 디자인/테마/레이아웃 자동 분석 + 스코어링 + 개선안 제시 (범용)
/doc-generator-core
문서 생성기 (PDF/DOCX/PPTX/XLSX/HWP)
/e2e-test-core
Playwright 기반 End-to-End 테스트 작성 및 실행 스킬
/exploratory-data-analysis
데이터 탐색 및 분석 — EDA, 시각화, 인사이트 도출, 통계 요약
/find-skills-core
AI 에이전트 스킬 검색 및 설치 (skills.sh 오픈 생태계)
/n8n-workflow-test
n8n 워크플로우 JSON 정적 분석 + 데이터 체인 모의테스트 (드라이런)
/performance-check-core
프론트엔드/백엔드 성능 분석 및 최적화 스킬
/platoon-formation-v1
소대 편제 방식 팀구성 - 소대장+연락병+3분대(Alpha/Bravo/Charlie) 편성
/platoon-formation-v2
소대 편제 방식 팀구성 (66명) - 소대장+연락병+5분대 + 용병4 + 19 Skills
/review-evaluate-core
검토 및 5기준 평가 - 97점 도달까지 순환 루프 (최소 3회)
/sal-grid-dev-슈퍼스킬1
SAL Grid 3D 좌표계 개발방법론 V3 - Template 기반, 동적 Stage, 소급 도입 지원
/security-audit-core
OWASP Top 10 기반 보안 취약점 검사 및 감사 스킬
/screenshot
데스크탑/웹페이지 스크린샷 캡쳐 및 분석 — PowerShell 또는 Puppeteer로 화면 캡쳐 후 자동 분석
/slideshow-web-코어2
PPT 슬라이드쇼 웹페이지 생성 + GitHub 공유
/troubleshoot-core
문제 진단, 로그 분석, 근본 원인 분석(RCA) 및 긴급 대응 스킬
/ui-ux-builder-core
UX 경험 설계 + UI 컴포넌트 구현 통합 스킬
/youtube-generate-core
유튜브 영상 올인원 자동화 — 소재 파일 → 리서치 → 대본 → 재료 생성 → 블로그
/youtube-generate-코어4
유튜브 영상 올인원 자동화 — 소재 파일 → 리서치 → 대본 → 재료 생성 → 블로그 (v4)
/architecture-svg
SVG 구조도 자동 생성 — 프로젝트의 아키텍처, 디렉토리 구조, 모듈 관계, 데이터 흐름을 SVG 다이어그램으로 시각화
/chatbot-rag
챗봇 인터페이스(RAG) 자동 생성 — Supabase pgvector 기반 RAG 챗봇 UI + 백엔드 파이프라인을 프로젝트에 자동 탑재
/copyright
저작권 등록 자료 자동 생성 — 프로젝트 소스코드/문서/방법론에 대한 한국저작권위원회 등록용 자료 패키지 생성
/manual-page
매뉴얼 페이지 (프리미엄 디자인) 자동 생성 — 사용 가이드, FAQ, 기능 설명을 프리미엄 화이트 테마 디자인으로 생성
/mobile-optimize
모바일 화면 최적화 — 반응형 레이아웃, 터치 UX, 뷰포트 적응, 성능 최적화를 자동 분석·적용
/patent-spec
특허 명세서 작성 자료 자동 생성 — 소프트웨어 발명에 대한 한국특허청(KIPO) 출원용 명세서 초안 및 도면 패키지 생성
/pdf-download
PDF 다운로드 v3 — html2canvas+jsPDF WYSIWYG 1순위, window.print() 2순위, Puppeteer 3순위 폴백. 그래프/차트/SVG 완벽 포함 + 잘림 방지
/text-clean
글자 투명도 최적화 + 섹션/카드 프리미엄 컬러 적용 — 텍스트 계층별 opacity/color 체계 설계 + 배경·테두리에 브랜드 Accent 기반 프리미엄 컬러 시스템 자동 적용
/ontology
AX 온톨로지 엔진 — AXOS 방법론 + 질문셋 엔진 + 그래프 생성 + 플랫폼 설계를 하나로 통합한 올인원 스킬
/ai-training-platform
AI 교육 플랫폼 범용 프레임워크 — SPIN Selling AI에서 추출한 재사용 아키텍처로 리더십/코칭/협상 등 모든 역량 교육 플랫폼을 빠르게 개발
/english-conversion
한국어 플랫폼 → 다국어(영어·중국어·일본어 등) 변환 스킬 — 파일 명명 규칙, 공통 nav/footer 패턴, 언어 감지·토글, 자주 발생하는 함정과 해결법, 전체 체크리스트
/pitchdeck-html
프로젝트/플랫폼/서비스를 분석해 슬라이드 수를 선택하고 완성형 HTML 피치 덱을 자동 생성 — 다크 그라디언트 풀스크린, 슬라이드 전환 애니메이션, 키보드/스와이프 네비게이션, PDF 다운로드 버튼
/platform-pitch
플랫폼 전체를 분석해 고객 세그먼트별 설득 메시지·고객 가치 자료를 자동 생성 — 기능 지도·차별점·페르소나별 피치 덱·세일즈 카피·FAQ·한 장 요약본까지 완전 자동 생성
📘 8가지 팁 — 에이전트 스킬(Skill) 마스터하기
에이전트 스킬을 효과적으로 설계·운영하기 위한 8가지 실전 팁 가이드 (PDF)
열기
디자인분석

웹 디자인 분석기

웹사이트 URL을 입력하면 디자인 시스템, 컬러, 레이아웃, 타이포그래피, 반응형, 접근성을 자동 분석합니다.

실시간 디자인 분석

분석할 웹사이트 URL을 입력하고 '분석 시작' 버튼을 클릭하세요. CORS 프록시를 통해 HTML/CSS를 가져와 클라이언트에서 분석합니다.

웹사이트를 가져오는 중...
📊 분석 기록 0건
⚡ Supabase 연동
로딩 중...
--
종합 점수 / 100
추출된 컬러 팔레트
사용된 폰트
✓ 강점
⚠ 개선 필요
★ 최적화 제안

메뉴 & 레이아웃 디자인 분석

현재 사이트의 UI/UX 구조를 분석하고, 각 영역별 강점과 개선 가능한 최적화 아이디어를 정리했습니다.

시각적 계층구조
92
브랜드 일관성
95
반응형 대응
72
접근성(A11y)
65
인터랙션 디자인
88
정보 밀도 균형
78
✓ 현재 디자인 강점
강점 브랜드 컬러 시스템
12개 이상의 CSS 변수 기반 브랜드 컬러 체계가 완벽하게 구축됨. Claude(시안), GitHub(퍼플), Supabase(그린) 등 각 섹션이 고유한 색상 아이덴티티를 유지하면서도 전체적으로 통일된 다크 테마를 형성.
강점 글래스모피즘 네비게이션
상단 네비게이션의 backdrop-filter: blur(20px) + 85% 투명도 조합이 세련된 깊이감 제공. 스크롤 시에도 콘텐츠와 자연스럽게 블렌딩되면서 가독성 유지.
강점 마이크로 인터랙션
카드 호버 시 translateY(-4px) + 그림자 확산, 버튼 복사 완료 시 색상 전환 피드백 등 세밀한 인터랙션이 프리미엄 UX 경험을 제공. 모든 트랜지션이 0.2s ease로 일관됨.
강점 사이드바 계층 구조
260px 고정 사이드바에 브랜드별 색상 헤더 + 들여쓰기 링크 구조로 명확한 정보 계층 표현. 활성 항목의 오른쪽 컬러 보더(2px)가 현재 위치를 직관적으로 안내.
⚠ 개선 가능 영역
개선 5컬럼 그리드 → 유동 그리드
홈 카드가 고정 repeat(5, 1fr) 그리드를 사용해 중간 해상도(1024~1280px)에서 카드가 지나치게 좁아짐. repeat(auto-fit, minmax(260px, 1fr))로 변경하면 모든 뷰포트에서 자연스러운 리플로우 가능.
개선 키보드 포커스 표시 부재
현재 :focus-visible 스타일이 정의되지 않아 키보드 네비게이션 시 활성 요소를 식별할 수 없음. 각 인터랙티브 요소에 브랜드 컬러 기반 아웃라인 링을 추가하면 접근성(WCAG 2.1 AA) 준수 가능.
개선 단일 브레이크포인트 한계
768px 단일 브레이크포인트만 존재해 태블릿(768~1024px) 구간에서 사이드바가 표시되지만 콘텐츠 영역이 부족함. 1024px, 1280px 중간 브레이크포인트를 추가하면 태블릿/소형 데스크탑 경험이 크게 향상됨.
개선 스킬 설명 텍스트 잘림
text-overflow: ellipsis로 긴 설명이 잘리는데, 모바일에서는 전체 설명을 볼 방법이 없음. 호버 시 툴팁 표시 또는 2줄 클램프(-webkit-line-clamp: 2)로 변경하면 더 많은 정보 노출 가능.
★ 최적화 아이디어
아이디어 사이드바 접이식 전환
사이드바를 아이콘 모드(60px)와 전체 모드(260px) 사이에서 토글 가능하게 변경. 아이콘 모드에서는 섹션 이모지만 표시하고 호버 시 확장. 콘텐츠 영역을 최대 200px 더 확보 가능.
아이디어 스킬 카테고리 필터 탭
스킬 목록 상단에 카테고리 필터 칩(개발, 테스트, 문서, 디자인, 자동화)을 추가. 칩 클릭으로 즉시 필터링되고, 검색과 조합 가능. 30개 이상 스킬에서 탐색 효율이 2~3배 향상.
아이디어 스크롤 진행률 인디케이터
상단 네비게이션 하단에 얇은(2px) 그라디언트 프로그레스 바를 추가. 현재 읽고 있는 섹션의 브랜드 컬러로 자동 전환. 긴 문서에서 위치감과 진행도를 직관적으로 제공.
아이디어 다크/라이트 테마 토글
CSS 변수 기반 테마 시스템이 이미 구축되어 있어 라이트 모드 추가가 용이. :root 변수셋만 교체하면 됨. 상단 네비게이션에 작은 토글 스위치 추가로 사용자 선호 테마 지원.
아이디어 TOC(목차) 미니맵
우측 여백(사이드바 반대편)에 현재 섹션의 하위 항목을 표시하는 미니 목차 추가. VS Code의 미니맵처럼 현재 위치를 하이라이트하고 클릭으로 점프. 긴 섹션 내 탐색 시간 단축.
아이디어 스킬 카드 2컬럼 레이아웃
넓은 화면에서 스킬 카드를 grid-template-columns: repeat(2, 1fr)로 배치. 한 화면에 더 많은 스킬이 보이고 스크롤이 줄어듦. 1200px 이상에서 자동 적용.
⚡ 빠른 적용 가능 항목 (Quick Wins)
Quick 스크롤 투 탑 버튼
페이지 하단에서 상단으로 즉시 이동하는 플로팅 버튼. position: fixed + scroll-behavior: smooth로 3줄 CSS + 5줄 JS면 구현 완료.
Quick 로딩 스켈레톤 애니메이션
카드 로딩 시 펄스 애니메이션 스켈레톤을 표시하면 체감 로딩 속도 향상. @keyframes pulse + 그라디언트 오버레이로 10줄 CSS면 구현 가능.
Quick Ctrl+K 단축키 검색
전역 검색 모달을 Ctrl+K로 열 수 있게 추가. 현재 섹션별 검색을 통합하여 어디서든 빠르게 원하는 스킬/섹션/키워드로 점프 가능.
Quick 활성 네비 자동 하이라이트
IntersectionObserver로 스크롤 위치에 따라 사이드바와 상단 네비 버튼의 활성 상태를 자동 동기화. 현재 위치를 항상 정확하게 반영.
⇄ Before → After 예시: 스킬 그리드
Before (현재)
.skill-grid { grid-template-columns: 1fr; gap: 12px; } .skill-desc { white-space: nowrap; text-overflow: ellipsis; }
→
After (제안)
.skill-grid { grid-template-columns: repeat( auto-fit, minmax(480px, 1fr)); gap: 14px; } .skill-desc { -webkit-line-clamp: 2; display: -webkit-box; }
폴더구조

프로젝트 폴더 탐색기

C:\01 클로드코드 내 93개 프로젝트 폴더를 카테고리별로 탐색합니다. 카드를 클릭하면 해당 목록이 아래에 표시됩니다.

10
Vibe Coding OS
19개 폴더
20
치과 AI 솔루션
17개 폴더
30
AI 교육/출판
17개 폴더
40
미디어/콘텐츠
12개 폴더
50
비즈니스
15개 폴더
60
개인 클라이언트
9개 폴더
ETC
기타/자료
13개 폴더
+
카테고리 추가
 

10 — Vibe Coding OS / 플랫폼

바이브코딩 OS 핵심 도구, 매뉴얼, Claude, 플랫폼 프로젝트
번호폴더명설명
03-01aitutorhub 심재우대표 - AI솔루션 포트폴리오AI 솔루션 포트폴리오 사이트
03-02Shim Platform Index심재우 플랫폼 인덱스
03-03AX비즈그룹AX 비즈니스 그룹 포탈
03-04AX덴탈그룹AX덴탈그룹 포탈
10Vibe Coding OS바이브코딩 운영체제 메인
10-00Vibe Coding OS - 정치솔루션정치 특화 솔루션
10-00-01오세훈 플랫폼오세훈 시장 전용 플랫폼
10-00-02정치인 표준 플랫폼정치인 표준 템플릿 플랫폼
10-01바이브코딩 매뉴얼(집필용)바이브코딩 매뉴얼 집필 원고
10-02바이브코딩 깃 사용법Git/GitHub 워크플로우 가이드
10-03메이크 매뉴얼Make(Integromat) 자동화 매뉴얼
10-04클로드코드 오케스트레이션Claude Code 멀티에이전트 오케스트레이션
10-05ClaudeClaude AI 관련 리소스
10-06UI & 유틸리티 쇼케이스UI 컴포넌트 및 유틸리티 데모
10-7AX교육플랫폼AX 교육 플랫폼 (clone 포함)
10-08n8n - AI Super Platformn8n 기반 AI 자동화 슈퍼 플랫폼
10-9미로피쉬미로피쉬 프로젝트
10-10미로피쉬-선웅규선웅규 대표 미로피쉬
10-11대한민국 AI 로드맵 2026대한민국 AI 로드맵 프로젝트

20 — 치과 AI 솔루션

치과 산업 특화 AI 솔루션 프로젝트
번호폴더명설명
20-01AX덴탈그룹AX덴탈그룹 메인 프로젝트
20-02AX BIZ 그룹AX 비즈니스 그룹
20-03덴탈클리닉파인더치과 병원 검색 플랫폼
20-04덴탈클리닉파인더 프랜차이즈프랜차이즈 치과 연계 시스템
20-05치과 AI 솔루션 통합치과 광고/마케팅 AI 통합 솔루션
20-06치과 병원 진단지 분석 앱AI 기반 치과 진단지 분석
20-07치과 광고 콘텐츠 생성 - 구버전치과 마케팅 콘텐츠 (구버전)
20-08치과 카드뉴스 생성기치과 카드뉴스 자동 생성 도구
20-09디지털스마일치과디지털스마일치과 프로젝트
20-10개원의 빌드업 프로그램치과 개원의 성장 지원 프로그램
20-11구강 방문케어 센터방문형 구강 케어 서비스
20-12치과 개업 의사결정 맵치과 개업 의사결정 지원 도구
20-13대한치과위생사 유은미 교수유은미 교수 협업 프로젝트
20-14덴탈클리닉파인더 아카데미 - 복사본아카데미 복사본 (정리 필요)
20-14치과 카드뉴스 생성기카드뉴스 생성기 (중복 번호)
20-15디지털스마일치과디지털스마일치과 (추가 버전)
20-16화이트서울치과화이트서울치과 프로젝트

30 — AI 교육/출판

AI 기반 교육 콘텐츠와 출판 프로젝트
번호폴더명설명
30-00AI노벨문해력5 02 - 복사본복사본 (정리 필요)
30-01AI노벨문해력5 v1AI 소설 문해력 교육 v1
30-02AI노벨문해력5 v2AI 소설 문해력 교육 v2 (개선판)
30-03AI노벨문해력5 앱 학교용학교 교육용 AI노벨문해력 앱
30-04AITutorHub 통합AI 튜터링 허브 통합 플랫폼
30-05AITutorHub 포트폴리오AITutorHub 포트폴리오 사이트
30-06AUTOBOOK STUDIOAI 자동 도서 제작 스튜디오
30-07오토북 엔진AUTOBOOK 코어 엔진
30-08Book Store온라인 서점 플랫폼
30-09집필도서 집필 프로젝트
30-10어머니의 손맛 레시피레시피 콘텐츠 출판 프로젝트
30-11큐매쓰(질문수학)질문 기반 수학 교육 플랫폼
30-11-02큐매쓰 2 / 큐매쓰 3큐매쓰 후속 버전들
30-12future_competency_ai_lab미래 역량 AI 연구소
30-13RQTDWRQTDW 교육 프로젝트
30-14K-AI출판허브한국 AI 출판 허브 플랫폼
32AUTOBOOK STUDIO (오토북 스튜디오) - 복사본복사본 (정리 필요)

40 — 미디어/콘텐츠

미디어 제작, 라디오카페, 영상/이미지 생성
번호폴더명설명
40-01클라라 라디오카페클라라 AI 라디오카페
40-02스타벅스 라디오카페스타벅스 테마 라디오카페
40-03더불어민주당 라디오카페정당 라디오카페
40-04오세훈 서울시장 라디오카페서울시장 라디오카페
40-05장경동 목사 중문교회교회 라디오카페
40-06텍스트 2 비디오 생성텍스트 기반 영상 자동 생성
40-07PDF 슬라이드 편집기PDF 기반 슬라이드 제작 도구
40-08Ad Gen Engine광고 콘텐츠 자동 생성 엔진
40-09씽크드로우 AIAI 기반 드로잉/이미지 생성
40-10GEO-AIO 콘텐츠GEO-AIO 콘텐츠
40-11GEO-AIOGEO-AIO 메인 플랫폼
41Claude Code Manual이 매뉴얼 사이트 (현재 페이지)

50 — 비즈니스/스타트업

비즈니스 솔루션, 스타트업, 선거, 특허, 내비
번호폴더명설명
50-01스타트업파인더스타트업 검색/매칭 플랫폼
50-02Sales Spark영업 자동화 솔루션
50-03M&A BuySellM&A 매매 중개 플랫폼
50-04OPS & AI-BM운영 및 AI 비즈니스 모델
50-04ops-websiteOPS 웹사이트 (중복 번호)
50-05AI선거솔루션AI 기반 선거 캠페인 솔루션
50-06선거 리포트선거 분석 리포트 시스템
50-07BJBJ 프로젝트
50-07선거 차량 이동 최적화선거 유세 차량 경로 최적화
50-08시니어 1인 창업시니어 대상 1인 창업 가이드
50-09Patent_VibeCoding_Process바이브코딩 특허 프로세스
50-09특허-저작권 솔루션특허 및 저작권 관리 솔루션
50-10RQTDW AI트레이너AI 트레이닝 플랫폼
50-11택시기사용 빈차 운행 AI내비택시 빈차 운행 AI 내비게이션
50-12화이어 내비화이어 내비게이션

60 — 개인 클라이언트

개인 클라이언트 전용 프로젝트
번호폴더명설명
60-01선욱규 대표선욱규 대표 프로젝트
60-01-1AX-On 플랫폼AX-On 플랫폼 (선욱규 대표 하위)
60-02이병목 대표 (미소미)미소미 이병목 대표 프로젝트
60-03리젠메드컨설팅리젠메드 컨설팅
60-03이장춘이장춘 프로젝트 (중복 번호)
60-04장석화 대표 브레인트러스트브레인트러스트 장석화 대표
60-05케르비시아 브루잉 수제맥주수제맥주 브루어리
60-05-01케르비시아 홈페이지-사업전략 및 투자제안서케르비시아 사업전략/투자제안
60-05-02소셜허브터널 홈페이지Social Hub Tunnel Vision

기타 / 자료 / 임시

70~80번대, 자료 백업, 임시 폴더

70~80번대 (신규 카테고리)

번호폴더명설명
70-01공대생 할아버지, 미대생 할머니라이프스타일 / 콘텐츠 프로젝트
80-01AI여행 플랫폼AI 기반 여행 서비스 플랫폼

자료 백업 폴더

번호폴더명설명
자료01RQTDW AI트레이너RQTDW 백업 자료
자료02삼국지삼국지 프로젝트 자료
자료03특허-저작권특허/저작권 백업 자료
자료04.claudeClaude 설정 백업
자료05케르비시아 브루잉 수제맥주케르비시아 백업 자료
자료06선웅규 대표선웅규 대표 백업 자료
자료07OPS & AI-BMOPS 백업 자료
자료08소셜미디어 마케팅 자료소셜미디어 마케팅 자료 모음

기타/임시 폴더

폴더명설명
사이버장례 플랫폼사이버 장례 서비스 플랫폼
autorun자동 실행 스크립트
pages페이지 자산
!!OXz, !!xtHT, !$cMdO 등임시/시스템 생성 폴더 (정리 가능)
관리자비번

관리자 비밀번호 목록

각 플랫폼별 관리자 계정 정보를 정리하여 빠르게 확인합니다.

플랫폼명폴더번호시스템관리자 ID회원 ID비번캠프관리자 비번작업

새 비밀번호 추가

새 카테고리 추가

폴더 추가

하네스 엔지니어링

01. 시작 가이드: 이 책을 끝까지 읽는 법

처음부터 모든 용어를 외우려 하지 않아도 됩니다. 기술 개념을 일상 장면으로 바꿔 이해하는 것이 핵심입니다.

어려운 개념 → 생활 비유

용어생활 비유
LLM똑똑하지만 회사 규칙을 모르는 신입사원
하네스신입사원이 안정적으로 일할 수 있게 해주는 사무실·도구·규칙·검토 체계
컨텍스트 창지금 책상 위에 펼쳐 놓은 자료
장기 메모리서랍, 창고, 회의록, 단골 카페의 취향 기록
도구 호출직원이 전화, 검색, 계산기, 파일함을 사용하는 행동
Hook문을 열면 자동으로 켜지는 센서등
Eval운전면허 시험, 품질검사표
Sandbox아이가 모래놀이하는 안전한 울타리

목적별 추천 읽기 순서

목적추천 순서
AI 에이전트 처음 알고 싶다시작 가이드 → 용어 읽기법 → 제1~3장
바로 실습하고 싶다실습 준비 → 제1장 → 각 장 실습
회사에 AI 도입해야 한다머리말 → 제1장 → 제10장 → 제12장 → 제14장
실제 하네스를 써보고 싶다제2장 → 제4장 → 제6장 → 제7장
강의/워크숍 운영목차 → 실습 준비 → 제1장 → 제11~12장

핵심 명제

"모델이 실패했다고 말하기 전에, 모델이 일하는 환경이 제대로 설계되었는가를 먼저 묻는다."

출처: wikidocs.net/346093

하네스 엔지니어링

02. 목차

5부 구성으로 이해·구현·운영·설계·실습을 단계적으로 다룹니다.

구분범위핵심 질문
들어가기시작 가이드 ~ 실습 준비학습 방법 및 준비 절차
1부 기초제1~3장하네스의 정의와 기본 개념
2부 도구·구현제4~7장OpenAI, Claude, MCP 실무 활용
3부 평가·운영제8~10장장시간 작업·평가·안전 설계
4부 설계·사례제11~14장패턴·결정·메모리 소유권

독자별 추천 경로

하네스 엔지니어링

03. 책의 구성: 다섯 개의 길

"기술 백과처럼 넓게 다루지만, 처음 접하는 사람도 길을 잃지 않도록 다섯 개의 흐름으로 묶었다."

하네스 엔지니어링

04. 머리말

"이제 중요한 것은 '모델에게 무엇을 시킬 수 있는가'가 아니라 '모델이 일하는 환경을 어떻게 설계할 것인가'다"

시대 변화

시점AI의 역할
2023년질문 응답 챗봇
2025년 이후웹 검색, 파일 조작, 코드 수정, DB 조회, 브라우저 제어, 테스트 실행, 보고서 작성이 가능한 "도구 활용 작업자"

핵심 비유: 신입사원 아날로지

아무리 능력 있는 신입사원도 규정, 도구, 권한, 문서 위치, 보고 양식, 결재 절차, 품질 기준, 보안 규칙 없이는 제대로 일하지 못한다. "알아서 잘해"가 아닌 구체적 시스템이 필요하다.

주요 학습 목표

  1. AI 활용의 패러다임 변화 이해
  2. 실무에 필요한 통합 요소(지시+자료+도구+권한+검사 체계) 이해
  3. 책의 성격 인식: 기술 설명서가 아닌 환경 설계 안내서
하네스 엔지니어링

05. 이 책을 읽는 방법

세 가지 읽기 방식과 대상별 학습 수준 가이드

세 가지 읽기 방식

  1. 개념서처럼 읽기 — 비유와 설명으로 "AI 에이전트가 실수하는 이유" 이해
  2. 실무 매뉴얼처럼 읽기 — AGENTS.md, CLAUDE.md, progress.md 등 템플릿을 프로젝트에 직접 적용
  3. 강의 교재처럼 읽기 — 핵심 개념→비유→도표→실습→요약 구조로 진행

대상별 학습 수준 가이드

상황여기까지면 충분더 해보고 싶다면
일반 사용자각 장의 핵심 비유와 한 장 요약마지막 실습 질문을 일상에 대입
실습 중심harness-lab으로 청사진 작성청사진을 실행 하네스로 구현
실무 도입자권한, 검증, 기록, 사람 승인 지점 표시실제 업무 절차 연결
개발자파일 구조, Skill, Agent, 평가 흐름 적용테스트와 회귀 평가까지 반복 운영
강사/스터디 운영자비유, 도표, 실습 순서로 설명 가능부록 C 워크시트로 수강생 점검
하네스 엔지니어링

06. 처음 접하는 사람을 위한 용어 읽기법

낯선 용어를 만날 때마다 "이것이 회사, 주방, 병원에서는 무엇과 비슷할까?"라고 자문하세요.

용어일상 비유한 문장 의미
LLM기억이 제한된 신입사원말을 이해하고 생성하는 모델
프롬프트업무 지시서모델에게 무엇을 하라고 말하는 문장
컨텍스트 창책상 위 펼쳐진 자료모델이 한 번에 볼 수 있는 정보 공간
RAG사서가 필요한 책을 찾아 펼쳐 주는 방식답변 전 관련 문서를 검색해 컨텍스트에 넣는 방식
MCPAI용 멀티탭 / USB-C 포트여러 외부 도구를 표준 방식으로 연결하는 규격
Guardrail도로의 가드레일, 공항 보안검색대위험한 행동을 막거나 확인하는 안전 장치
Handoff고객센터에서 전문 부서로 넘기는 일한 에이전트가 다른 에이전트에게 작업을 넘기는 것
Hook문을 열면 켜지는 센서등특정 순간에 자동으로 실행되는 절차
Compaction긴 회의록을 요약본으로 줄이는 일오래된 대화를 압축해 컨텍스트를 아끼는 방식
Artifact작업 결과를 증명하는 영수증과 사진계획서, 스크린샷, 테스트 결과처럼 검토 가능한 산출물
하네스 엔지니어링

07. 실습 준비: harness-lab 설치와 사용법

harness-lab은 AI 하네스 설계를 단계적으로 실습할 수 있게 도와주는 도구입니다.

Windows 설치

# WSL 설치 (PowerShell 관리자 권한)
wsl --install

# Ubuntu 기본 도구
sudo apt update && sudo apt install -y git curl

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

# 단축 명령 등록 (.bashrc에 추가)
alias cc="claude --dangerously-skip-permissions"

harness-lab 내려받기

git clone https://github.com/jikime/harness-lab.git
cd harness-lab

# 개인용 스킬 설치
mkdir -p ~/.claude/skills
cp -R skills/harness-lab ~/.claude/skills/

청사진 vs 실행 하네스

단계무엇을 하나언제 쓰면 좋은가
청사진Agent, Skill, Orchestrator, Test, Evolution의 설계안개념 이해 및 실습 결과 검토 시
실행 하네스승인 후 실제 Agent와 Skill 구성 생성같은 일을 반복해서 실제로 수행할 때

초보자 오류 대응

오류 메시지원인해결
command not found: claudeClaude Code 미설치터미널 재시작 후 claude 실행
command not found: gitGit 미설치sudo apt install -y git
/harness-lab이 보이지 않음스킬 미설치ls ~/.claude/skills/harness-lab 확인
하네스 엔지니어링

08. 제1장. 하네스의 탄생

"원시 LLM은 운영체제 없는 CPU다" — 모델 자체가 아닌 실행 환경이 핵심입니다.

컴퓨터 구조로 보는 하네스

컴퓨터 구조LLM 에이전트설명
CPULLM, 모델 가중치계산 엔진, 혼자서는 일 미완성
RAM컨텍스트 창책상 위 자료, 공간 제한 있음
하드디스크벡터DB, 문서, 파일장기 저장소
장치 드라이버도구 통합, MCP, API외부 세계 접촉 통로
운영체제에이전트 하네스메모리·도구·권한·오류·검증 관리
애플리케이션에이전트 행동사용자가 경험하는 결과

AI 하네스 최소 구성요소 5가지

  1. 목표 문서 — 무엇을 해야 하는지, 무엇을 하지 말아야 하는지
  2. 컨텍스트 지도 — 필요한 문서와 데이터의 위치
  3. 도구 목록 — 사용 가능한 도구와 금지된 도구 구분
  4. 검증 방법 — 테스트나 체크리스트, 결과 확인 방식
  5. 기록 방식 — 수행 내용 문서화, 다음 세션으로의 기억 이전

메모리 유형

유형의미비유
Working Context지금 작업에 필요한 상태책상 위 펼쳐둔 자료
Semantic Knowledge의미 있는 지식과 개념자주 참고하는 업무 창고
Episodic Experience과거 경험과 사건이전 회의록과 업무 이력
Personalized Memory개인화된 기억단골 가게의 취향 기억
하네스 엔지니어링

09. 제2장. LLM 에이전트의 작동 원리

입력-판단-도구 사용-결과 읽기의 반복 루프가 에이전트의 핵심 작동 방식입니다.

7단계 Agent Loop

  1. 프롬프트 조립 — 시스템 지시, 도구 스키마, 메모리, 대화 기록, 사용자 요청 통합
  2. LLM 추론 — 최종 답변 / 도구 호출 / 다른 에이전트 handoff 중 결정
  3. 출력 분류 — 최종 답변 vs 도구 실행 요청 vs handoff 요청 구분
  4. 도구 실행 — 인자 검사, 권한 정책 확인, 샌드박스 실행
  5. 결과 패키징 — 도구 결과를 관찰 메시지로 변환
  6. 컨텍스트 업데이트 — 새 관찰, 파일 변경, 테스트 결과 반영
  7. 반복 또는 종료 — 최종 답변이면 종료, 조건에 따라 중단

ReAct vs Plan-and-Execute

방식특징사용 사례
ReAct즉석에서 한 단계씩, 유연함편의점 물 사기 같은 단순 작업
Plan-and-Execute전체 계획 먼저, 실행자에게 분담결혼식 준비 같은 복합 작업

하위 에이전트 오케스트레이션 3형태

형태설명주의점
Fork부모 컨텍스트 복사해 별도 작업결과 요약 필수
Teammate별도 터미널/세션에서 동료처럼 작업누가 뭘 했는지 기록 필요
Worktree격리된 브랜치/작업공간에서 수정merge 및 충돌 해결 정책 필요
하네스 엔지니어링

10. 제3장. 프롬프트와 컨텍스트 엔지니어링

세 가지 엔지니어링의 관계를 이해하면 하네스 설계의 전체 그림이 보입니다.

세 가지 엔지니어링의 관계

구분핵심 질문비유
프롬프트 엔지니어링어떻게 말할 것인가?업무 지시서 쓰기
컨텍스트 엔지니어링무엇을 보여 줄 것인가?책상 위 자료 정리
하네스 엔지니어링어떤 환경에서 일하게 할 것인가?사무실·도구·승인·검사 체계 만들기

AGENTS.md 기본 템플릿

## 프로젝트 목표
이 프로젝트는 고객 문의를 빠르고 정확하게 분류하는 AI 도우미를 만든다.

## 작업 전 읽을 문서
- docs/product.md
- docs/policy.md

## 반드시 지킬 규칙
- 문서에 없는 내용은 추측하지 않는다.
- 고객 개인정보를 답변에 노출하지 않는다.

## 완료 기준
- 결과 요약 작성, 불확실한 항목 표시

컨텍스트 압축 전략

전략설명비유
압축(compaction)오래된 대화를 요약해 공간 확보회의록 요약본 만들기
JIT 검색필요할 때만 grep/search로 읽음창고 전체가 아니라 필요한 상자만 꺼내기
구조화 메모progress.md, feature_list.json으로 정리인수인계 문서 작성

Lost in the Middle 현상: 중요 정보가 문서 중간에 있으면 성능 저하 → 중요 정보는 문서의 시작/끝에 배치하세요.

하네스 엔지니어링

11. 제4장. 도구 엔지니어링과 MCP

도구가 에이전트의 손과 발입니다. 많이 주는 것이 항상 좋은 것은 아닙니다.

위험도별 도구 분류

위험도도구 예시원칙
낮음파일 읽기, 문서 검색자동 허용 가능
중간파일 수정, 초안 작성작업 후 확인 필요
높음이메일 전송, 결제, 삭제, 배포사람 승인 필수

MCP 정의

AI 애플리케이션이 외부 도구와 데이터 소스에 연결하기 위한 표준. "AI용 USB-C 포트"처럼 Jira, Sentry, PostgreSQL, Figma, Slack, Gmail 등과 연결 가능.

도구 범위 설계 순서

  1. 이 업무에 반드시 필요한 도구를 적는다
  2. 읽기 도구와 쓰기 도구를 분리한다
  3. 위험한 도구는 승인 필요로 표시한다
  4. 비슷한 도구는 하나로 합치거나 이름을 명확히 한다
  5. 장시간 작업에서는 단계별로 도구를 동적으로 열어 준다
하네스 엔지니어링

12. 제5장. 평가 하네스와 신뢰성

AI 결과를 감으로 판단하지 않고 평가 케이스와 채점 기준으로 확인합니다.

3가지 검증 방식 비교

방식예시장점한계
규칙 기반테스트, 린터, 스키마 검사형식 오류 감지의미 품질 놓침
시각적·환경스크린샷, DB 상태 확인실제 상태 불일치 감지검증 도구 준비 필요
추론 기반LLM 평가자, 리뷰 에이전트어조, 논리, 의도 파악지연시간, 비용 증가

하네스 힐클라이밍 루프

운영 trace 수집
→ 실패 사례를 eval case로 변환
→ 실패 유형 태그: 도구선택 / 컨텍스트누락 / 권한 / 검증부족
→ 하네스 수정: 프롬프트, 도구 설명, 권한, 검증, 컨텍스트
→ 재평가
→ holdout case로 과적합 확인

핵심 원칙: Guides(사전 제어) + Sensors(사후 교정)을 함께 가져야 합니다.

하네스 엔지니어링

13. 제6장. OpenAI에서 하네스 구축하기

Responses API, Agents SDK, 도구, 평가, 추적, 권한까지 통합 설계합니다.

OpenAI 구성요소 대응표

OpenAI 구성요소하네스에서 하는 일
Responses API모든 요청이 처음 들어오는 접수 창구
Function calling캘린더, 메일, 예약 앱을 실제로 여는 행동
Handoff전문 담당자에게 넘기는 일
Guardrail결제·외부 발송·민감 정보 처리 전 확인 규칙
Tracing누가 어떤 도구를 썼고 어떤 결과가 나왔는지 남기는 업무 일지
Eval업무 정확성을 주기적으로 확인하는 점검표

Codex 하네스 부품 지도

구성요소비유하네스에서 하는 일
AGENTS.md매장 운영 수칙프로젝트 규칙·주의사항을 작업 전에 읽게 함
Skill반복 업무 레시피 카드자주 하는 작업 절차를 재사용 가능하게 묶음
Subagent조사 담당자독립적으로 처리할 일을 병렬로 맡기고 결과 회수
Worktree별도 작업대같은 프로젝트에서 여러 작업을 서로 방해하지 않고 진행
Hook자동으로 켜지는 센서등특정 시점에 검사·기록·승인·요약을 자동 실행
하네스 엔지니어링

14. 제7장. Claude에서 하네스 구축하기

Claude Code를 "프롬프트 도구"가 아닌 "작업 환경 설계"로 이해하는 것이 핵심입니다.

CLAUDE.md 6가지 기본 영역

영역포함 내용비유
대화 방식불필요한 인사말 제거, 불확실성 표시대화 예절
변경 통제큰 수정 전 확인, 요청 범위만 수정허락받고 진행
기억과 연속성MEMORY.md, 세션 요약, 실패 기록회의록과 실수 노트
개발 안전관련 파일만 수정, 파괴적 작업 확인공구함 사용 규칙
고위험 행동 차단배포, DB 변경, 외부 전송 제한현관 열쇠와 결제 카드

권한 설계

Read/Grep/Glob: allow
Edit/Write: ask
Bash: ask 또는 제한
삭제/배포: deny

.claude 폴더 구조

위치역할
CLAUDE.md프로젝트 설명, 명령, 원칙
.claude/skills/특정 작업의 Skill
.claude/agents/subagent 정의
.claude/settings.json권한, 승인 흐름
~/.claude/개인 선호와 습관
하네스 엔지니어링

15. 제8장. 장시간 실행 에이전트와 세션 인계

"모델이 기억한다" → "다음 모델도 읽을 수 있게 남긴다"

Handoff Artifact 필수 포함 항목

목표        - 현재 프로젝트 목표
완료된 일   - 검증된 완료 항목
진행 중인 일 - 미완료 항목
다음 행동   - 다음 세션 우선 과제
주의점      - 실패 접근법, 위험 파일, 미해결 질문

파일별 역할

파일역할
feature_list.json남은 작업을 구조화
progress.md시간순 작업 기록 설명
git history실제 변경 이력
test report검증된 항목 증거

세션 시작 플로우

pwd 확인 → progress.md 읽기 → git log 확인
→ feature_list.json에서 미완료 항목 선택
→ smoke test 실행
→ 한 기능 작업 → 테스트 및 상태 업데이트
→ commit + 진행 기록
하네스 엔지니어링

16. 제9장. Generator-Evaluator 하네스

만드는 에이전트와 평가하는 에이전트를 분리하면 품질이 안정적으로 높아집니다.

3-Agent Architecture

Sprint Contract 예시

# Sprint Contract
## 이번 범위
사용자 검색 입력 UI와 빈 결과 상태 구현

## 제외 범위
고급 필터, 엑셀 다운로드, 권한 관리

## 완료 기준
- 검색어 입력 시 API 호출
- 결과 없음 메시지 표시
- 로딩 상태 표시
- 관련 테스트 통과

반복 개선 루프

  1. Planner가 작은 목표를 정한다
  2. Generator가 만든다
  3. Evaluator가 검사한다
  4. 실패하면 구체적 피드백을 준다
  5. Generator가 수정한다
  6. 통과하면 다음 sprint로 간다
하네스 엔지니어링

17. 제10장. 안전, 거버넌스, 운영

"초심자는 '할 수 있는 일'이 아닌 '절대 하면 안 되는 일'부터 정의하세요."

권한 설계

행동정책
문서 읽기·요약허용
파일 수정확인 요청
이메일 초안허용
이메일 전송사람 승인
결제·환불·파일 삭제승인 또는 거부
배포승인

운영 지표

지표의미
성공률작업이 완료 기준을 통과한 비율
평균 비용작업당 토큰·도구 비용
재시도율한 번에 성공하지 못한 비율
사람 개입률승인 또는 수정이 필요한 비율
회귀율이전 고장이 재발한 비율

사람 개입이 필요한 행동

하네스 엔지니어링

18. 제11장. 에이전틱 하네스 12가지 실전 패턴

"좋은 에이전트는 더 똑똑한 모델이 아닌 더 잘 설계된 작업 환경에서 나온다."

#패턴일상 비유
1영구 지침 파일 — 핵심 규칙을 파일로 고정냉장고에 붙인 집안 규칙 메모
2범위별 문맥 조립 — 상황에 맞는 규칙만 선택백화점 전체 규칙이 아닌 구역별 규칙
3계층형 메모리 — 자주/가끔 쓰는 정보를 층으로 분리책상 → 서랍 → 창고
4메모리 정리 — 주기적으로 중복·모순 제거계절마다 옷장 정리
5점진적 문맥 압축 — 오래된 것부터 단계적으로 요약최근 논의는 자세히, 오래된 것은 결론만
6탐색-계획-실행 루프 — 살펴본 후 계획 세우고 마지막에 실행숙련된 수리 기사는 먼저 상태를 확인
7문맥 격리 하위 에이전트 — 다양한 업무를 별도 에이전트로 분리회계·법무·디자인·개발 각 팀 담당
8포크-조인 병렬성 — 독립 작업을 동시 실행 후 병합가족이 각자 방 하나씩 청소
9점진적 도구 확장 — 기본 세트로 시작해 필요 시 추가초보 운전자에게 한 번에 모든 키를 주지 않기
10명령 위험 분류 — 자동허용·확인요청·자동차단으로 분류공항 보안 검사대의 기준
11단일 목적 도구 설계 — 전용 도구로 분리스위스 아미 나이프가 아닌 목적별 도구
12결정론적 수명 주기 훅 — 반드시 일어나야 하는 절차를 자동 실행세탁기가 자동으로 헹굼→탈수 실행

핵심 원칙: "매번 일어나야 하는 일은 지침이 아니라 훅에 있어야 한다."

하네스 엔지니어링

19. 제12장. 하네스 설계의 7가지 결정과 3가지 역발상

"개발할 때 기분 좋은 선택과 운영에서 살아남는 선택은 자주 다르다."

7가지 설계 결정

결정한쪽 선택반대쪽 선택
에이전트 수단일 에이전트멀티 에이전트
추론 전략ReAct계획 후 실행
컨텍스트 전략강한 압축풍부한 컨텍스트
검증 방식계산적 검증추론적 검증
권한 설계허용적제한적
도구 범위전체 상시 노출단계별 최소 도구
하네스 두께얇은 하네스두꺼운 하네스

역발상 — Vercel d0 실증 데이터

지표기존개선 후
평균 실행 시간274.8초77.4초 (3.5배 빠름)
성공률80%100%
토큰 사용량약 102k약 61k (37% 감소)
평균 단계 수약 12단계약 7단계 (42% 감소)

"도구를 줄인 것이 아니라, 작업 환경을 읽기 좋게 만든 것이다."

하네스 엔지니어링

20. 제13장. 아키텍처에서 에이전트-퍼스트 엔지니어링까지

"모델은 생각하는 엔진이다. 하네스는 그 엔진이 무엇을 보고, 무엇을 만지고, 어디서 멈추고, 어떻게 다시 시작하는지를 결정한다."

하네스 관점의 질문 전환

초보자용 최소 하네스

  1. progress.md — 매 세션 시작/종료 때 업데이트
  2. feature_list.json — 검증 가능한 완료 기준
  3. git commit — 깨끗한 상태로 커밋
  4. 테스트/린터/브라우저 검증

환경 감사 체크리스트

하네스 엔지니어링

21. 제14장. 하네스와 메모리 소유권

"기억을 소유하지 못하면 에이전트를 소유하기 어렵다."

네 가지 메모리 소유권 모델

  1. 내가 소유한 하네스 — 프롬프트, 도구, 단기/장기 메모리 모두 자체 관리. 구현 부담 크지만 이식성 높음
  2. 상태형 제공자 API — 장기 메모리는 자체 관리, 단기 스레드/압축은 제공자 내부
  3. 폐쇄형/블랙박스 하네스 — 메모리 형태, 요약 방식, 출처 불분명
  4. 관리형 하네스와 메모리 — 도구 실행부터 메모리까지 전부 제공자 인프라

메모리 스키마 예시

{
  "memory_id": "mem_001",
  "scope": "user|project|organization",
  "type": "preference|decision|constraint|lesson|summary",
  "content": "사용자는 보고서 첫머리에 3줄 요약을 선호한다.",
  "source": "session_2026_04_26",
  "confidence": 0.82,
  "created_at": "2026-04-26T10:00:00Z"
}

폐쇄형 하네스 점검 질문

점검 질문좋은 신호위험 신호
메모리는 어디에 저장되는가내 DB, 파일, 스토리지제공자 내부 상태만
다른 모델로 옮길 수 있는가모델 독립적 API 또는 파일 내보내기특정 모델/스레드에 종속
삭제와 수정이 가능한가사용자별 삭제, redaction삭제 정책 불분명
하네스 엔지니어링

22. 맺음말: 하네스는 AI 시대의 업무 운영체제다

"AI를 잘 쓰는 사람은 질문을 잘 쓰는 사람에서, AI가 일하는 환경을 잘 설계하는 사람으로 바뀌고 있다."

5가지 핵심 요약

  1. AI 시대의 역량은 모델에게 좋은 문장을 쓰는 것 → 모델이 일할 환경을 설계하는 것으로 이동
  2. 하네스는 모델·도구·메모리·권한·검증·기록·안전장치를 묶어 실제 업무가 가능하게 만든다
  3. 잘 설계된 하네스는 AI를 가두는 장치가 아니라 AI가 더 안전하고 오래 일할 수 있게 해주는 업무 운영체제
  4. 초보자는 지시 파일·작은 도구·테스트·진행 기록부터 시작하면 된다
  5. 앞으로의 경쟁력은 "어떤 모델을 쓰는가"뿐 아니라 "그 모델에게 어떤 하네스를 제공하는가"에서 나온다

하네스의 구성

프롬프트(시작) + 컨텍스트(작업대) + 도구(손과 발) + 평가(눈) + 권한(안전벨트) + 로그(기억) + 구조(이 모든 것을 연결하는 하네스)

하네스 엔지니어링

23. 부록 A. 하네스 엔지니어링 핵심 용어집

읽다가 막혔을 때 다시 책상으로 돌아오게 해주는 지도. 각 용어마다 일상 비유 / 쉬운 설명 / 초보자 주의점 3가지를 제공합니다.

주요 카테고리

핵심 용어 빠른 참조

용어비유초보자 주의점
Model엔진모델만 바꾸면 문제가 해결된다고 생각하지 않는다
Harness업무 운영체제모델이 아니라 환경을 먼저 점검한다
Subagent전문 담당자Fire-and-forget이라 공유 상태 없음을 주의
Hook센서등지침이 아니라 시스템으로 연결해야 반드시 실행됨
Eval품질검사표감이 아니라 케이스와 기준으로 측정한다
하네스 엔지니어링

24. 부록 B. 참고문헌과 출처 지도

이 책이 참조한 공식 문서, 논문, 보안 프레임워크 목록입니다.

공식 문서

8개 핵심 논문

  1. ReAct: Synergizing Reasoning and Acting (Yao et al., 2022)
  2. Toolformer: Language Models Teaching Themselves to Use Tools (Schick et al., 2023)
  3. Reflexion: Verbal Reinforcement Learning (Shinn et al., 2023)
  4. Self-Refine: Iterative Refinement with Self-Feedback (Madaan et al., 2023)
  5. SWE-bench: Real-World GitHub Issues Resolution (Jimenez et al., 2023)
  6. SWE-agent: Agent-Computer Interfaces (Yang et al., 2024)
  7. AgentBench: Evaluating LLMs as Agents (Liu et al., 2023)
  8. Lost in the Middle: How Language Models Use Long Contexts (Liu et al., 2023)

보안·거버넌스

하네스 엔지니어링

25. 부록 C. 함께 따라하는 하네스 실습 워크시트

자신의 업무를 하네스 관점으로 진단하고 소규모 하네스 v0.1을 설계합니다.

10개 하네스 계층 자가진단 (0~3점)

계층평가 항목
목표결과 명확성
지시원칙과 금지사항
컨텍스트자료 정리
메모리작업 연속성
도구사용 가능성
워크플로우이해→계획→실행→확인 흐름
검증확인 기준
가드레일금지 행동 정의
로그·관찰추적 가능성
사람 승인개입 지점

최종 선언 문장

"나는 내 AI 업무에서 먼저 ___ 계층을 보강하고, ___을/를 모델 밖으로 꺼내 구조화하겠다."

하네스 엔지니어링

26. 부록 D. AI의 기억을 설계하는 법

AI가 "기억한다"는 것은 실제로 하네스가 기록을 남기고 다시 꺼내 보여주는 운영 방식입니다.

저장하면 좋은 기억 vs 저장하지 않는 기억

저장하면 좋은 기억저장하지 않는 편이 좋은 기억
반복되는 사용자 선호오늘 한 번만 필요한 임시 요청
계속 지켜야 하는 규칙이미 문서에 명확히 적힌 일반 정보
과거에 실패했던 접근과 이유확인되지 않은 추측
보고 형식, 승인 절차, 금지 표현곧 바뀔 가능성이 큰 일시적 선택
다시 설명하면 시간이 드는 업무 방식불필요하게 민감한 개인정보

8가지 핵심 원칙

  1. 기억의 위치: 모델의 머릿속이 아니라 하네스가 운영하는 기록장
  2. 저장 원칙: 모든 것을 저장하면 중요한 것을 놓침
  3. 접근 방식: 목차를 먼저 보고 필요한 페이지만 펼쳐야 함
  4. 검증 방식: 오래된 기억은 포스트잇처럼 다시 확인해야 함
  5. 이전 방식: 파일 복사가 아니라 사용 규칙 이전
  6. 범위 분류: 개인, 프로젝트, 조직, 임시 기억 구분 보관
  7. 초기 설정: 사용자가 승인한 소개서로 시작
  8. 보안 관리: 오래 남는 기억일수록 삭제·수정 이력 중요
하네스 엔지니어링

27. 부록 E. Subagent와 Agent Teams를 구분하는 법

언제 혼자 보낼 것인가 vs 팀을 꾸릴 것인가를 결정하는 기준입니다.

핵심 차이

구분SubagentAgent Teams
기본 성격Fire-and-forgetCollaborative
작업 방식맡긴 일 끝내고 보고상태 공유하며 조율
에이전트 간 대화없음있음
공유 메모리없음공유 작업 목록·상태 있음
지속 상태거의 없음시간에 따라 문맥 축적

5가지 오케스트레이션 패턴

패턴의미사용 시기
프롬프트 체이닝앞 단계 결과를 다음 단계 입력으로순차적 의존 작업
라우팅요청에 따라 전문가로 발송난이도 분류·전문 담당 선택
병렬화독립 작업을 동시 실행여러 조사·후보 생성
오케스트레이터-워커중앙 에이전트가 일 분배·결과 종합Subagent & Teams 모두에서 활용
평가자-개선자하나가 생성, 다른 하나가 평가해 반환품질이 중요하고 한 번에 끝내기 어려울 때

멀티에이전트를 쓰지 말아야 할 때

하네스 엔지니어링

28. 부록 F. 최종 종합 보고서

하네스 엔지니어링의 역사·실증 데이터·미래 로드맵을 종합합니다.

Agent = Model + Harness

모델은 점점 범용화되고, 하네스가 차이를 만든다.

3단 진화 계보

Prompt Engineering  (2022~2024): "모델에게 뭘 말할까?"
Context Engineering (2025):      "모델이 뭘 보게 할까?"
Harness Engineering (2026~):     "모델을 둘러싼 실행 환경을 어떻게 설계할까?"

글로벌 타임라인

시점사건
2025.01Andrej Karpathy의 "Vibe Coding" 표현 등장
2026.02.05Mitchell Hashimoto, 하네스 관점 제시
2026.02OpenAI, 「Harness engineering」 공식 발행
2026.04AWS, Red Hat, Anthropic 등 주요 기업 공식 가이드 발행

실증 데이터

AI 성숙도 레벨

레벨명칭역량
L0도구 사용자AI 챗봇, 기본 프롬프트
L1컨텍스트 설계자AGENTS.md 작성, 업무 규칙 명문화
L2하네스 구축자훅 작성, 피드백 루프 구현
L3하네스 엔지니어Eval 체계, 멀티에이전트, CI 통합
L4하네스 아키텍트조직 표준화, Self-Harness 설계

핵심 인사이트

"바이브코딩이 AI와 같이 논다면, 하네스 엔지니어링은 AI가 제대로 일하도록 판을 짠다."
"2025년은 AI가 코드를 쓰는 해였다. 2026년은 인간이 AI가 일할 환경을 설계하는 해다."
"교육의 최소 단위는 '실수 1개 → 하네스 업데이트 1회'다. 이 사이클을 10번 경험하면 하네스 엔지니어가 된다."

출처: wikidocs.net/347327

📚 스킬 강의

Claude Code CLI — 스킬(Skill) 만들기 완전 정복

스킬의 개념부터 제작, 품질 관리까지 완벽 가이드 · skill-creator로 표준화된 스킬 개발

📖 강의안 다운로드

완전한 강의안 MD 파일 다운로드

⚡ 빠른 시작

Claude Code에서 바로 스킬 활용

📌 주요 목차

  • 1. 스킬이란 무엇인가 — 정의와 작동 원리
  • 2. 스킬이 왜 필요한가 — 문제 상황 vs 해결책
  • 3. 폴더 구조와 파일 역할 — SKILL.md, scripts, references, assets
  • 4. 개인 공용 vs 프로젝트 전용 — 설치 위치와 공유 방법
  • 5. 실습: 프롬프트만으로 스킬 만들기 — 6단계 Step-by-Step
  • 6. 문제점: 프롬프트만으로 만들면 — 중구난방이 되는 5가지
  • 7. skill-creator — 품질 관리의 답 — 표준화된 스킬 제작
  • 8. skill-creator 실전 사용법 — 7단계 완성 프로세스
  • 9. 전체 흐름 요약 — 방법 A vs 방법 B 선택 가이드

🎯 학습 시간

초급 (개념만)

15분

중급 (실습)

1시간

고급 (skill-creator)

2시간

💡 핵심 개념

용어설명
SKILL.md스킬의 심장 · 필수 파일 · 이것만 있어도 작동
description트리거 키워드 · 사용자 자연어 매칭 담당
scripts/실행 코드 분리 · 스킬 일관성 보장
~/.claude/skills/개인 공용 스킬 · 모든 프로젝트에서 사용 가능
.claude/skills/프로젝트 전용 스킬 · Git으로 팀 공유 가능
skill-creator메타 스킬 · 스킬 제작 표준화 · 품질 보장

🚀 다음 스텝

  1. 강의안 다운로드 — 위의 "다운로드 (.md)" 버튼으로 전체 강의안 확보
  2. Claude Code 실행 — 터미널에서 claude 명령 입력
  3. 스킬 기획 — 만들고 싶은 스킬의 목적, 트리거 키워드, 출력 형식 정리
  4. 방법 선택 — 간단하면 방법 A(프롬프트), 중요하면 방법 B(skill-creator)
  5. 반복 개선 — 테스트 → 피드백 → 수정 → description 최적화
  6. 팀 공유 — Git에 커밋 또는 .skill 파일로 패키징

📢 강의안 정보

버전: v1.0
작성: Claude Code 공식 문서 기반
파일: skills/Claude_Code_Skills_강의안.md
스킬: ~/.claude/skills/claude-code-skills-lecture/
트리거: "스킬 강의", "스킬 만드는 법", "skill 튜토리얼" 등