mvper 개요 — 자연어로 MVP를 뽑아내는 클로드 코드 지침

description: 회피형 인간의 가동률 최적화 프로젝트 1편
date: 2025-02-19
tags: [mvper, claude-code, MVP, 생산성, 개발도구]

---

이 글은 선언문의 후속이다. 선언대로 굴리기 위해 만든 첫 번째 도구, mvper를 소개한다.

---

한 줄 정의

mvper는 자연어 요청을 받아 즉시 실행 가능한 MVP 설계 모델과 동작 스캐폴딩을 자동 생성하는 클로드 코드 지침이다.

"점심 메뉴 고르는 앱 만들어줘"라고 입력하면 설계 문서부터 실제 동작하는 웹앱까지 한 번에 나온다.

---

왜 만들었나

완벽주의로 포장된 회피 패턴에는 구체적인 형태가 있다.

• 아이디어는 있는데 어디서 시작할지 모르겠음
• 구조 설계하다 시간 다 씀
• 기술 스택 고르다 지침
• 결국 아무것도 안 만들고 "다음에"

mvper는 이 루프를 강제로 끊기 위한 장치다. 생각할 시간을 줄이고, 일단 굴러가는 뭔가를 손에 쥐게 만드는 게 목적이다.

---

핵심 철학

Deterministic First, LLM Second.

화려한 AI 기능보다 일단 동작하는 코드가 먼저다. LLM 연동이 필요 없으면 쓰지 않는다. 로컬 로직으로 해결 가능한 건 로컬 로직으로 한다.

70% 완성도에서 출고.

100%는 목표지 출고 기준이 아니다. 3개월 내 결과가 안 나오면 소비다. mvper는 이 기준을 구조로 강제한다.

만들기 전에 먼저 판단.

요청이 들어오면 바로 만들지 않는다. 스크립트 하나로 해결 가능한지, 기존 도구로 충분한지 먼저 판단한다. 만들 필요 없으면 대안을 제시하고 끝낸다.

---

구조 개요

지침은 크게 세 단계로 구성된다.

Stage 1 — 요청 분석: 문제 정의, 핵심 가설 도출, Must/Nice/No-Go 분류, 함정 식별.

Stage 2 — MVP 설계 모델 생성: 12개 섹션으로 구성된 표준 템플릿을 채운다. 기능 범위, DB 스키마, API 명세, 안정성 가드레일, 구현 순서, DoD 체크까지 포함된다.

Stage 3 — 스캐폴딩 코드 자동 생성: 설계 모델 기반으로 즉시 실행 가능한 코드를 뽑는다. README, Makefile, 백엔드, 프론트엔드, 테스트, 배포 설정까지 한 번에.

Stage 2와 3은 항상 순서대로 모두 실행한다. 설계만 하고 멈추는 건 불완전한 응답으로 간주한다.

---

DoD — 완성의 정의

mvper에서 MVP "완성"은 아래 5개를 모두 충족하는 상태다.

• 로컬 원커맨드 실행 (make run 또는 docker compose up)
• 핵심 플로우 e2e 성공
• 오프라인 Fallback 동작
• 필수 예외처리 구현
• 스모크 테스트 1개 통과 (/healthz 200 반환)

나머지 완성도 개선은 No-Go다. 다음 사이클에서 한다.

---

현재 상태

지침은 완성됐다. "점심 메뉴 고르는 앱"처럼 간단한 요청도, 외부 API 연동이 필요한 요청도 처리한다.

구현 과정이 순탄하진 않았다. 토큰 폭발, 컨텍스트 폭발, 시스템 권한 문제, 보안과 속도 사이의 절충 — 그 과정은 2편에서 다룬다.