Claude Code 개인 프로젝트 실습

본인 서비스의 첫 사용자 결과를 AI 협업 워크플로우로 구현하고, 배포 뒤 다음 작업이 시작할 상태로 정리합니다

Overview

Feedme에서는 주어진 방향과 요구사항을 따라갔지만, 개인 프로젝트에서는 무엇을 먼저 완성할지 스스로 좁혀야 합니다. 작업이 둘 이상으로 늘어나면 Worktree로 작업 나누기에서 익힌 대로 세션을 나눠 동시에 진행해도 좋습니다.

이번 Lesson에서는 자신의 아이디어에서 사용자 결과 하나를 선택하고, 새 대화가 이어받을 기준을 남기며 실제 배포 결과까지 독립적으로 완성합니다. 완료 뒤에는 다음 작업이 현재 상태에서 바로 이어질 수 있게 정리합니다.

학습 목표

대략적인 서비스 방향을 구체화해 PRODUCT.md로 남깁니다.
이번에 완성할 사용자 결과 하나를 정해 spec.md로 남깁니다.
AI 협업 워크플로우를 처음부터 끝까지 독립적으로 완주합니다.

시작하기 전 확인사항

본인 사이드 프로젝트를 담을 새 GitHub 저장소를 프로젝트 셋업 레슨 절차에 따라 claude-code-playbook-template에서 만들고 Vercel 첫 배포까지 확인합니다.
사용할 외부 API 키(AI 게이트웨이·공공데이터 등)가 있다면 미리 발급받아 .env.local에 넣어둡니다. Supabase는 본문의 setup-supabase Skill로 설정합니다. 자세한 키 등록 방법은 배포 시 환경 변수 설정하기에서 다룹니다.

대략적인 서비스 방향 고르기

define-product는 백지에서 아이디어를 발굴하는 Skill이 아닙니다. 다음 중 하나 이상의 대략적인 방향을 먼저 준비합니다.

누구를 위한 서비스인지
어떤 상황이나 불편을 다루고 싶은지
사용자에게 무엇이 달라지면 좋은지
어떤 방식으로 문제를 풀고 싶은지

이미 만들고 싶은 서비스가 있다면 서비스 전체 방향 정리로 넘어가 한두 문장으로 입력하면 됩니다. 아직 없다면 평소의 불편이나 관심 분야를 떠올리거나, 아래의 AI·API 조합 예시에서 누구에게 어떤 결과를 줄지 대략적인 사용 장면 하나를 고릅니다. 이 단계에서는 자세한 기능 목록까지 정하지 않아도 됩니다.

AI와 데이터 API 고르기

요즘 사이드 프로젝트는 AI 기능 한 줄만 붙여도 결과물이 크게 달라집니다.

AI 모델

AI 기능을 넣을 계획이라면 제공자마다 키를 발급받지 말고 게이트웨이 한 곳에 소액을 충전합니다. 키 하나로 여러 모델을 부를 수 있어서, 싼 모델부터 써 보고 결과가 아쉬울 때만 코드에서 모델 이름을 바꾸면 됩니다.

Vercel AI Gateway나 OpenRouter를 씁니다. 프로토타입 단계에서는 $5면 충분합니다.

Backend·Database

아래 서비스는 모두 무료로 시작할 수 있고, 키 발급도 보통 5분 안에 끝납니다.

서비스	무료 한도	어디에 쓰면 좋은가
Supabase	프로젝트 2개, DB 500MB, Auth 무료 MAU 한도 넉넉	Postgres + Auth + Storage가 한 묶음. CRUD가 필요한 사이드 프로젝트에 자주 쓰는 조합

Supabase 설정은 템플릿의 Skill에 맡깁니다

프로젝트 템플릿에는 setup-supabase Skill이 이미 들어 있습니다.

/setup-supabase

이 프로젝트에 Supabase를 설정해줘.

이 Skill은 기존 설정을 먼저 확인하고 Supabase Cloud 연결과 Auth 사용 여부를 묻습니다. 선택한 범위에 필요한 공식 Supabase Skill을 준비한 뒤 설정과 실제 동작 검증까지 진행합니다. 로그인·동의·보안 정보 입력이 필요하면 안내에 따라 직접 진행합니다.

해외 데이터·이미지

서비스	인증	어디에 쓰면 좋은가
Open-Meteo	없음	날씨 데이터. 사실상 무제한
REST Countries	없음	국가 정보 (국기·통화·언어 등)
NASA APIs	이메일로 키 발급	오늘의 우주 사진, 화성 로버 사진 등
Unsplash	회원가입 + 앱 등록	고화질 이미지 시간당 50번 호출

한국 데이터

서비스	인증	어디에 쓰면 좋은가
공공데이터포털	회원가입 + API별 활용신청	기상청 단기예보, 미세먼지, 박스오피스, 실시간 버스 등 수천 개
카카오 디벨로퍼스	앱 등록 (REST 키)	카카오 지도, 로컬 (장소 검색), 카카오 로그인
네이버 개발자센터	앱 등록 (Client ID/Secret)	블로그·뉴스·책 검색, 파파고 번역
서울 열린데이터광장	회원가입 + 키 발급	따릉이, 지하철 혼잡도, 문화행사
한국은행 ECOS	회원가입 + 키 발급	환율, 금리, 물가지수

AI와 데이터 조합 예시

혼자서는 평범해 보이는 API도 AI와 조합하면 결과물이 확 달라집니다.

AI + Open-Meteo: 오늘 날씨에 맞춰 옷차림을 한 줄로 추천하는 AI 비서
AI + 기상청 단기예보: 한국 위치 기반으로 "오늘 우산 챙겨?" 답해주는 챗봇
AI + 카카오 로컬 API: "강남역 근처 조용한 카페 3곳"을 골라주는 AI 큐레이터
AI + 영화진흥위원회 박스오피스: 어제 박스오피스 1위 영화에 AI가 쓴 한 줄 평 붙이기
AI + 네이버 검색 API: 키워드를 넣으면 최신 블로그·뉴스를 빠르게 요약

더 많은 API 살펴보기

open-apis-korea: 한국어 사용자를 위한 오픈 API 모음
public-apis-4Kr: 한국 서비스에 사용 가능한 Public API 목록

서비스 전체 방향을 `PRODUCT.md`로 정리하기

Feedme에서 실행한 것처럼, 대략적인 방향을 골랐다면 define-product를 실행합니다. 이번에는 다음처럼 자신의 생각을 명령 아래에 함께 입력합니다.

/define-product

날씨에 맞춰 오늘 입을 옷을 추천하는 서비스

define-product는 실제 사용 상황에서 출발해 사용자, 문제, 지금 사용하는 대안, 약속할 변화와 반복되는 사용자 흐름을 하나씩 묻습니다. 답변을 바탕으로 정리한 전체 방향을 먼저 보여주며, 사용자가 확인한 뒤에만 프로젝트 루트의 PRODUCT.md를 만듭니다.

<프로젝트 루트>/
└── PRODUCT.md

PRODUCT.md에는 서비스 전체가 앞으로 지켜야 할 방향을 남깁니다. 개별 화면의 상세 요구사항, 기술 구조나 이번에 구현할 기능 목록은 넣지 않습니다.

한 번에 구현하고 검증할 사용자 결과로 좁히기

서비스 전체를 한 번에 만들려 하지 마세요. 이번 작업에서 완성할 사용자 결과 하나를 정합니다. shape-idea는 PRODUCT.md에서 관련 방향을 읽고, 그 결과의 동작과 완료 기준을 spec.md로 만듭니다.

/shape-idea

이 서비스에서 먼저 완성할 사용자 결과 하나를 정하고 싶어.
한 번에 구현하고 실제 동작으로 검증할 수 있는 범위로 좁혀줘.

대화가 끝나면 docs/specs/<slug>/spec.md에서 이번 작업의 사용자 동작과 완료 기준을 확인합니다.

명세에 서로 독립적으로 완성할 수 있는 사용자 결과가 여러 개라면 split-into-tasks를 사용합니다.

나눌 필요가 있을 때만 다음 명령을 실행하고, 제안된 Task를 확인한 뒤 승인합니다.

/split-into-tasks @docs/specs/<slug>/

구현하고 검증하기

승인한 Task가 있으면 tasks/의 문서를, 없으면 spec.md를 그대로 구현합니다.

/implement @docs/specs/<slug>/

implement는 완료 기준을 충족할 때까지 구현과 검증을 이어갑니다. 테스트와 빌드가 통과해도 실행한 서비스에서 바뀐 동작을 확인하지 못했다면 끝난 것이 아닙니다. 이번 작업에서 고치지 못한 문제는 docs/follow-ups/에 남습니다.

결과 검토하기

/human-review

검토 화면에서 완성된 결과와 검증 근거를 확인하고, 남은 질문에 답합니다. 수정할 점을 그 자리에서 전달하면 AI가 구현과 검증으로 이어갑니다.

배포하기

환경 변수 설정하기

프로젝트에 외부 API 키(Supabase URL 등)가 있으면 환경 변수를 설정합니다.

로컬: Next.js는 프로젝트 루트의 .env.local 파일에서 환경 변수를 읽습니다. NEXT_PUBLIC_ 접두사를 붙인 변수만 브라우저에서 읽을 수 있습니다. API 키처럼 노출되면 안 되는 값에는 이 접두사를 붙이지 않습니다.

Vercel: 대시보드에서 프로젝트를 열고 사이드바의 Environment Variables로 들어가 Key/Value를 등록합니다.

Vercel 프로젝트 설정의 Environment Variables 화면

.env.local의 내용을 그대로 붙여넣거나 파일을 올려 한 번에 등록할 수도 있습니다.

.env 내용을 붙여넣어 환경 변수를 한 번에 등록하는 화면

양쪽에 등록하고, 등록한 뒤 다시 배포합니다

.env.local의 값을 Vercel에도 같은 이름으로 등록해야 프로덕션에서 동작합니다. 환경 변수는 새 배포부터 적용되므로 이미 올라간 배포에는 반영되지 않습니다.

배포하고 확인하기

Claude Code에 커밋과 push를 요청합니다.

지금까지 변경 사항을 커밋하고 main 브랜치에 push해줘.

프로젝트 셋업에서 Vercel을 연결해 뒀으므로 push하면 .vercel.app 주소가 다시 배포됩니다. 주소를 열어 spec.md의 완료 기준이 실제로 동작하는지 확인합니다.

배포 뒤 다음 작업 준비하기

배포가 확인되면 배포 뒤 프로젝트 이어가기에서 Feedme에 적용한 종료 판단을 자신의 프로젝트에도 반복합니다.

docs/follow-ups/에 기록이 있다면 각 파일을 먼저 읽고 다음처럼 분류합니다.

재현 절차와 해결 방향이 확정된 문제: resolve-follow-ups
제품 판단이 더 필요한 문제: shape-idea
근거가 부족하거나 재현되지 않는 문제: 기록을 유지하고 근거를 더 모으기

별도 문제가 없다면 follow-up이 없다는 판단을 명시하고 이 단계는 건너뜁니다. resolve-follow-ups는 첫 번째로 분류한 항목에만 실행합니다.

/resolve-follow-ups

이번 사용자 결과가 배포된 URL을 확인한 뒤 <slug>와 <배포 URL>을 실제 값으로 바꿔 완료된 Spec과 프로젝트 맥락을 정리합니다.

/maintain-project-context

docs/specs/<slug>/spec.md에 해당하는 변경은 <배포 URL>에 배포가 완료됐어.
다음 작업에서도 재사용할 결정은 보존하고, 배포가 끝난 Spec과 중복된 프로젝트 맥락을 정리해줘.

변경 내용을 검토해 재사용할 결정만 현재 문서에 남고 완료된 Spec 폴더가 삭제됐는지 확인한 뒤 커밋하고 push합니다.

실습 규칙 지키기

사용자 결과 하나를 먼저 완성하기: 기능을 늘리기 전에 사용자가 시작부터 결과까지 실제로 이용하고 검증할 수 있는지 확인합니다.
새 도구 하나씩 추가하기: Supabase 연동을 확인한 뒤 Vercel 배포를 시도합니다. 여러 도구를 한꺼번에 추가하면 문제가 생겼을 때 원인을 찾기 어렵습니다.

결과물 공유하기

실습이 끝나면 본인 프로젝트를 claude-hunt.com에 업로드합니다.

오프라인 수강생: 강의 마지막 날 오후 5시까지 올리면 그날 투표 대상이 됩니다.
온라인 수강생: 완성하는 대로 올리면 그달 말일 투표 대상이 됩니다.

FAQ

이어서 배울 내용

개인 프로젝트 실습이 끝나면 Part 3 전체를 정리합니다.

내 아이디어 구현하기 | Practice