쿠팡 최저가 알림 봇 만들기 — Claude Code로 1시간 완성 (네이버 쇼핑 API)

Claude Code · 바이브코딩 · 자동화

Claude Code로 1시간 만에
최저가 추적기 만들기
— 코드보다 PRD가 핵심이다

2026.06  ·  12년차 제조업 엔지니어가 바이브코딩으로 만든 실전 프로젝트

쇼핑할 때마다 "언제 가격 내려가지?" 하고 기다린 적 있을 것이다. 특정 상품의 최저가를 주기적으로 추적하고, 목표 가격 이하로 떨어지면 브라우저 팝업으로 알려주는 앱이 있으면 어떨까. 그걸 Claude Code로 1시간 만에 만들었다. 코드를 공유하는 게 목적이 아니다. PRD(기획서)를 공유한다. 이 글에 있는 PRD를 그대로 Claude Code에 붙여넣으면, 개발 경험이 없어도 동일한 서비스를 직접 만들 수 있다.

이 프로젝트의 전체 기술 스택: Next.js 14 + TypeScript (Frontend) / Python FastAPI + PostgreSQL (Backend) / 네이버 쇼핑 API

01 어떤 서비스인가

Lowest Price Seeker는 등록한 상품 키워드를 1분마다 네이버 쇼핑 API로 조회해서, 최저가가 목표가 이하로 내려오면 브라우저 팝업으로 알려주는 웹 앱이다. 로컬 윈도우 환경에서 돌아가고, Start.bat 하나로 백엔드·프론트엔드를 동시에 실행한다.

메인 대시보드 — 등록 상품의 현재가 / 목표가 / 달성률을 한눈에

• 상품 등록 키워드 + 최소 검색 가격 + 목표가를 입력하면 즉시 네이버 쇼핑에서 현재 최저가를 조회해 보여준다.
• 1분마다 자동 추적 APScheduler가 백그라운드에서 1분 주기로 가격을 체크하고 DB에 이력을 누적 저장한다.
• 브라우저 팝업 알림 목표가 도달 시 Web Notification API로 OS 레벨 팝업이 뜬다. 알림 권한 거부 시 인앱 토스트로 fallback.
• 가격 이력 차트 Recharts로 시간대별 최저가 변동을 라인 차트로 시각화한다. 언제 제일 쌌는지 한눈에 보인다.
• 최소 검색 가격 필터 "NT960XJG" 같은 노트북 키워드를 검색하면 저가 액세서리가 섞인다. min_price 설정으로 특정 금액 이상인 결과만 추린다.

상품 등록 화면 — 키워드, 최소 검색 가격, 목표가 입력

상세 보기 — 가격 이력 차트 + 최근 조회 이력 테이블

02 1시간 만에 만든 비결 — 코드가 아니라 PRD

핵심 — Claude Code는 코드를 짜달라고 하면 잘 못 한다. 그런데 PRD를 주면 다르다. "이 기획서를 보고 Phase 1부터 순서대로 만들어줘" 한 마디면 폴더 구조부터 DB 마이그레이션, API 엔드포인트, 프론트엔드 컴포넌트까지 알아서 만든다.

12년차 제조업 공정 엔지니어인 내가 이 앱을 1시간 만에 완성할 수 있었던 이유는 딱 하나다. PRD를 먼저 충분히 만들었기 때문이다. Claude Code에게 어떤 파일을 어디에 만들지, 어떤 API를 써야 하는지, 어떤 순서로 개발해야 하는지를 PRD에 전부 담았다. Claude Code는 그 PRD를 읽고 기계처럼 실행했다.

❌ 잘 안 되는 방식

"쿠팡 최저가 알림 봇 만들어줘"

막연한 요청 → Claude Code가 방향을 혼자 결정 → 원하는 것과 다른 결과 → 수정 반복

✅ 1시간 완성 방식

"PRD.md와 CLAUDE.md를 읽고 Phase 1부터 시작해줘"

명확한 스펙 → Claude Code가 그대로 실행 → 원하는 결과 → 거의 수정 없음

이 글에서 코드를 줄줄이 공유하지 않는다. 코드는 PRD를 주면 Claude Code가 알아서 생성하기 때문이다. 진짜 가치 있는 것은 "어떻게 기획했느냐"다. 아래에 실제 사용한 PRD 전문을 공개한다.

03 동작 구조

전체 흐름은 단순하다. 프론트(Next.js)가 사용자 입력을 받아 백엔드(FastAPI)에 전달하고, 백엔드의 스케줄러가 주기적으로 네이버 API를 호출해 가격을 DB에 쌓는다.

상품 키워드 + 목표가 등록

→

PostgreSQL DB 저장

→

APScheduler 1분 주기

→

네이버 쇼핑 API 조회

→

목표가 도달?

→

브라우저 팝업 알림

프론트엔드는 30초마다 /api/alerts/unread를 폴링해서 미확인 알림이 있으면 Web Notification API로 OS 팝업을 띄운다. 브라우저 알림 권한이 없으면 화면 내 토스트로 대체된다.

구성요소	기술	역할
Frontend	Next.js 14 + TypeScript + Tailwind	대시보드, 상품 등록/상세 UI
Backend	Python FastAPI + Uvicorn	REST API, 스케줄러 관리
Scheduler	APScheduler 3.x	1분 주기 가격 자동 조회
Database	PostgreSQL + SQLAlchemy 2.0	상품/가격이력/알림 저장
외부 API	네이버 쇼핑 검색 API	멀티 쇼핑몰 최저가 조회
알림	Web Notification API	목표가 달성 시 브라우저 팝업

04 PRD 전문 — 그대로 복사해서 Claude Code에 붙여넣으세요

사용 방법 — 아래 PRD를 전체 복사 → PRD.md 파일로 저장 → Claude Code를 프로젝트 루트에서 실행 → "PRD.md를 읽고 Phase 1부터 순서대로 만들어줘" 입력. 그게 전부다. Claude Code가 폴더 구조, DB 마이그레이션, API 엔드포인트, 프론트엔드 컴포넌트를 모두 만든다.

📄 PRD.md — Lowest Price Seeker

# PRD — Lowest Price Seeker
> Claude Code(바이브코딩)로 만드는 최저가 알림 봇 시스템

---

## 1. 프로젝트 개요

| 항목 | 내용 |
|------|------|
| 프로젝트명 | Lowest Price Seeker |
| 목적 | 쇼핑몰 상품 가격을 주기적으로 추적하고, 목표가 도달 시 브라우저 알림 |
| 개발 방식 | Claude Code를 활용한 바이브코딩 |
| 개발 환경 | Windows 11 + Python 3.11+ + Node.js |

---

## 2. 기술 스택

### Frontend
- Framework: Next.js 14 (App Router) + TypeScript strict
- Styling: Tailwind CSS v3
- 서버 상태: React Query (TanStack Query v5)
- 클라이언트 상태: Zustand v5 (토스트 알림)
- 차트: Recharts (가격 이력 시각화)
- Dev 서버: next dev --turbo (Windows 파일 잠금 오류 방지)

### Backend
- Runtime: Python 3.11+
- Web Framework: FastAPI + Uvicorn
- ORM: SQLAlchemy 2.0 async + Alembic (마이그레이션)
- 스케줄러: APScheduler 3.x (AsyncIOScheduler)
- HTTP Client: httpx (비동기 API 호출)
- 패키지 관리: requirements.txt (>= 버전 지정)

### Database
- DBMS: PostgreSQL
- DB명: lowest_price_seeker
- 접속 정보: .env 파일로 관리 (절대 코드에 하드코딩 금지)

### 환경변수 (.env.example)
DATABASE_URL=postgresql://USER:PASSWORD@localhost:5432/lowest_price_seeker
NAVER_CLIENT_ID=
NAVER_CLIENT_SECRET=

### 외부 API
| API | 용도 | 비용 |
|-----|------|------|
| 네이버 쇼핑 검색 API | 멀티 쇼핑몰 최저가 조회 | 무료 (일 25,000건) |

네이버 쇼핑 API 발급: https://developers.naver.com
→ 애플리케이션 등록 → 검색 API 선택 → Client ID / Secret 발급

---

## 3. 핵심 기능

### 3-1. 상품 등록
- 웹 대시보드에서 상품 키워드 + 목표가 + 최소 검색 가격(선택) 입력
- 등록 즉시 네이버 쇼핑 API로 1회 가격 조회 → 현재가 표시
- 가격 조회 실패 시에도 상품 등록은 완료 처리

### 3-2. 최소 검색 가격 필터 (min_price)
- 키워드 검색 시 저가 액세서리·무관련 상품 혼입 방지
- min_price 설정 시: 결과 중 해당 금액 이상인 것만 추린 뒤 최솟값 선택
- 미설정 시: 전체 결과 중 최솟값
- 네이버 API: sort=sim + display=100으로 조회

### 3-3. 주기적 가격 추적
- APScheduler로 1분마다 등록된 활성 상품 전체 가격 조회
- 조회 결과는 항상 price_history 테이블에 누적 저장
- current_price 업데이트

### 3-4. 목표가 알림
- 현재가 ≤ 목표가 조건 충족 시 알림 생성
- 동일 상품 알림 쿨다운 6시간 (DB alerts 테이블 기준)
- 프론트엔드가 백엔드를 30초마다 폴링하여 미확인 알림 확인
- Web Notification API로 브라우저 팝업 (권한 미허용 시 인앱 토스트 fallback)
- 알림 내용: 상품명 + 현재가

### 3-5. 웹 대시보드
- 등록 상품 목록: 현재가 / 목표가 / 달성률 프로그레스바
- 상품별 가격 이력 라인 차트 (Recharts)
- 상품 추가 / 삭제(soft delete) / 목표가 수정

---

## 4. 데이터베이스 스키마

### products 테이블
CREATE TABLE products (
    id            SERIAL PRIMARY KEY,
    keyword       VARCHAR(255) NOT NULL,
    target_price  INTEGER NOT NULL,
    current_price INTEGER,
    min_price     INTEGER,
    is_active     BOOLEAN DEFAULT TRUE,
    created_at    TIMESTAMP DEFAULT NOW(),
    updated_at    TIMESTAMP DEFAULT NOW()
);

### price_history 테이블
CREATE TABLE price_history (
    id          SERIAL PRIMARY KEY,
    product_id  INTEGER REFERENCES products(id) ON DELETE CASCADE,
    price       INTEGER NOT NULL,
    mall_name   VARCHAR(100),
    product_url TEXT,
    checked_at  TIMESTAMP DEFAULT NOW()
);

### alerts 테이블
CREATE TABLE alerts (
    id           SERIAL PRIMARY KEY,
    product_id   INTEGER REFERENCES products(id) ON DELETE CASCADE,
    price        INTEGER NOT NULL,
    is_read      BOOLEAN DEFAULT FALSE,
    sent_at      TIMESTAMP DEFAULT NOW()
);

### Alembic 마이그레이션
001_initial: products / price_history / alerts 테이블 생성
002_add_min_price: products 테이블에 min_price 컬럼 추가

---

## 5. API 엔드포인트 (FastAPI)

### 상품
GET    /api/products              활성 상품 목록 조회 (최신순)
POST   /api/products              상품 등록 + 즉시 가격 조회
DELETE /api/products/{id}         상품 삭제 (soft delete)
PATCH  /api/products/{id}         목표가 수정
GET    /api/products/{id}/history 가격 이력 조회 (최신 100건)

### 알림
GET   /api/alerts/unread     미확인 알림 목록 (프론트 폴링용)
PATCH /api/alerts/{id}/read  알림 읽음 처리

---

## 6. 프론트엔드 페이지 구성

/              대시보드 (상품 카드 그리드 + 달성률 프로그레스바)
/products/new  상품 등록 (키워드 + 최소가 + 목표가 입력폼)
/products/[id] 상품 상세 (가격 이력 차트 + 목표가 수정)

---

## 7. 폴더 구조

src/
├── frontend/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── providers.tsx
│   │   └── products/
│   │       ├── new/page.tsx
│   │       └── [id]/page.tsx
│   ├── components/
│   │   ├── ProductCard.tsx
│   │   ├── PriceChart.tsx
│   │   ├── AddProductForm.tsx
│   │   └── NotificationToast.tsx
│   ├── hooks/
│   │   └── useAlertPolling.ts
│   └── lib/
│       ├── api.ts
│       ├── types.ts
│       └── store.ts
│
└── backend/
    ├── main.py
    ├── models.py
    ├── schemas.py
    ├── database.py
    ├── routers/
    │   ├── products.py
    │   └── alerts.py
    ├── services/
    │   ├── naver_api.py
    │   └── scheduler.py
    ├── alembic/
    ├── requirements.txt
    ├── .env
    └── .env.example

---

## 8. 개발 단계 (Phase)

Phase 1 — 백엔드 코어
- FastAPI 프로젝트 초기화 + Uvicorn
- PostgreSQL 연결 + SQLAlchemy 2.0 async 모델 정의
- Alembic 마이그레이션 초기 설정
- 네이버 쇼핑 API 연동 + 최저가 파싱 (sort=sim, display=100)
- 상품 CRUD API 구현 (등록 시 즉시 가격 조회 포함)

Phase 2 — 스케줄러 + 알림
- APScheduler 1분 주기 가격 조회 구현
- 목표가 비교 로직 + alerts 테이블 기록
- /api/alerts/unread 폴링 엔드포인트 구현
- 알림 쿨다운 6시간 로직

Phase 3 — 프론트엔드
- Next.js 14 App Router + Tailwind CSS + TypeScript strict
- 대시보드 페이지 (상품 카드 그리드 + 달성률 프로그레스바)
- 상품 등록 폼 (min_price + 목표가)
- 가격 이력 차트 (Recharts)
- useAlertPolling 훅 (30초 폴링 + Web Notification)
- 인앱 토스트 fallback
- FastAPI 연동 (React Query)

Phase 4 — 마무리
- Start.bat / Stop.bat 원클릭 실행/종료 스크립트
- .env.example 및 README 작성

---

## 9. 실행 방법 (Windows)

# 원클릭 실행
Start.bat 더블클릭

# Start.bat이 자동으로 수행:
# 1. Python 가상환경(.venv) 생성
# 2. pip install -r requirements.txt
# 3. .env 파일 존재 확인
# 4. alembic upgrade head (DB 자동 마이그레이션)
# 5. 백엔드 서버 시작 (포트 8000)
# 6. npm install (필요 시)
# 7. 프론트엔드 서버 시작 (포트 3000)

# 접속 주소
Frontend:  http://localhost:3000
Backend:   http://localhost:8000
Swagger:   http://localhost:8000/docs

---

## 10. Windows 환경 주의사항

| 이슈 | 원인 | 해결 |
|------|------|------|
| .bat 한글 깨짐 | CP949 인코딩 | .bat 파일을 순수 ASCII로 작성 |
| alembic UnicodeDecodeError | configparser CP949 파싱 | alembic.ini 한글 주석 전부 제거 |
| Next.js errno -4094 | webpack Windows 파일 잠금 | next dev --turbo 로 전환 |
| Python 3.14 패키지 실패 | C/Rust 빌드 도구 없음 | requirements.txt를 >= 버전으로 변경 |

## 11. 주의사항

- 네이버 쇼핑 API 일 호출 한도: 25,000건
  → 1분 주기 기준 최대 약 17개 상품 동시 추적 가능 (운영 시 주기 조정 권장)
- DB 접속 정보는 반드시 .env로 관리, .gitignore에 추가
- Web Notification은 localhost 또는 HTTPS 환경에서만 동작
- .env 파일은 절대 git에 커밋하지 말 것

05 개발하면서 마주친 실제 이슈들

Claude Code가 코드를 다 만들어줘도 막히는 지점이 있었다. 특히 Windows 환경 특유의 문제들이었다. PRD에도 넣어뒀지만, 겪어보지 않으면 모르는 것들이라 따로 정리한다.

• .bat 파일 한글 깨짐 cmd.exe가 UTF-8 파일을 CP949로 파싱한다. 해결책은 간단하다. .bat 파일의 주석과 메시지를 전부 영어로만 작성하면 된다.
• Next.js UNKNOWN: errno -4094 webpack dev 서버의 Windows 파일 잠금 버그다. next dev를 next dev --turbo (Turbopack)으로 바꾸면 바로 해결된다.
• 네이버 API에서 저가 액세서리 혼입 sort=asc로 정렬하면 노트북 키워드를 넣어도 1,000원짜리 케이블이 최저가로 잡힌다. sort=sim(관련도순) + display=100으로 가져와서 min_price 이상인 것 중 최솟값을 선택하는 로직이 핵심이다.
• Python 3.14 패키지 빌드 실패 asyncpg, pydantic-core 같은 패키지가 Python 3.14용 wheel이 없어서 C 빌드를 시도하다 실패한다. requirements.txt의 버전을 ==에서 >=로 바꾸면 호환 가능한 하위 버전을 자동으로 찾는다.

06 이 서비스의 확장 가능성

지금은 브라우저를 열어두어야 팝업 알림이 동작한다는 한계가 있다. 하지만 구조상 알림 채널을 교체하는 건 어렵지 않다. 백엔드의 알림 발송 로직 한 곳만 바꾸면 된다.

🚀 향후 확장 방향

• 카카오톡 알림 연동 카카오 비즈니스 채널 + 알림톡 API 연동 시, 브라우저 없이 휴대폰으로 직접 알림을 받을 수 있다. 가장 현실적인 다음 단계다.
• 텔레그램 봇 연동 Telegram Bot API는 무료고 구현도 간단하다. 봇 토큰 하나로 어느 기기에서든 알림 수신이 가능해진다. 해외 사용자에게 특히 유용하다.
• 쿠팡 파트너스 수익화 쿠팡 파트너스 API 키를 발급받아 알림 메시지에 딥링크를 삽입하면, 사용자가 링크를 타고 구매할 때마다 1~3% 수수료가 쌓인다. 현재 구조에서 naver_api.py 옆에 coupang_api.py만 추가하면 된다.
• 다나와 · 11번가 직접 크롤링 네이버 쇼핑 API가 커버하지 못하는 특가 정보를 위해 BeautifulSoup 크롤러를 추가할 수 있다. scheduler.py에 크롤러 호출만 추가하면 된다.
• 서버 배포 + 다중 사용자 지금은 로컬 단독 사용이지만, VPS에 배포하고 사용자 인증을 추가하면 가족·지인이 함께 쓰는 서비스로 확장된다. PRD의 user_id 컬럼만 다시 살리면 된다.

핵심 — 이 구조의 진짜 강점은 알림 채널이 백엔드 서비스 한 곳에만 의존한다는 점이다. 브라우저 팝업 → 카카오톡 → 텔레그램으로 바꾸는 데 코드 10줄이면 충분하다. PRD를 잘 짜면 확장도 쉽다.

07 Claude Code 사용 팁 — CLAUDE.md도 같이 만들어라

PRD 외에 CLAUDE.md라는 파일도 함께 만들어두면 Claude Code가 훨씬 일관되게 동작한다. CLAUDE.md는 Claude Code가 매 작업 전에 읽는 규칙 파일이다.

CLAUDE.md 핵심 항목 예시

# 파일 생성 위치 규칙
모든 코드는 D:\Dev\04.lowest_price_seeker\src\ 아래에만 생성

# 보안 규칙 (절대 위반 금지)
DB 접속 정보, API 키를 코드에 하드코딩 절대 금지
민감 정보는 backend/.env 파일에만 작성

# 개발 순서
Phase 1 → Phase 2 → Phase 3 → Phase 4 순서 준수
이전 Phase 완료 전 다음 Phase 시작 금지

# 커밋 메시지 규칙
한국어로 작성: [Phase N] 작업 내용

PRD가 "무엇을 만드냐"를 정의한다면, CLAUDE.md는 "어떻게 만드냐"의 규칙을 강제한다. 이 두 파일이 있으면 Claude Code가 폴더를 엉뚱한 곳에 만들거나, Phase를 건너뛰거나, 비밀번호를 코드에 박아넣는 실수를 하지 않는다.

Summary

12년차 공정 엔지니어가 Claude Code로 최저가 추적 웹앱을 1시간 만에 완성했다. 비결은 코딩 실력이 아니라 PRD의 품질이었다. 위에 공개한 PRD를 그대로 Claude Code에 입력하면 동일한 서비스를 누구나 만들 수 있다. 코드는 AI가 쓴다. 기획은 사람이 한다. 그게 바이브코딩의 본질이다. 다음 글에서는 카카오톡 알림 연동까지 확장하는 과정을 다룬다.