소개
지난 주 mvpgen 기본 구조는 아이디어 한 줄에서 Plan → Plan critic → Build → Build critic → 최종 검증 순으로 MVP 폴더까지 만드는 파이프라인이었습니다. 핵심은 "만드는 시스템과 그 검증"으로 critic과 루프로 결과물을 끝까지 가져오는지에 집중했습니다. 무한반복 실행환경을 위해 GitHub Actions 사용, 마지막까지 개발을 마치고 각 단계별 검증 점수와 비용까지 기록으로 볼 수 있었습니다.
마지막으로 다음의 3가지를 변경 보완 했습니다.
실행환경 변경
디자인 시안 3가지를 제안 사용자의 선택하도록 하는 디자인 단계
어떤 API든 supabase 적재까지 완성하는 데이터 단계
초입 인터뷰 단계 + 작성된 스펙을 2~3개로 그리고 그것에 대한 조사와 검증
최종 구조도는 다음과 같습니다.
진행 방법
실행환경 및 mvp 형식 변경
부분적인 변경 실험을 여러번 하기에는 끝까지 돌아가는 Githun Actions 환경이 소모적이어서 로컬로 환경을 바꾸고 SDK도 Claude API 에서 구독제로 변경했습니다. 개인용으로 사용할경우 구독제가 지원됩니다.
src/mvpgen/identity.py의 detect_auth()를 바꿈 #claud 구독제
mac 이 꺼지지 않도록 caffeinate 설정 시안 9개를 보여주는 디자인 단계 추가
이 단계를 추가하고 싶었던 이유는 에이전트가 자료 조사, 스펙에 맞는 디자인을 알잘딱깔센으로 골라서 기능까지 더해서 보여줄 수 있는지에 대한 실험이었습니다.
아이디어에 적합한 디자인을 일반 웹서치가 아닌 design.md를 제공하는 레퍼런스 사이트로 한정, 아이디어에 맞는 옵션 3가지에 서비스 이용자가 무엇을 이용하게 할지에 대한 옵션 3가지로 총 9가지 시안을 보여줍니다.
claude가 처음엔 라이브러리 전체 목록(INDEX.md)을 보고 직접 고르게 했고 그 다음 커밋에서 레퍼런스 사이트 원천을 design-sources.toml로 정리하네요.
만드는 게 웹사이트면 웹사이트 레퍼런스 사이트, 앱이면 앱 UI와 UX 레퍼런스 사이트로 나뉩니다.
Refero Styles: 2,000개 이상, 그러나 실제로 가져올 때 유료 이슈
designmd.app: 759개, 공개 API가 있어요.
VoltAgent awesome-design-md: 86개로 처음엔 이걸 다 다운받아 무작위 선택을 해보기도 했죠.역시 무작위는 안됩니다.
awesome-ios-design-md: 앱용이에요.
"의외성" 정의하기
결과물이 너무 뻔하지 않았으면 했습니다.그래서 처음엔 프롬프트에 "의외성"을 넣어 한번 돌린 후에 그것에 대한 피드백으로 "의외성"이 어떤 방향성인지 잡도록 했습니다. 디자인은 아이디어의 성질에 맞는 통계적으로 흔한 모양을 따르되, 서비스 이용자가 어떤 정보를 얻을지는 낯설게 보여 주는 것으로 했습니다. 방향 프롬프트에는 의외성이 "분야에 어울리는 스타일 중 흔하지 않은 표현"이라고 적혀 있어요. 미리보기는 previews/<id>.html로 만들고, 글자와 배경의 대비는 4.5 이상인지 코드로 검사합니다.
디자인 적용 전 mvpgen 최종
한국사이트 스크린샷
Supabase 적재까지 스스로 하게 만들기
데이터 단계의 목적은 어떤 API를 줘도 데이터 적재까지 정해진 단계를 스스로 풀게 하는 것입니다.
1차 실행은 성공했어요. 전시 정보 API(MMCA) 문서만 받아 Supabase에 적재하는 파이프라인을 만들었습니다. 시작할 때 Supabase 프로젝트를 나보고 만들래서 "Supabase cli 있으니 네가 만들어라" 한 이후로 엄청난 토큰을 먹으며 열심히 만들더니 모델을 쓰지 않는 최종 검증 5페이지도 모두 통과했습니다.
만들어진게 작동하면 새로운 api 를 넣으면 자동으로 정보를 가져오고 적재하고 프론트 엔드에 전달해?
그냥 물어본 건데 mvpdata라는 별도 진입점을 만들더군요. 이걸 전체와 어떤 구조로 가져갈지가 사후 문제로 남았습니다. claude 가 내게 너무 물어도 문제고 안물어도 문제입니다. 단계는 data-plan, data-build, 최종 검증으로 데이터가 구조가 plan에 들어갈 수 있게 되었습니다.
전체 구조를 어떻게 할 것인가
디자인과 데이터단계를 구성하면서 메인에서는 기존에 없었던 2가지, 아이디어 한줄에서 인터뷰로 그리고 spec critic 을 넣고 각 단계별로 사용할 모델을 달리했습니다.
최종 mvpgen 구성
단계마다 새 Claude 세션을 띄우고, 결과는 파일로 넘깁니다.
1. 인터뷰(Claude Code 세션): brief.md
2. PRD와 PRD critic
3. spec 후보 2개, 후보별 조사, spec critic의 거르기
4. 디자인 원천 찾기, 방향 3개와 미리보기
5. 멈춤: 사람이 구현 후보와 디자인 방향을 고른다(awaiting_choice, 종료 코드 3). --resume --choose-spec --choose-design으로 이어 간다
6. spec 다듬기(지적이 남았을 때만), DESIGN.md
7. Build와 Build critic
8. 최종 검증: 모델 없이 코드가 설치, 테스트, 실행, smoke를 확인한다
한국어의 다양한 유형을 보여주는 다이어그램
데이터 모드(mvpdata)는 같은 틀을 씁니다. data-plan, API 샘플(코드가 대신 받음), data-build, 최종 검증(DB에 적용하고 적재를 두 번 확인) 순서입니다. 이미 DB에 적용한 마이그레이션은 파일만 되돌릴 수 없어서 점수가 떨어져도 되돌리지 않습니다.
검증은 네 겹입니다.
세션 안: 끝내려 할 때 검사를 돌려 실패하면 못 끝내게 하는 Stop 게이트(최대 3회), 위험 명령과 쓰기 경로와 비밀값을 막는 가드
세션 밖: 만든 쪽과 맥락을 공유하지 않는 독립 critic. 80점 이상이고 critical이 없어야 합격이고, 불합격이면 지적을 넘겨 다시 만든다(두 번까지). 점수가 떨어지면 최고점 라운드로 되돌린다
사람의 선택
실행 사이: 지적을 lessons.md에 쌓아 다음 실행의 프롬프트에 넣는다
최종 실행: brief로 끝까지 돌려 보기
인터뷰부터 시작, Claude Code 세션에서 /grilling으로 질문을 두 번(12개) 받고 brief.md를 만듭니다. 고르는 방식은 일부러 열어 두었고, 디자인 선호는 적지 않았습니다. 파이프라인이 스스로 어떤 방향을 내놓는지 보고 싶었습니다.
한국어 텍스트가 있는 페이지의 스크린샷
한국사이트 스크린샷
모든 단계 Opus, 예산 $10에서 $15, $25로 올림, 합계 $19.15. 단계별 모델은 --stage-model로 정할 수 있지만 이번에는 쓰지 않았습니다. (금액은 SDK가 계산한 추정치)
한국어 한국어 한국어 한국어 한국어 한국어 한국어 한국어
PRD: 84점 합격
spec 후보 2개: 앱이 두 전시를 먼저 걸고 한 자리씩 바꾸는 방식(a), 오늘 전시 전부를 두 개씩 짝지어 안내도로 보여 주는 방식(b). 후보별 조사와 거르기 뒤 둘 다 실행 가능, a 84점 / b 72점, 추천은 a
디자인: 레퍼런스 사이트에서 원천 5개를 찾고, 방향 3개(화이트큐브, 전시 도록, 리소 인쇄 리플렛)를 미리보기로 만든 뒤 멈춤
사람의 선택: 디자인은 제가 리소 인쇄 리플렛(C)을 골랐고, 구현은 추천 a를 그대로 썼습니다.
Build critic 90점, 앱 테스트 38개 통과, 최종 검증 통과
파이프라인 결함 두 개
하나는 단계를 시작한 AI 세션이 제 개인 메모(Claude Code 자동 메모리)를 읽고 있던 것입니다. brief에서 일부러 뺀 디자인 선호가 들어가면 실험이 의미를 잃어서 환경변수로 막았습니다.
다른 하나는 채점 AI가 화면 캡처를 읽다가 SDK의 메시지 크기 한도(1MB)를 넘어 죽은 것입니다. 한도를 16MB로 올려 해결했습니다.
당연히 너무 아쉬운 점도 있습니다. 결과 화면의 "오늘의 2인전", "나머지 벽", "캡션" 같은 제목이 납득되지 않았습니다. PRD가 "오늘 갈 곳 한두 곳, 고르는 방식이 핵심, 의외성은 전시 분야 안의 표현"을 한꺼번에 받아 핵심 기능의 이름과 규칙까지 정해 버렸기 때문입니다. 그래서 spec 후보 둘도 모두 그 틀 안에서만 달랐습니다. 다음에는 PRD가 고르는 규칙과 이름을 정하지 않게 바꿀 계획입니다.
한국어 텍스트가 있는 페이지
기타
들여다 볼수록 더 했으면 하는게 생겨서 끝이 안날것처럼 보입니다. 하지만 애초에 Claude Agent SDK를 사용해서 각 부분에 대한 여러 실험을 해도 체계적으로 돌아가는거 같습니다.
단계마다 스킬을 적용해 더 세세하게 작동하게 하는 것까지 하지 못했습니다.
만들어진 전시앱은 그냥 claude code 상에서 바이브코딩 워크플로우로 요구사항 꼼꼼히 써서 주고, 레퍼런스 이미지 넣어주는것보다 못합니다. 저는 mvp보다는 이 시스템을 만들어보는게 목적이었습니다. 어느 과정에서 바이브 코딩할때 꼬이는지를 알고, 결과물에서 정보에 대해 충분히 알고 있는 것으로 택했습니다.
그래프 엔지니어링 궁금해서 스터디에서 Google ADK 만들어보고 싶었습니다. 하지만 Claude SDK를 해본건 claude 의 추천대로 좋은 선택이었습니다.
결과와 배운점
루브릭은 과정별로 다시 설계해야 합니다.
SDK에 이미 구축된 단계에서 spec 단계에서 조사를 넣은 것은 기존 시스템에서 작동하지 않고 오히려 토큰만 더 들어갔습니다.
이것 저것 해보면서 처음으로 로컬에서 git 을 제대로 써보게 되었습니다.