AI 스터디 실습 자료

Claude Code 실습 가이드

스크린캡처와 자연어로
실제 프로젝트를 만들고 수정하는 실습 과정입니다.

전체 소요 시간: 약 2~3시간

목차

📚 1주차 — 로컬 환경 + 대시보드 + Apify

로컬 개발 환경 셋업 → 공구 대시보드 → 인스타 컨텐츠 Apify 연동 순으로 진행합니다.

0

사전 준비 — 환경 세팅

본인의 운영체제에 맞는 탭을 선택하여 환경을 세팅하세요.

📋 실습 전 꼭 준비해 주세요
  • 가능하면 Mac PC — 실습 가이드와 단축키가 Mac 기준으로 작성되어 있어, Mac을 권장합니다. (Windows도 가능하지만 일부 명령어/단축키가 다릅니다.)
  • Claude Pro 플랜 이상 구독 — Claude Code는 무료 플랜으로 사용할 수 없습니다. Claude Pro($20/월) 이상 구독 또는 Anthropic API 키가 필요합니다.
※ Pro 구독은 월 단위 결제이며 언제든 해지 가능합니다. 스터디 기간에만 사용하셔도 됩니다.
🍎 Mac
🪟 Windows

📦 Mac 필수 설치

Step 1 — 터미널 열기

Cmd + Space로 Spotlight를 열고 터미널을 검색하여 실행합니다.
또는 Finder → 응용 프로그램 → 유틸리티 → 터미널을 실행합니다.

Step 2 — Git 확인 + (필요 시) 설치
💡 왜 필요해요? Git 은 "코드 우체부 + 백업 + 타임머신" 입니다. GitHub(인터넷 코드 보관소) 에 있는 이 실습 프로젝트를 내 컴퓨터로 받아오고(clone), 내가 수정한 내용을 다시 GitHub 에 올리는(push) 데 씁니다. 또 "어제 코드로 되돌리기" 같은 변경 이력 관리도 git 이 해줍니다.
(옵션 gh = GitHub CLI: 터미널에서 PR 만들기·이슈 보기 등 더 편한 작업용)

먼저 이미 깔려 있는지 확인부터 합니다.

# Git 설치 여부 확인 (필수)
git --version

# GitHub CLI 설치 여부 확인 (선택)
gh --version

✅ git 이 버전을 출력하면 OK — 예: git version 2.43.0 → 이 단계 건너뛰세요.
❌ "command not found" 가 나오면 설치 필요 → 아래로 진행.

설치 방법 (Mac 에서는 두 가지 중 하나)

방법 A. Xcode Command Line Tools 로 한꺼번에 (권장) — git 포함 기본 개발 도구가 다 깔립니다.

xcode-select --install

팝업 → "설치" 클릭 → 수 분~10분 대기. 완료 후 git --version 으로 재확인.

방법 B. Homebrew 로 git 만 설치 — 이미 Homebrew 가 있고 더 최신 git 을 원하면.

brew install git

(선택) GitHub CLI 설치 — 터미널에서 PR 만들기·이슈 확인 등에 유용. 이번 실습은 없어도 OK.

brew install gh

설치 후 gh auth login 으로 GitHub 계정 연결 (Step 7 에서 자세히 다룸).

⚠️ brew: command not found 가 나오면? Homebrew 자체가 아직 안 깔린 상태입니다. ↓ Homebrew 설치 안내로 이동 하여 먼저 Homebrew 를 설치한 뒤 위 명령을 다시 실행하세요.
Step 3 — Node.js 설치
💡 왜 필요해요? Node.js 는 다른 도구들이 그 위에 깔려서 돌아가는 "바탕" 이에요. 이번 실습의 거의 모든 도구(로컬 서버 · Claude Code · 패키지들)가 Node.js 위에서 돕니다. Node.js 가 없으면 그 위 도구들은 시작도 못 해요.

📱 휴대폰에 비유하면: iOS · Android 같은 운영체제 가 있어야 카카오톡 · 인스타 같은 앱이 깔리고 돌아갑니다. Node.js 가 우리 실습 도구들의 그 "운영체제" 역할이에요.

먼저 이미 깔려 있는지 확인부터.

# Node.js 가 이미 깔려 있는지 확인
node --version
npm --version

✅ 버전이 나오면 OK — 예: v22.14.0 → 이 단계 건너뛰세요.
❌ "command not found" 가 나오면 설치 필요 → 아래 두 방법 중 하나로 설치.

방법 A. 공식 사이트에서 받아 클릭 설치 (가장 쉬움)

  1. nodejs.org 접속 → LTS 버전 다운로드
  2. 받은 .pkg 파일 더블클릭 → "다음" 누르며 진행
  3. 설치 끝나면 터미널 다시 열고 node --version 으로 확인

방법 B. Homebrew 로 설치 (터미널 명령 한 줄)

brew install node

설치 후 node --version · npm --version 으로 확인.

⚠️ brew: command not found 가 나오면? Homebrew 자체가 아직 안 깔린 상태입니다. ↓ Homebrew 설치 안내로 이동 하여 먼저 Homebrew 를 깔고 다시 brew install node 를 실행하세요. 그게 귀찮으면 위 방법 A 로 진행해도 됩니다.
📦 Homebrew 설치 (Mac 의 패키지 관리자) — brew 명령이 안 될 때 먼저 깔아야 하는 도구.
# Homebrew 설치 (공식)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 설치 후 (Apple Silicon M1/M2/M3) — Homebrew 를 PATH 에 추가
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# 설치 확인
brew --version

Homebrew = Mac 에서 명령어 한 줄로 다양한 개발 도구를 깔게 해주는 "앱 스토어" 같은 도구. 한 번 깔아두면 두고두고 씁니다.

Step 4 — Claude Code 설치
💡 왜 필요해요? 이번 실습의 주인공. AI(Claude) 가 내 컴퓨터에서 직접 코드를 읽고 · 쓰고 · 실행할 수 있게 해주는 터미널 도구예요. "이 화면에 카드 하나 추가해줘", "왜 이게 안 돼?" 같은 말을 그냥 한국어로 입력하면 Claude 가 알아서 코드를 만들고 고치고 실행합니다. 본인이 코딩을 직접 안 해도 결과물이 나옵니다.

터미널에서 Claude Code CLI를 설치합니다.

npm install -g @anthropic-ai/claude-code
참고: Claude Code를 사용하려면 Anthropic 계정 또는 API 키가 필요합니다.
Step 5 — 권한 확인 생략 설정 (원커맨드)

실습 중 매번 권한 확인 팝업이 뜨지 않도록, 아래 명령어 하나로 alias를 등록합니다.

echo "alias claude='claude --dangerously-skip-permissions'" >> ~/.zshrc && source ~/.zshrc

설정 완료 후 claude를 실행하면 자동으로 권한 확인 없이 동작합니다.

주의: 이 옵션은 Claude가 파일 수정·명령어 실행 등을 확인 없이 진행합니다. 스터디 실습용으로만 사용하고, 중요한 프로젝트에서는 alias를 해제하세요.
해제: unalias claude 또는 ~/.zshrc에서 해당 줄을 삭제합니다.
Step 6 — 터미널 2개 준비

실습에서는 터미널 창 2개를 사용합니다. 하나는 로컬 서버용, 다른 하나는 Claude Code용입니다.

# Mac 터미널 새 창 열기
Cmd + N (기본 터미널 앱에서)
터미널 앱: Mac 기본 터미널, iTerm2, Warp 등 어떤 터미널이든 괜찮습니다. 창 2개만 열어두세요.
Step 7 — 프로젝트 다운로드 + 개인 레포 연결

Claude Code에게 자연어로 요청하면 됩니다. 터미널에서 Claude Code를 먼저 실행하세요.

claude

Claude Code가 실행되면 아래처럼 말하세요:

github.com/kimkh10/influencer 레포를 클론하고,
내 GitHub 아이디는 본인아이디야.
내 개인 레포로 remote를 변경하고 push까지 해줘.
⚠️ 본인아이디 자리에 본인의 GitHub 계정 아이디를 그대로 입력하세요.
예: 본인 GitHub 주소가 github.com/jane-pharm 이라면 위 명령에서 본인아이디 를 jane-pharm 으로 바꿔서 말하세요.

아직 GitHub 계정이 없다면 (가입 방법):
  1. github.com/signup 접속
  2. 이메일 입력 → 비밀번호 → 사용자명(이게 본인의 GitHub 아이디) 입력
  3. 이메일 인증 코드 입력 후 가입 완료
  4. 로그인하면 우측 상단 프로필 사진 옆 또는 본인 프로필 URL github.com/아이디 에서 아이디 확인 가능
  5. 본인 GitHub 에 influencer 라는 이름의 빈 레포를 미리 만들어 두세요. (Step 7 명령이 이 레포로 push 함)
    • 로그인 후 우상단 + → New repository
    • Repository name 에 influencer 입력
    • Public/Private 선택 (개인 학습용이면 Private 권장)
    • README · .gitignore · license 체크박스는 모두 비워둔 채로 생성 (빈 레포여야 push 가능)

완료되면 Claude Code를 종료하고, 클론된 폴더 안에서 다시 실행합니다:

# Claude Code 종료
/exit

# 프로젝트 폴더로 이동 후 다시 실행
cd influencer
claude
왜 다시 실행하나요? Claude Code는 실행된 디렉토리의 .claude/commands/에서 슬래시 명령어를 읽습니다. 상위 디렉토리에서 실행하면 /공구캘린더, /공구대시보드 등의 스킬이 보이지 않습니다.

왜 개인 레포로 옮기나요? 원본 레포는 읽기 전용입니다. 개인 레포로 연결해야 실습 중 수정한 코드를 push하고 배포할 수 있습니다.

사전 준비: 본인 GitHub에 influencer라는 이름의 빈 레포를 미리 만들어 두세요.
Step 8 — Wrangler 설치
💡 왜 필요해요? Wrangler 는 이 실습 사이트가 운영되고 있는 Cloudflare 의 공식 도구 입니다. 내 컴퓨터에서 실제 서비스와 똑같은 환경(로컬 서버)을 띄워주고, 작업 끝나면 "실제 인터넷에 배포" 하는 일도 같은 도구가 해줍니다. 한마디로 "내 컴퓨터 ↔ 실제 인터넷 서비스" 를 연결해주는 다리 라고 보면 됩니다.

먼저 프로젝트 의존성을 설치한 다음, Cloudflare의 Wrangler CLI 를 설치합니다.

npm install
# package.json 의 devDependencies (wrangler 포함) 설치

npm install -g wrangler # (선택) 글로벌 설치 — npx 없이 wrangler 직접 사용 가능
Wrangler란? Cloudflare Pages/Workers 로컬 개발 및 배포 도구입니다. npx serve .와 달리 CORS 프록시(functions/api/)까지 로컬에서 실행해줍니다.
Step 9 — cmux 설치 (선택, Claude 세션 multiplexer)

여러 Claude Code 세션을 한 화면에서 동시에 관리할 수 있는 도구입니다. 한 세션은 코딩, 다른 세션은 디버깅·문서 작성 식으로 병렬 작업할 때 유용합니다.

# 공식 GitHub: https://github.com/anthropics/cmux (또는 사용 중인 cmux 배포처)
# 권장: 공식 README 의 최신 설치 명령을 그대로 사용

# Homebrew 예시
brew install cmux

# 또는 npm 글로벌 설치 (패키지명은 공식 안내 참고)
npm install -g cmux
꼭 필요한가요? 없어도 실습에는 지장 없습니다. 동시에 2~3개 작업을 굴리기 시작하면 그때 설치해도 OK. 처음 학습 단계라면 일반 터미널 2개로 충분합니다.
Step 10 — 터미널 2개로 서버 + Claude Code 동시 실행

터미널 창을 2개 열어 각각 서버와 Claude Code를 실행합니다.

터미널 1 — 로컬 서버

cd influencer
npx wrangler pages dev .

서버가 실행되면 http://localhost:8788 주소가 표시됩니다.

터미널 2 — Claude Code (새 터미널 창)

cd influencer
claude

서버는 그대로 두고, 새 터미널 창(Cmd + N)에서 Claude Code를 실행합니다.

브라우저에서 http://localhost:8788 접속하여 대시보드를 확인합니다.

핵심: 터미널 1(서버)은 계속 켜둔 상태로, 터미널 2(Claude Code)에서 코드를 수정하면 브라우저를 새로고침하여 결과를 확인합니다.

실행하면 아래와 같은 화면이 됩니다:

터미널 1 — 로컬 서버
$ npx wrangler pages dev .

Ready on http://localhost:8788

[mf:inf] Worker reloaded!
[mf:inf] Listening on :8788
터미널 2 — Claude Code
$ claude

╭──────────────────────────╮
│ Claude Code │
│ /influencer │
╰──────────────────────────╯

>
Step 11 — (선택) 상태바(Statusline) 설정

Claude Code 하단에 시간 · 모델명 · 컨텍스트 사용률 · 5시간/주간 사용 한도를 한 줄로 보여주는 상태바를 추가합니다. 작업 중 한도를 미리 확인할 수 있어 유용합니다.

설정 방법 (가장 쉬운 방식)

아래 예시 이미지를 스크린캡처한 뒤 Claude Code에 붙여넣고 이렇게만 입력하세요:

이렇게 나오게 설정해줘

Claude가 알아서 ~/.claude/statusline.sh 스크립트와 ~/.claude/settings.json 설정을 만들어 줍니다.

참고 이미지 — 이 모양 그대로 따라하면 됩니다:

Statusline 예시
08:59  Opus 4.7 (1M context)[1M]  ai-project/influencer  main  ctx:60%  5h:4%(~4h0m)  wk:10%(~1d18h)
표시 항목: 시간 · 모델명 · 컨텍스트 윈도우 · 작업 디렉토리 · git 브랜치 · 컨텍스트 사용률(ctx) · 5시간 한도(5h) · 주간 한도(wk)
※ 5h/wk는 Claude.ai 구독자에 한해 첫 API 응답 후부터 표시됩니다.

📦 Windows 필수 설치

Step 1 — 터미널 열기

Win + R → cmd 입력 → Enter로 명령 프롬프트를 실행합니다.
또는 시작 메뉴에서 Windows Terminal 또는 PowerShell을 검색하여 실행합니다.

권장: Windows Terminal을 Microsoft Store에서 설치하면 더 편리합니다.
Step 2 — Git 설치

git-scm.com에서 다운로드하여 설치합니다.

# 설치 후 터미널을 다시 열고 확인
git --version
설치 옵션: 설치 중 "Use Git from the Windows Command Prompt" 옵션을 선택하세요. 나머지는 기본값 그대로 진행합니다.
Step 3 — Node.js 설치
💡 왜 필요해요? Node.js 는 자바스크립트로 만든 도구들이 내 컴퓨터에서 돌아가게 해주는 "엔진" 입니다. 이번 실습에서 쓸 거의 모든 도구 — 로컬 서버(wrangler), Claude Code, npm 으로 깔 다른 패키지들 — 이 전부 Node.js 위에서 돕니다. Node.js 가 없으면 그 위에 있는 도구들도 깔리지도, 돌아가지도 않아요. 자동차의 엔진이라고 보면 됩니다.

nodejs.org에서 LTS 버전을 다운로드하여 설치합니다.

# 설치 후 터미널을 다시 열고 확인
node --version
npm --version
주의: 설치 후 반드시 터미널을 닫고 다시 열어야 node, npm 명령어가 인식됩니다.
Step 4 — Claude Code 설치
💡 왜 필요해요? 이번 실습의 주인공. AI(Claude) 가 내 컴퓨터에서 직접 코드를 읽고 · 쓰고 · 실행할 수 있게 해주는 터미널 도구예요. "이 화면에 카드 하나 추가해줘", "왜 이게 안 돼?" 같은 말을 그냥 한국어로 입력하면 Claude 가 알아서 코드를 만들고 고치고 실행합니다. 본인이 코딩을 직접 안 해도 결과물이 나옵니다.

터미널에서 Claude Code CLI를 설치합니다.

npm install -g @anthropic-ai/claude-code
참고: Claude Code를 사용하려면 Anthropic 계정 또는 API 키가 필요합니다.
Step 5 — 권한 확인 생략 설정 (원커맨드)

실습 중 매번 권한 확인 팝업이 뜨지 않도록, 아래 명령어 하나로 설정을 등록합니다.

if(!(Test-Path $PROFILE)){New-Item $PROFILE -Force|Out-Null}; Add-Content $PROFILE "function claude { & claude.ps1 --dangerously-skip-permissions @args }"

설정 후 터미널을 닫고 다시 열면 claude 실행 시 자동으로 권한 확인 없이 동작합니다.

주의: 이 옵션은 Claude가 파일 수정·명령어 실행 등을 확인 없이 진행합니다. 스터디 실습용으로만 사용하고, 중요한 프로젝트에서는 해제하세요.
해제: notepad $PROFILE로 열어 해당 줄을 삭제합니다.
Step 6 — 프로젝트 다운로드 + 개인 레포 연결

Claude Code에게 자연어로 요청하면 됩니다. 터미널에서 Claude Code를 먼저 실행하세요.

claude

Claude Code가 실행되면 아래처럼 말하세요:

github.com/kimkh10/influencer 레포를 클론하고,
내 GitHub 아이디는 본인아이디야.
내 개인 레포로 remote를 변경하고 push까지 해줘.
⚠️ 본인아이디 자리에 본인의 GitHub 계정 아이디를 그대로 입력하세요.
예: 본인 GitHub 주소가 github.com/jane-pharm 이라면 위 명령에서 본인아이디 를 jane-pharm 으로 바꿔서 말하세요.

아직 GitHub 계정이 없다면 (가입 방법):
  1. github.com/signup 접속
  2. 이메일 입력 → 비밀번호 → 사용자명(이게 본인의 GitHub 아이디) 입력
  3. 이메일 인증 코드 입력 후 가입 완료
  4. 로그인하면 우측 상단 프로필 사진 옆 또는 본인 프로필 URL github.com/아이디 에서 아이디 확인 가능
  5. 본인 GitHub 에 influencer 라는 이름의 빈 레포를 미리 만들어 두세요. (Step 7 명령이 이 레포로 push 함)
    • 로그인 후 우상단 + → New repository
    • Repository name 에 influencer 입력
    • Public/Private 선택 (개인 학습용이면 Private 권장)
    • README · .gitignore · license 체크박스는 모두 비워둔 채로 생성 (빈 레포여야 push 가능)

완료되면 Claude Code를 종료하고, 클론된 폴더 안에서 다시 실행합니다:

# Claude Code 종료
/exit

# 프로젝트 폴더로 이동 후 다시 실행
cd influencer
claude
왜 다시 실행하나요? Claude Code는 실행된 디렉토리의 .claude/commands/에서 슬래시 명령어를 읽습니다. 상위 디렉토리에서 실행하면 /공구캘린더, /공구대시보드 등의 스킬이 보이지 않습니다.

왜 개인 레포로 옮기나요? 원본 레포는 읽기 전용입니다. 개인 레포로 연결해야 실습 중 수정한 코드를 push하고 배포할 수 있습니다.

사전 준비: 본인 GitHub에 influencer라는 이름의 빈 레포를 미리 만들어 두세요.
Step 7 — Wrangler 설치
💡 왜 필요해요? Wrangler 는 이 실습 사이트가 운영되고 있는 Cloudflare 의 공식 도구 입니다. 내 컴퓨터에서 실제 서비스와 똑같은 환경(로컬 서버)을 띄워주고, 작업 끝나면 "실제 인터넷에 배포" 하는 일도 같은 도구가 해줍니다. 한마디로 "내 컴퓨터 ↔ 실제 인터넷 서비스" 를 연결해주는 다리 라고 보면 됩니다.

먼저 프로젝트 의존성을 설치한 다음, Cloudflare의 Wrangler CLI 를 설치합니다.

npm install
# package.json 의 devDependencies (wrangler 포함) 설치

npm install -g wrangler # (선택) 글로벌 설치 — npx 없이 wrangler 직접 사용 가능
Wrangler란? Cloudflare Pages/Workers 로컬 개발 및 배포 도구입니다. npx serve .와 달리 CORS 프록시(functions/api/)까지 로컬에서 실행해줍니다.
Step 8 — cmux 설치 (선택, Claude 세션 multiplexer)

여러 Claude Code 세션을 한 화면에서 동시에 관리할 수 있는 도구입니다. 한 세션은 코딩, 다른 세션은 디버깅·문서 작성 식으로 병렬 작업할 때 유용합니다.

# 공식 GitHub: https://github.com/anthropics/cmux (또는 사용 중인 cmux 배포처)
# 권장: 공식 README 의 최신 설치 명령을 그대로 사용

# Windows: Scoop / Chocolatey / npm 등 본인 환경에 맞게
npm install -g cmux
꼭 필요한가요? 없어도 실습에는 지장 없습니다. 동시에 2~3개 작업을 굴리기 시작하면 그때 설치해도 OK. 처음 학습 단계라면 일반 터미널 2개로 충분합니다.
Step 9 — 로컬 서버 실행

프로젝트를 브라우저에서 확인합니다. CORS 프록시가 포함된 서버를 실행합니다.

npx wrangler pages dev .

브라우저에서 http://localhost:8788 접속하여 확인합니다.

방화벽 알림: Windows 보안 알림이 뜨면 "허용"을 클릭하세요.
Step 10 — 터미널 분할 + Claude Code 실행

서버가 실행 중인 상태에서 화면을 분할하여 Claude Code를 동시에 띄웁니다.
(Windows Terminal 분할 기능 또는 별도 터미널 창을 사용합니다.)

# Windows Terminal에서 화면 분할:
Alt + Shift + D (현재 패널 복제 분할)

분할된 오른쪽 패널에서 Claude Code를 실행합니다:

cd influencer
claude
Windows Terminal 분할 조작:
• 세로 분할: Alt + Shift + = (또는 +)
• 가로 분할: Alt + Shift + -
• 패널 전환: Alt + 방향키
• 패널 닫기: Ctrl + Shift + W
Step 11 — (선택) 상태바(Statusline) 설정

Claude Code 하단에 시간 · 모델명 · 컨텍스트 사용률 · 5시간/주간 사용 한도를 한 줄로 보여주는 상태바를 추가합니다. 작업 중 한도를 미리 확인할 수 있어 유용합니다.

설정 방법 (가장 쉬운 방식)

아래 예시 이미지를 스크린캡처한 뒤 Claude Code에 붙여넣고 이렇게만 입력하세요:

이렇게 나오게 설정해줘

Claude가 알아서 ~/.claude/statusline.sh 스크립트와 ~/.claude/settings.json 설정을 만들어 줍니다.

참고 이미지 — 이 모양 그대로 따라하면 됩니다:

Statusline 예시
08:59  Opus 4.7 (1M context)[1M]  ai-project/influencer  main  ctx:60%  5h:4%(~4h0m)  wk:10%(~1d18h)
표시 항목: 시간 · 모델명 · 컨텍스트 윈도우 · 작업 디렉토리 · git 브랜치 · 컨텍스트 사용률(ctx) · 5시간 한도(5h) · 주간 한도(wk)
※ 5h/wk는 Claude.ai 구독자에 한해 첫 API 응답 후부터 표시됩니다.

✅ 환경 세팅 완료 체크리스트

1

스킬 개요 — 사용 가능한 명령어

이 프로젝트에서 사용할 수 있는 슬래시 명령어 목록입니다.

/공구캘린더 인스타그램 공동구매 캘린더 생성 및 수정
/당첨자폼 이벤트 당첨자 배송지 입력 폼 생성 및 수정
/커리큘럼 AI 스터디 커리큘럼 페이지 생성 및 수정
/공구대시보드 공구 매출 대시보드 수정 (API 연동, 차트, 테이블)
/deploy Cloudflare Pages에 프로덕션 배포
/add-product 캘린더에 새 제품 매핑 추가
/setup 프로젝트 설정 상태 점검
사용법: Claude Code 실행 후, 채팅창에 슬래시(/)를 입력하면 사용 가능한 명령어 목록이 나타납니다. 명령어를 선택한 뒤 자연어로 원하는 작업을 설명하면 됩니다.
3

1주차 실습 — 공구대시보드

파마브로스 공동구매 어드민 API를 연동하여 공동구매 매출 대시보드를 수정합니다.

핵심 포인트: 대시보드는 파마브로스 공동구매의 백엔드 API 에서 실시간으로 데이터를 받아와 화면에 보여줍니다.
🚀 공구 대시보드 바로 열기
💻 로컬 대시보드 열기 ↗ 🌐 프로덕션 대시보드 열기 ↗
• 로컬 은 npm run dev 로 서버가 떠 있어야 동작 (실습 환경 — 코드 수정 즉시 반영)
• 프로덕션 은 항상 떠 있는 실서비스 (이미 main 브랜치에 배포된 최신본)
• 처음 진입 시 파마브로스 공동구매 어드민 ID/PW + Slack 2FA 코드 입력
• 로그인 성공 시 통계 카드 · 차트 · 공구 테이블이 표시되며, 테이블에서 공구를 클릭하면 상세 정보(인플루언서 · 셀러 · 옵션 · 일별 매출)를 확인할 수 있습니다.

🎯 실습 목표

📖 핵심 개념

데이터는 어디서 오나요?

대시보드 화면의 모든 숫자·표·차트는 파마브로스 공동구매 백엔드 API 에서 실시간으로 받아옵니다. 직접 데이터를 입력하는 게 아니라, 로그인하면 파마브로스 공동구매 서버가 본인 계정에 매핑된 공구·매출 정보를 보내줍니다.

파마브로스 공동구매 API → 대시보드 화면
# 새로고침할 때마다 최신 데이터로 갱신
💡 비개발자 포인트: "어디서 어떻게 가져오나" 같은 내부 동작 (로그인 토큰, CORS, 프록시 등) 은 모두 자동으로 처리되니 신경 쓸 필요 없어요. 화면에 보이는 데이터 = 파마브로스 공동구매 서버의 실시간 정보, 이것만 기억하면 됩니다.

🔨 실습 과정

실습 2-A — Swagger로 API 스키마 확인

API 응답 구조를 Swagger에서 확인하는 방법을 실습합니다. Swagger 페이지를 스크린캡처하여 Claude Code에 붙여넣고 질문합니다:

# Swagger 페이지 캡처를 붙여넣은 후:
이 API의 응답 필드를 설명해줘.
매출 리포트 데이터 구조는 어떻게 되어있어?
Swagger URL: dev-api.store.friendly-pharmacist.com/swagger-ui/index.html 에서 API 스키마를 직접 확인할 수 있습니다. 각 API의 요청 파라미터, 응답 필드, HTTP 메서드를 한눈에 볼 수 있습니다.
실습 2-B — 대시보드 커스터마이징

대시보드에서 수정하고 싶은 영역을 스크린캡처하여 Claude Code에 붙여넣고 요청합니다:

# 차트 영역 캡처를 붙여넣은 후:
이 차트를 세로 바 차트로 변경해줘
# 테이블 영역 캡처를 붙여넣은 후:
이 테이블에 "주문수" 컬럼을 추가해줘
# 통계 카드 영역 캡처를 붙여넣은 후:
여기에 "이번 달 매출" 카드를 추가해줘
확인 방법
http://localhost:8788/dashboard → 로그인 → 공구 클릭 → 상세 매출 데이터 확인
주의: 일부 공구(진행예정 상태)는 아직 매출 데이터가 없을 수 있습니다. 상세 패널에서 "아직 매출 데이터가 없습니다" 메시지가 표시되는 것은 정상입니다.

1주차 실습 — 컨텐츠 Apify 연동

🎯 실습 목표

🔨 실습 과정

Step 1 — apify-demo.html 페이지 열기

레포에 포함된 단독 실습 페이지로 이동합니다. 토큰 발급 단계부터 결과 카드까지 한 페이지에서 따라할 수 있습니다.

📷 Apify 실습 페이지 열기 ↗

Step 2 — Apify 토큰 발급 + 아이디 입력

실습 페이지의 Step 1 ~ Step 2 안내를 따라 console.apify.com 에서 토큰을 발급하고, 본인 인스타 아이디 (예: yakstory119) 을 입력합니다.

Step 3 — [가져오기] 클릭 + 결과 확인

Apify Actor 가 cold-start 시 30초~1분 정도 걸립니다. 비주얼 로딩 인디케이터로 진행을 확인하고, 결과 카드에서 본인 포스트가 보이면 성공입니다.

Step 4 — 대시보드에서 같은 데이터 확인

실습 페이지와 대시보드(/dashboard) 는 같은 localStorage 키를 공유합니다. 토큰/아이디를 한 번 저장하면 대시보드의 최근 인스타 포스트 panel 과 컨텐츠 관리 view 에서도 같은 데이터가 보입니다.

📚 2주차 — 공구 캘린더 + 이벤트 폼

공구 캘린더와 당첨자/이벤트 폼 실습. 인스타 업로드용 이미지 생성 + 폼 기반 데이터 수집.

2

2주차 실습 — 공구 캘린더

공동구매 캘린더의 디자인과 제품 매핑을 수정해 봅니다.

배우는 것: CSS 변수를 통한 테마 변경, REST API 데이터와 제품 매핑의 관계, html2canvas를 이용한 DOM→이미지 변환 원리, 대시보드와의 인증 토큰 공유 구조

🎯 실습 목표

🔨 실습 과정

실습 1-A — 테마 색상 변경

브라우저에서 http://localhost:8788을 열고, 캘린더 화면을 스크린캡처합니다.

Claude Code에 캡처 이미지를 붙여넣고 자연어로 요청합니다:

# 스크린캡처를 붙여넣은 후:
이 캘린더의 테마 색상을 파란색 계열로 변경해줘

브라우저를 새로고침하여 변경 사항을 확인합니다.

동작 원리: 캘린더의 모든 색상은 CSS 변수(--accent, --accent-hex)로 관리됩니다. Claude는 이 변수값만 변경하여 전체 테마를 일괄 적용합니다.
실습 1-B — 제품 추가

캘린더에 표시되는 제품 목록 부분을 스크린캡처하여 Claude Code에 붙여넣고 요청합니다:

# 캘린더 제품 영역 스크린캡처를 붙여넣은 후:
여기에 "피쉬 콜라겐"이라는 제품을 추가해줘.
타이틀에 "콜라겐"이 포함되면 매칭되게 하고,
설명은 "먹는 피부관리 / 저분자 콜라겐", 배지는 NEW로 해줘
매핑이란? 파마브로스 공동구매 API의 "공구타이틀(group_purchase_title)"에 키워드(예: 콜라겐)가 포함되면, 캘린더에 지정한 제품명·설명·배지가 자동 표시됩니다. 캘린더와 대시보드는 동일한 REST API를 사용하며, 로그인 토큰도 공유합니다.
실습 1-C — 자주 사용하는 제품 별칭(Alias) 관리

같은 제품이 매월 반복적으로 공구로 올라올 때마다 매번 매핑을 추가하면 비효율적입니다. 제품 별칭 관리 시스템을 만들어 한 번 정의한 제품을 키워드로 자동 매칭되게 해봅니다.

1) 현재 구조 파악 — Claude Code에 요청:

index.html 에서 캘린더가 제품을 어떻게 매핑하는지 분석해줘.
getShortName, getProductDesc, getBadge 함수가 어떻게 동작하고,
새 제품을 추가하려면 몇 군데를 고쳐야 하는지 알려줘

2) 별칭 테이블로 리팩토링:

index.html 의 제품 매핑을 PRODUCT_ALIASES 라는 객체 하나로
통합해줘. 다음 구조로:

const PRODUCT_ALIASES = {
  '콜라겐': { name: '피쉬 콜라겐', desc: '먹는 피부관리', badge: 'NEW' },
  '오메가': { name: '식물성 오메가3', desc: '혈관 건강', badge: 'HOT' },
  // ...
};

getShortName, getProductDesc, getBadge 함수가 이 테이블을 사용하도록 바꿔줘

3) 다중 키워드 매칭:

하나의 제품에 여러 별칭(키워드)을 매핑할 수 있게 확장해줘.
예: '루테인'과 '눈영양제'가 모두 같은 제품으로 매칭되도록.
키워드는 배열로 받을 수 있게 해줘

4) 자주 쓰는 제품 미리 등록 — 본인이 자주 다루는 5~10개 제품을 별칭 테이블에 추가하고 캘린더에서 정상 표시되는지 확인합니다.

왜 별칭으로 관리하나요? 파마브로스 공동구매 공구 타이틀은 매번 약간씩 달라집니다("YDY 콜라겐 60캡슐" → "[프리미엄] YDY 콜라겐 90캡슐"). 키워드 기반 별칭 테이블이 있으면 타이틀이 바뀌어도 동일 제품으로 자동 인식되어 매월 매핑을 다시 손보지 않아도 됩니다.
심화 도전: 별칭 테이블을 별도 JSON 파일로 분리하거나, localStorage에 저장해서 페이지에서 직접 추가/수정할 수 있는 관리 UI를 만들어 보세요.
실습 1-D — 자유 수정

수정하고 싶은 부분을 스크린캡처하여 Claude Code에 붙여넣고, 원하는 변경을 자연어로 설명합니다. 예시:

# 캘린더 헤더 부분을 캡처해서 붙여넣은 후:
이 헤더에 있는 이름을 내 인스타 아이디(@myid)로 바꿔줘
# 캘린더 하단을 캡처해서 붙여넣은 후:
여기 하단에 "문의: DM 주세요" 텍스트를 추가해줘
스크린캡처 팁: Mac: Cmd + Shift + 4로 영역 캡처 → Claude Code에 Cmd + V로 붙여넣기. 전체 화면보다 수정하고 싶은 부분만 캡처하면 Claude가 더 정확하게 이해합니다.
데이터 흐름: 캘린더는 대시보드와 동일한 파마브로스 공동구매 REST API(/api/admin/v1/group-purchases/plans)를 호출합니다. 상태코드 T4(확정), T6(진행중), T8(진행완료), Y0(정산대기)인 공구만 필터링하여 표시합니다. 대시보드에서 먼저 로그인하면, 캘린더에서도 자동 인증됩니다(동일한 dashboard_bearer_token 공유).
확인 방법
http://localhost:8788 → 관리자 패널 열기 → 로그인 → 캘린더 확인 → "이미지 저장" 버튼 클릭
4

2주차 실습 — 당첨자폼 (이벤트 폼)

이벤트 당첨자 배송지 입력 폼을 커스터마이징합니다.

배우는 것: HTML 폼 요소(input, select, textarea) 구조, Google Apps Script를 이용한 폼 데이터 저장, 관리자 페이지에서 데이터 조회 및 엑셀 내보내기

🎯 실습 목표

🔨 실습 과정

실습 3-A — 제품 정보 변경

브라우저에서 http://localhost:8788/event를 열고, 상품 카드 부분을 스크린캡처합니다.

Claude Code에 캡처를 붙여넣고 요청합니다:

# 상품 카드 캡처를 붙여넣은 후:
이 상품 카드의 제품명을 "내 브랜드 비타민C 1000"으로 바꾸고,
판매가를 39,000원, 옵션을 "30일분 / 60일분"으로 변경해줘
실습 3-B — 폼 필드 추가

폼 입력 영역을 스크린캡처하여 Claude Code에 붙여넣고 요청합니다:

# 폼 입력 영역 캡처를 붙여넣은 후:
여기에 "구매 옵션" 선택 필드를 추가해줘.
옵션은 "3박스", "6박스" 두 가지로 드롭다운으로 만들어줘
실습 3-C — 관리자 페이지 확인

관리자 페이지에서 데이터를 확인합니다:

# 브라우저에서 접속
http://localhost:8788/event-admin
# 로그인: admin / 1234

로그인 후 제출된 데이터를 테이블로 확인하고, 엑셀이나 CSV로 내보내기할 수 있습니다.

확인 방법
http://localhost:8788/event → 폼 작성 → 제출 → event-admin에서 확인
참고: 실제로 데이터가 저장되려면 Google Apps Script 연동이 필요합니다. 로컬 테스트에서는 UI 변경 확인에 집중하세요.
5

실습 4 — /deploy (배포하기)

수정한 결과물을 Cloudflare Pages에 배포합니다.

배우는 것: 정적 웹사이트 배포의 개념, Cloudflare Pages 배포 방법, 로컬 개발환경과 프로덕션 환경의 차이

🎯 실습 목표

🔨 실습 과정

Step 1 — Wrangler 설치

먼저 의존성을 설치한 다음 Cloudflare 배포 도구를 설치합니다:

npm install # package.json 의 의존성 설치 (wrangler 포함)

npm install -g wrangler # (선택) 글로벌 wrangler — 배포 명령을 더 짧게 쓸 수 있음
Step 2 — 배포 실행

Claude Code에서 배포 명령어를 실행합니다:

/deploy
# Claude가 Cloudflare API 토큰을 요청합니다
# 호스트에게 토큰을 받아 입력하세요
Step 3 — 배포 확인

배포 완료 후 제공되는 URL에 접속하여 확인합니다.

주의: Cloudflare API 토큰은 호스트가 제공합니다. 토큰은 절대 외부에 공유하지 마세요. 실습 시 호스트의 안내를 따라주세요.
★

도전 과제

실습을 모두 마친 후, 아래 도전 과제 중 하나를 선택하여 완성해 보세요. 난이도를 참고하여 도전해 보세요!

도전 A — 매출 요약 알림 시스템 보통

대시보드에 공구별 매출 목표 대비 달성률을 계산하고, 목표 초과 시 시각적 알림을 표시하는 기능을 만들어 보세요.

# 대시보드 테이블 영역 캡처를 붙여넣은 후:
각 공구에 매출 목표 금액을 설정할 수 있게 하고,
달성률이 100% 넘으면 테이블 행에 하이라이트 표시,
상단에 "목표 달성 공구 N개" 통계 카드도 추가해줘

완성 기준: 목표 설정 UI가 동작하고, 달성률이 테이블과 통계 카드에 반영된다

도전 B — 캘린더 멀티뷰 (월간/주간 전환) 보통

현재 월간 뷰만 있는 캘린더에 주간 뷰를 추가하고, 토글로 전환할 수 있게 만들어 보세요. 레이아웃과 데이터 필터링 로직을 모두 다뤄야 합니다.

# 캘린더 전체 화면 캡처를 붙여넣은 후:
이 캘린더에 "월간/주간" 전환 버튼을 추가하고,
주간 뷰에서는 이번 주 공구만 카드형으로 크게 보여줘.
주간 뷰도 PNG 저장이 되어야 해.

완성 기준: 월간↔주간 전환이 동작하고, 주간 뷰에서도 PNG 저장이 된다

도전 C — 일별 매출 트렌드 차트 어려움

공구 상세 모달에서 일별 매출 데이터를 꺾은선 차트로 시각화해 보세요. API의 group_purchase_plan_report_sale_day 데이터를 파싱하고 Chart.js 라인 차트로 렌더링합니다.

# 공구 상세 모달 캡처를 붙여넣은 후:
이 모달에 일별 매출 추이 꺾은선 차트를 추가해줘.
X축은 날짜, Y축은 주문금액.
주문이 급증한 날은 포인트를 강조해줘.

완성 기준: 상세 모달에 일별 매출 라인 차트가 표시되고, 데이터가 정확하다

도전 D — 공구 비교 분석 기능 어려움

두 개 이상의 공구를 선택하여 매출, 주문수, 기간 등을 나란히 비교하는 기능을 만들어 보세요. 체크박스 선택 → 비교 패널 렌더링까지 전체 흐름을 구현합니다.

# 대시보드 테이블 캡처를 붙여넣은 후:
이 테이블에 체크박스를 추가하고, 2~3개 공구를 선택하면
"비교" 버튼이 활성화되어 매출/주문수/기간을
나란히 비교하는 모달이 뜨게 만들어줘. 차트도 포함.

완성 기준: 복수 공구 선택 → 비교 모달에 데이터가 차트와 함께 표시된다

도전 E — Cloudflare Pages 자동 배포 파이프라인 어려움

GitHub에 push하면 Cloudflare Pages에 자동 배포되도록 설정해 보세요. CI/CD 파이프라인의 기초를 경험합니다.

내 GitHub 레포에 push하면 Cloudflare Pages에
자동 배포되도록 연결해줘.
Cloudflare 대시보드 설정 방법을 단계별로 알려줘.

완성 기준: git push만으로 프로덕션에 자동 배포되고, 배포 URL에서 확인 가능하다

도전 F — 새 페이지 처음부터 만들기 어려움

기존 프로젝트에 완전히 새로운 페이지를 추가해 보세요. 예: 공구 타임라인, 인플루언서 포트폴리오, 매출 리포트 PDF 등. 기획부터 구현까지 전 과정을 AI와 함께 진행합니다.

이 프로젝트에 새 페이지를 만들고 싶어.
공구 진행 상황을 타임라인으로 보여주는 페이지야.
각 공구의 시작일~종료일을 가로 막대로 표시하고,
현재 진행중인 공구는 강조해줘. API 데이터 연동도 해줘.

완성 기준: 새 HTML 페이지가 생성되고, API 데이터가 연동되어 배포까지 완료된다

AI 스터디 — Claude Code 실습 가이드

커리큘럼 보기 · 매출 대시보드 · 스터디 신청