## 📝 한줄 요약
YouTube Studio를 영상별로 들락날락하며 지표 보는 게 답답해서, Claude Code와 함께 **하루 만에** 내 채널 전용 분석 대시보드를 만들었다. 핵심은 "예쁜 차트"가 아니라 **거기서 다음 영상 기획용 action item을 뽑아내는 것**이라는 걸 깨달았다.
**바쁘시면 이것만 읽어도 돼요:**
- **사용한 도구와 목표**: Claude Code로 본인 YouTube 채널 전용 분석 대시보드 구축 — 영상별 지속률·CTR·트래픽 소스를 한 페이지에서 조회
- **가장 만족도 높았던 워크플로우**: docs 스킬로 YouTube API의 불가능한 부분부터 먼저 파악 → 그걸 반영한 PRD 작성 → /kkirikkiri 멀티 에이전트로 PRD 재검증 (이 3단 파이프라인)
- **검증 효과**: PRD 재검증 단계에서 본격 개발 전 P0(필수 픽스) 9건 + 핵심 P1 다수가 한 번에 도출됨
- **하루 안에 풀스택 완성**: 인증 + DB + YouTube API + 스케줄러 + 3개 UI 페이지를 한 세션에서
- **현실 트러블슈팅**: 포트 3000을 좀비 프로세스가 점유 → OAuth 콜백 URL 불일치로 로그인 자체가 안 될 뻔 → PowerShell로 진단·해결
- **배운 교훈**: 처음부터 "어디에 배포할지" 정하고 시작해라. 그리고 **지표 자체가 아니라 거기서 뽑는 action item이 진짜 가치다.**
## 🎯 이런 분들께 도움돼요
- YouTube/SNS 운영하는 1인 크리에이터 — 매번 Studio 메뉴 들락날락이 답답한 분
- AI 코딩 도구로 본인 업무용 도구를 만들고 싶은데 어디서 시작할지 막막한 분
- 한 번 시도했다가 PRD 단계에서 막막해서 그냥 코드부터 짜다가 망친 경험이 있는 분
## 😫 문제 상황 (Before)
YouTube Studio가 보여주는 분석은 영상별로 메뉴에 들어가서 봐야 한다. "이 영상은 알고리즘 추천이 몇 퍼센트, 검색 유입이 몇 퍼센트지?" "Shorts 평균 지속률이랑 비교하면 이 영상은 잘 나온 건가?" 같은 질문을 하려면 영상 하나하나 클릭해서 표를 따로 만들어야 했다.
**유튜브 지표를 빠르게 보고 판단하기 위해서** — 그게 시작이었다. 영상을 올린 다음 "다음 영상은 어떤 방향으로 갈지" 결정하려면 데이터를 빠르게 봐야 하는데, 매번 Studio 안에서 길을 잃었다.
그래서 결심했다. **한 페이지에서 다 보이는 내 전용 대시보드를 만들자.**
## 🛠️ 사용한 도구
- **도구명**: Claude Code (Anthropic 공식 CLI)
- **모델**: Claude Opus 4.7
- **활용한 외부 스킬**:
- 지피타쿠님의 docs 스킬 — 외부 API 문서를 정확히 읽고 한계를 파악해주는 스킬
- /kkirikkiri 스킬 — 자연어로 AI 에이전트 팀을 자동 구성해서 동시 검토 시키는 멀티 에이전트 스킬
---
## 🔧 작업 과정
### 1단계 — 코드부터 짜지 않고 "안 되는 것"부터 알아보기
이번 프로젝트에서 가장 결과물 만족도가 높았던 이유는 **시작을 잘 했기 때문**이다. 보통 AI 코딩을 한다고 하면 바로 "이런 거 만들어줘" 하고 코드부터 짜는데, 이번엔 의도적으로 한 단계를 더 두었다.
YouTube에는 두 종류의 API가 있다. 하나는 영상 메타데이터를 주는 Data API, 다른 하나는 시청률·노출수 같은 분석 지표를 주는 Analytics API. **각각이 뭘 줄 수 있고, 뭘 못 주는지를 모르고 PRD를 쓰면 십중팔구 헛것을 그리게 된다.**
그래서 먼저 지피타쿠님이 만드신 docs 스킬을 돌렸다. 이 스킬은 공식 문서를 정확히 읽고 "이런 dimension은 있고, 이런 건 없다" "이 API는 D-3 지연이 있어서 오늘 데이터는 못 받는다" 같은 한계를 정리해준다.
그렇게 **불가능한 것의 목록**을 먼저 받아두고, 그 위에서 PRD를 작성했다. 이게 나중에 엄청난 차이를 만들었다.
---
### 2단계 — 만든 PRD를 혼자 검토하지 않고 가상 전문가 팀에게 맡기기
PRD를 다 쓰고 나면 보통 "이 정도면 됐겠지" 하고 바로 구현 들어간다. 근데 이번엔 한 가지 더 했다.
```
/kkirikkiri 유튜브 전문가 관점으로 prd 체크해봐
```
/kkirikkiri는 자연어로 "이런 관점에서 검토 팀을 만들어줘" 하면 AI가 가상 전문가 4명을 자동으로 구성해서 동시에 검토시켜주는 스킬이다. 처음엔 Claude가 "어떤 관점이 필요하냐"고 묻길래 골랐다:
> 유튜브 전문가가 어떤 관점으로 PRD를 봐줬으면 좋겠어요?
선택지를 3개 골랐다 — **콘텐츠 성과 지표**, **YouTube API 제약·현실성**, **성장·알고리즘 인사이트**. 이렇게 시점이 다른 가상 전문가들이 동시에 PRD를 뜯어보고 문제점을 도출했다.
결과는 놀라웠다. 본격 코드를 한 줄도 짜기 전에 **반드시 고쳐야 할 P0 9건**이 한 번에 발견됐다. 예를 들면:
- Analytics API는 D-3 지연이 있어서 오늘 데이터는 못 받는다 → 화면에 "Analytics 데이터는 X일까지 반영"이라고 명시 필요
- 트래픽 소스를 raw 그대로 보여주면 종류가 너무 많다 → 알고리즘 / 검색 / 직접 / 기타 4그룹으로 정규화 필요
- 영상 삭제됐을 때 DB에서 지우면 과거 분석 데이터가 사라진다 → soft delete 패턴 필요
**이 9건을 PRD 단계에서 잡았기 때문에**, 나중에 구현하면서 "어 이거 안 되네" 하고 멈춰서 PRD를 다시 고치는 일이 거의 없었다.
---
### 3단계 — "한 번에 진행하자" 한 마디로 풀스택 앱 완성
PRD가 단단해진 다음엔 사실상 일사천리였다. Google Cloud Console 세팅(이건 처음이라 Claude한테 단계별 가이드 시킴), 자격증명 발급, pnpm 설치까지 끝낸 다음 한 마디 했다.
```
한번에 남은 작업 한번에 진행하자
```
이 한 마디로 Claude가 6개 작업을 한 번에 처리했다:
- 로그인 인증 시스템 (Google OAuth, 본인만 통과하는 화이트리스트)
- 데이터베이스 10개 테이블 설계
- YouTube API 호출 모듈 (쿼터 관리 포함 — 하루 한도 넘으면 자동 중단)
- 동기화 파이프라인 (영상 메타 + 일별 통계 + 트래픽 소스 + 지속률 곡선)
- 자동 스케줄러 (매일 새벽 3시에 자동 동기화)
- 3개 화면 (홈 KPI / 영상 목록 / 영상 상세)
이게 가능했던 이유는 **앞 단계에서 PRD가 단단했기 때문**이다. PRD가 흐릿하면 "한 번에 진행해" 시키면 100% 산으로 간다. 근데 PRD에 "이건 이렇게 해야 한다"가 명확히 적혀있으니까 Claude가 헷갈릴 일이 없었다.
---
### 4단계 — 첫 동기화 직전, 좀비 프로세스에게 발목 잡힐 뻔
로컬에서 처음 실행하는데 메시지가 떴다.
```
PS C:\Full_Ai\youtube_dashboard> pnpm dev
⚠ Port 3000 is in use by process 78816, using available port 3002 instead.
```
3000번 포트가 다른 프로세스에게 점유돼서 Next.js가 알아서 3002로 옮겨갔다. 보통이면 "오 그래 3002로 가자" 하고 넘어갈 일이다. **근데 Google OAuth 콜백 URL은 localhost:3000으로 고정 등록**돼 있었다. 3002에서 로그인 시도하면 "redirect_uri_mismatch"로 통째로 막힌다.
Claude에게 물었다.
```
포트 바꿔야되는거아냐?
```
Claude는 즉시 진단했다: "3000번 점유한 프로세스가 이전 세션의 좀비 next dev 서버다. 죽이는 게 맞다 — OAuth URL을 다시 등록하기보다." 그리고 PowerShell로 프로세스 ID 식별 → 강제 종료 → 포트 회수 → "이제 다시 pnpm dev 하면 3000번으로 뜬다"까지 정확히 안내했다.
**이런 환경 문제는 비개발자가 가장 잘 막히는 지점**인데, AI가 진단·해결까지 가이드해주니까 5분도 안 걸렸다.
---
### 5단계 — 첫 동기화 결과 화면이 의도대로 비어 있는 걸 확인한 순간
로그인하고 "수동 동기화" 한 번 누르니까 영상 3개가 적재됐다. 근데 시청시간·CTR·노출수 컬럼이 전부 "—"로 비어 있었다.
순간 "어 버그인가?" 했는데, Claude가 바로 짚어줬다.
> 이건 버그가 아닙니다. 오늘이 2026-05-22인데 Analytics API는 D-3 지연이 있어서 5-19까지만 데이터를 줍니다. 그런데 영상 업로드일이 5-20이에요. **영상이 업로드되기도 전 시점까지밖에 데이터가 없는 셈이라 비어 있는 게 정상.** 내일부터 채워집니다.
**1단계에서 docs 스킬로 D-3 지연을 미리 파악해뒀기 때문에**, 코드도 정확히 그렇게 짜져 있었던 거다. PRD 단계의 정확성이 끝까지 일관되게 이어진 순간이었다.
---
### 6단계 — 로컬용으로 만든 걸 Vercel 배포용으로 다시 만들기
여기서 한 가지 후회되는 게 있다. 처음엔 "내 PC에서만 돌면 되지" 싶어서 로컬 SQLite + 상주 스케줄러 구조로 만들었다. 근데 첫 동기화 성공한 다음에 생각이 바뀌었다.
```
이 페이지를 vercel 배포해볼까?
```
Vercel은 서버리스 환경이라서 **로컬용 구조가 통째로 안 맞는다**. SQLite 파일은 매번 휘발되고, 상주 스케줄러는 동작 자체를 안 한다. Claude가 옵션 3가지를 정리해서 보여주고 결정을 도와줬다 — 결국 리팩토링 진행.
DB는 Turso(libSQL)로, 스케줄러는 Vercel Cron으로 교체. 다행히 같은 날에 작업해서 코드가 머릿속에 살아있어 부담이 적었다. **하지만 일주일 뒤였으면 훨씬 큰 비용이 들었을 거다.**
이게 두 번째 교훈이다: **처음부터 "어디에 배포할지" 정하고 시작해라.**
---
## ✅ 결과 (After)
### Before vs After
| 항목 | Before | After |
|------|--------|-------|
| 영상별 지표 확인 | YouTube Studio에서 영상 하나씩 클릭, 표 따로 작성 | 한 페이지에서 전체 목록 + 정렬·필터 즉시 |
| Shorts vs Long 비교 | 직접 분류해서 평균 계산 | 자동 분리 + 평균 지속률 카드 분리 표시 |
| 본인 영상 vs 채널 평균 | 비교 불가능 | 영상 상세에 채널 평균 지속률 곡선 오버레이 |
| 트래픽 소스 분석 | 영상별 메뉴에서 raw 데이터 | 알고리즘/검색/직접/기타 4그룹 자동 정규화 + 드릴다운 |
| 의사결정 속도 | 데이터 모으는 데 시간 소요 → 판단 지연 | 페이지 로드 즉시 다음 영상 방향 판단 가능 |
| 자동 갱신 | 없음 (매번 수동 확인) | 매일 03:00 자동 동기화 (Vercel 배포 후 PC 안 켜도 됨) |
### 결과물
- 본인 YouTube 채널 전용 분석 대시보드 (3개 화면 — 홈 KPI / 영상 목록 / 영상 상세)
- 매일 새벽 자동 동기화 시스템
- 본인 외 다른 계정은 로그인조차 막힌 보안 구조
## 💬 이 과정에서 배운 AI 활용 팁
### 효과적이었던 것
1. **외부 API 쓸 거면 docs 스킬부터 돌려라**
"되는 것"보다 **"안 되는 것"**을 먼저 알아야 PRD가 현실적이다. YouTube Analytics의 D-3 지연, search.list 쿼터 100 같은 제약을 모르고 가면 한참 헤맨다.
2. **PRD를 혼자 검토하지 말고 /kkirikkiri 같은 멀티 에이전트로 재검증해라**
사람 한 명 시점에선 빈틈을 못 본다. 4명의 가상 전문가가 동시에 검토하면 P0 9건이 한 번에 잡힌다. 본격 개발 전에 이 단계를 거치는 비용 < 개발 도중에 발견해서 다시 만드는 비용.
3. **처음부터 "어디에 배포할지" 정하고 시작해라**
로컬용으로 만들었다가 클라우드용으로 다시 만드는 비용은 처음부터 클라우드용으로 만드는 비용과 비슷하다. 일주일만 늦어도 비용이 훨씬 커진다.
4. **단단한 PRD가 있을 땐 "한 번에 진행하자" 큰 위임을 무서워하지 마라**
AI가 6개 작업을 한 번에 처리할 수 있다. 단 **앞 단계에서 PRD가 단단해야** 통한다.
### 이렇게 하면 안 돼요
1. **PRD 없이 "이런 거 만들어줘" 한 마디로 시작하기**
초기엔 빨라 보이지만 결국 중간에 멈춰서 PRD 만들기를 반복하게 된다. 시작에서 30분 더 쓰는 게 전체 시간을 줄인다.
2. **API 한계를 안 보고 "그냥 다 가능하겠지" 가정하기**
YouTube Analytics가 오늘 데이터를 줄 거라 가정하고 UI를 짜면, 막상 받아보니 비어 있어서 화면이 깨진다.
3. **환경 문제(포트, 좀비 프로세스 등)를 혼자 끙끙대기**
"포트 3000 점유 중인 프로세스 뭐냐"만 물어봐도 AI가 PowerShell 명령어 + 해결 순서를 그대로 알려준다.
## 🌍 다른 업무에 적용한다면?
이 워크플로우 — **docs로 한계 파악 → PRD → /kkirikkiri 재검증 → 단계별 위임** — 는 외부 API에 의존하는 모든 도구 만들기에 그대로 통한다.
- **인스타그램·블로그 통합 분석 대시보드**: docs로 각 플랫폼 API 한계 파악 → 어떤 지표는 받을 수 있고 어떤 건 못 받는지 먼저 정리.
- **고객사 데이터 자동 리포트**: 고객사 CRM/Slack/Sheets API 제약을 먼저 docs로 확인 후 PRD.
- **이커머스 매출 모니터링**: 쇼피파이/네이버스마트스토어 API의 일별 호출 한도, 데이터 지연 같은 제약을 PRD에 미리 반영.
**핵심은 항상 같다 — "AI가 헛것을 그리지 않게, 시작 단계에서 현실 제약을 정확히 알려주는 것".**
## 🚀 앞으로의 계획
대시보드가 완성됐지만, 정말 중요한 건 차트 자체가 아니라 **거기서 어떤 action item을 뽑아낼 것인가**다. 다음 두 가지를 추가할 계획.
### 1. 자동 인사이트 생성기
동기화가 끝나면 영상별 지표를 LLM에 보내서 자동으로 분석을 받는다. 예:
> "이 영상은 알고리즘 추천 30% / 검색 50% — 검색 최적화가 잘 됐다. 다음 영상도 같은 키워드 전략 시도 권장."
이런 인사이트를 사이드바에 매일 새로 띄워서, **대시보드를 켜자마자 "오늘 뭘 해야 하는지"가 보이도록**.
### 2. 데이터 기반 영상 기획
"지금까지 검색 유입이 잘 됐던 영상들의 제목/태그/길이 공통점"을 분석해서, **다음 영상을 기획할 때 데이터 기반 결정**이 가능하게.
결국 분석 대시보드 → 행동 안내 시스템으로 진화시키는 게 다음 목표다.
## 📋 재사용 가능한 프롬프트
### 프롬프트 1: 외부 API의 한계 먼저 파악하기
> [API 문서 URL 또는 플랫폼 이름]의 공식 문서를 정확히 읽고, 다음을 정리해줘:
> 1. 받을 수 있는 데이터 종류
> 2. **받을 수 없는 데이터 (가장 중요)**
> 3. 호출 제한 (쿼터, 일일 한도)
> 4. 데이터 지연 (실시간인지, 며칠 늦는지)
> 5. 인증 방식과 만료 정책
>
> [플랫폼]은 본인이 분석하려는 외부 서비스로 바꿔서 쓰세요. (예: YouTube Analytics, 인스타그램 Graph API, 네이버 검색광고)
### 프롬프트 2: PRD를 가상 전문가 팀에게 재검증 받기
> /kkirikkiri [도메인] 전문가 관점으로 prd 체크해봐
>
> [도메인] 자리에 본인 프로젝트의 도메인을 넣으세요. (예: 유튜브, 이커머스, SaaS 운영) 검토 관점 선택지가 나오면, 본인 프로젝트에서 가장 위험할 것 같은 시점을 골라주세요 (예: API 제약, 사용자 시점, 데이터 일관성).
### 프롬프트 3: 단단한 PRD가 있을 때 큰 단위 위임
> 위 PRD 기반으로 Phase 1 작업 N개를 한 번에 진행해줘. 단,
> 1. 각 작업 시작 전에 어떤 파일을 만들/수정할지 한 줄로 알려줘
> 2. PRD에 명시되지 않은 부분은 임의로 결정하지 말고 나에게 물어봐
> 3. 마지막에 type-check + 동작 확인까지 같이
>
> N은 본인 작업 개수로 바꿔서 쓰세요.
### 프롬프트 4: 환경 문제 빠르게 진단
> [에러 메시지 or 증상] 발생했는데, 원인 진단하고 해결 명령어까지 한 번에 알려줘. 운영체제는 [Windows/Mac/Linux].
>
> 예: "포트 3000이 다른 프로세스에게 점유돼 있다. 운영체제는 Windows."
