Claude Code와 로컬 서비스앱 MVP를 만들 때의 기본 절차

바이브코딩Claude Code로컬MVPSOPAI협업개발

이 글은 Claude Code와 함께 로컬 서비스앱 MVP를 만들 때 반복 사용할 수 있는 절차를 정리한 가이드입니다. SOP(Standard Operating Procedure) 형식의 실행 절차로 구성했습니다.

쇼츠/릴스 생성기 로컬 MVP(v0.1.0~v0.1.4)를 만들며 직접 검증한 흐름을 바탕으로 작성했습니다.

이 절차를 언제 사용하는가

  • 코드를 깊게 알지 못해도 로컬에서 작동하는 앱을 만들고 싶을 때
  • Claude Code와 협업해 MVP를 만들되, 방향과 판단은 운영자가 주도하고 싶을 때
  • 반복 가능한 개발 흐름을 만들고 운영 자산으로 남기고 싶을 때

01 — 운영자와 Claude Code의 역할 분리

시작 전에 역할을 명확히 정한다.

역할담당
목적 정의, 우선순위 판단운영자
완료 기준 설정운영자
기능 검증 (실제로 작동하는지 확인)운영자
코드 구조 설계, 구현Claude Code
오류 진단 및 수정Claude Code
문서 초안 작성Claude Code (운영자 검토 후 확정)

역할이 섞이면 검증 없이 기능이 쌓이거나, 완료 기준 없이 개발이 지속된다.

02 — 목적과 완료 기준 먼저 정하기

코드 요청 전에 다음을 정한다.

  • 목적: 이 MVP를 왜 만드는가? 어떤 문제를 해결하는가?
  • 핵심 기능: 1단계에서 반드시 작동해야 하는 기능은 무엇인가?
  • 완료 기준: 어떤 조건이 충족되면 1단계를 완료로 판단할 것인가?
  • 2단계 후보: 지금 당장 필요하지 않지만 나중에 검토할 기능은?

완료 기준이 없으면 MVP는 끝나지 않는다.

03 — 기술 구조 나누기

구현 전에 기술 구조를 정한다. Claude Code에게 맡기기 전에 어떤 기술 스택을 쓸지 방향을 정하면, 나중에 구조를 대규모로 바꾸는 일이 줄어든다.

일반적인 로컬 서비스앱 구조 예시:

영역선택지 예시
프론트엔드Next.js, React
백엔드FastAPI (Python), Express (Node.js)
처리 엔진FFmpeg (영상), Pillow (이미지), 기타 라이브러리
실행 방식로컬 개발 서버 (프론트/백 병렬 실행)

04 — 최소 기능부터 구현하기

첫 번째 구현 요청은 가장 핵심 기능 하나만 포함한다.

예시: “사진을 업로드하면 9:16 세로 MP4를 생성한다”

이 하나가 작동하면 다음 기능으로 넘어간다. 처음부터 모든 기능을 한꺼번에 요청하면 오류가 쌓이고 디버깅이 어려워진다.

05 — 프론트엔드/백엔드 서버 실행 확인

각 버전에서 서버가 정상 실행되는지 먼저 확인한다.

  1. 백엔드 서버 실행 확인 (예: uvicorn main:app --reload)
  2. 프론트엔드 서버 실행 확인 (예: npm run dev)
  3. 브라우저에서 접근 확인
  4. 기본 기능(파일 업로드, 다운로드 등) 작동 확인

서버가 뜨지 않는 상태에서 기능을 테스트하려 하면 불필요한 혼란이 생긴다.

06 — 기능 테스트 순서

기능을 테스트할 때는 다음 순서로 진행한다.

  1. 정상 입력으로 기본 기능이 작동하는지 확인
  2. 극단적인 입력(빈 파일, 너무 큰 파일, 지원하지 않는 형식)으로 오류 처리 확인
  3. 여러 기능이 함께 사용될 때(예: BGM + 전환 효과 + 캡션 동시 적용) 작동 확인
  4. 결과물(MP4 파일 등)이 실제로 재생되는지 직접 확인

테스트는 직접 써봐야 한다. 코드가 오류 없이 실행된다고 해서 기능이 의도대로 작동한다는 뜻은 아니다.

07 — 오류 발생 시 확인 순서

오류가 생기면 다음 순서로 확인한다.

  1. 브라우저 콘솔 오류 메시지 확인
  2. 백엔드 서버 터미널 오류 로그 확인
  3. 오류 내용을 정확하게 복사해서 Claude Code에게 전달

08 — Claude Code에게 오류를 전달하는 방식

“안 돼요” 또는 “오류가 났어요”만 전달하면 Claude Code가 문제를 파악하기 어렵다.

다음 형식으로 전달한다.

[어떤 기능을 테스트했는지]
[어떤 입력을 사용했는지]
[어떤 오류 메시지가 나왔는지 — 전체 텍스트 복사]
[예상했던 결과는 무엇인지]

오류 메시지를 정확하게 전달할수록 해결 속도가 빠르다.

09 — 문서화: 1단계의 일부로 포함하기

문서화는 개발이 끝난 뒤 추가하는 것이 아니라 1단계의 일부다.

문서목적
README.md프로젝트 개요, 실행 방법
CHANGELOG.md버전별 변경 이력
docs/LOCAL_RUN.md로컬 실행 절차
docs/FEATURES.md기능 목록과 사용 방법
docs/KNOWN_ISSUES.md알려진 문제와 우선순위
docs/ROADMAP.md2단계 후보 기능

문서화가 없으면 동일한 환경을 재현하거나 2단계를 시작할 때 처음부터 다시 파악해야 한다.

10 — 1단계 완료와 2단계 보류 구분

1단계 완료를 판단하는 기준을 정하고, 그 기준을 충족했을 때 완료로 선언한다.

완료 판단 기준 예시:

  • 핵심 기능이 실제로 작동한다
  • 최소 편집 기능이 갖춰졌다
  • 문서화로 재현 가능한 상태다

2단계 보류 기준:

  • 지금 없어도 핵심 목적은 달성된다
  • 구현 난이도에 비해 현재 단계에서 검증이 어렵다
  • 배포나 멀티 사용자 대응이 필요한 기능이다

“있으면 좋겠다”는 기능을 모두 1단계에 넣으려 하면 MVP가 완성되지 않는다.

11 — 공개 전 민감정보 점검

로컬 환경에서 개발하면 민감한 정보가 코드에 포함될 수 있다.

공개 전 반드시 확인:

  • API 키, 비밀번호, 토큰이 코드에 하드코딩되어 있지 않은지
  • 로컬 경로나 사용자명이 문서에 포함되어 있지 않은지
  • 내부 브랜드명, 계정 정보가 노출되지 않는지

환경변수(.env)로 분리하고, .gitignore에 포함시킨다.

관련 Log: 쇼츠/릴스 생성기 로컬 MVP 1단계 완료 기록
관련 Insight: AI와 함께 MVP를 만들 때 운영자가 붙잡아야 할 것은 코드가 아니라 판단이다

← 모든 가이드 보기