VibeCraft: AI 기반 원샷 대시보드 생성 에이전트

동기

스쿠버 다이빙을 하다 보니 어종 정보를 한자리에서 보고 싶어졌고, GBIF 에서 받은 FishBase 데이터 46만 건으로 지도 기반 도감을 만들어 본 적이 있습니다. 프롬프트 한 번으로 나왔습니다. 이걸 대학 동기들에게 보여 준 게 공모전 아이디어의 출발점입니다. 2021년에 함께 대회를 다니던 친구들이고, 졸업 뒤로는 4년 만이었습니다.

한 번 쓰고 버릴 수도 있었는데 CLI 로 뽑아 npm 에 올린 이유는 민관협력 공모전이었기 때문입니다. 다른 사람이 집어 들어 쓸 수 있는 형태여야 한다고 봤고, 그래서 Apache-2.0 으로 공개했습니다. 결과는 특별상이었습니다.

팀에서는 제가 에이전트 코어를 맡았습니다. 다른 팀원들이 웹에서 데이터를 받아 SQLite 로 가공하고 요구사항을 프롬프트로 정제해 넘겨주면, 그때부터 대시보드가 나올 때까지가 제 몫입니다.

내가 담당한 트랙

에이전트 코어 전체가 제 몫입니다 — 원샷 프롬프트 아키텍처, MCP 서버 연동, SchemaAnalyzer, 시각화 템플릿 4종, CLI 와 npm 배포까지. 항목별 내역은 오른쪽 「주요 업무」에 있습니다.

한 번에 안 되던 지점

원샷이 실제로 걸린 곳은 빌드였습니다. 코드가 그럴듯하게 나와도 npm install && npm run dev 가 안 되면 아무 소용이 없는데, LLM 이 매번 같은 자리에서 미끄러졌습니다.

그래서 돌려 보고 깨진 것을 지침에 적어 넣는 일을 반복했습니다. 시스템 프롬프트(GEMINI.md)에 쌓인 항목이 그 기록입니다.

• sql.js 의 wasm 파일을 없는 로컬 경로에서 찾는 것 — CDN 경로를 못박았습니다
• Vite 가 public/ 을 루트로 서빙하는데 /public/data.sqlite 로 fetch 하는 것
• JSX 본문의 부등호를 안 이스케이프해 구문 오류를 내는 것
• tsconfig.json 의 include 에 vite.config.ts 를 넣어 타입 검사가 깨지는 것

패키지 버전도 템플릿마다 package.json 을 통째로 적어 고정했습니다. 버전을 열어 두면 조합이 매번 달라지고, 그중 하나가 어긋나면 다시 빌드가 안 됩니다.

지침에는 순서도 적었습니다. 코드를 쓰기 전에 MCP 도구로 실제 데이터를 먼저 보라는 것입니다. describe_table 로 컬럼을 확인하고, read_query 로 열 개쯤 뽑아 실제 값을 보고, 집계를 한 번 돌려 분포를 본 다음에 쿼리를 쓰라고 단계까지 적어 뒀습니다. 스키마를 프롬프트에 텍스트로 넣어 주는 것만으로는 부족했습니다. 넣어 준 것을 믿고 쓰는 것과, 미심쩍을 때 직접 확인해 보는 것이 다릅니다.

생성 전후의 검증

원샷에는 중간에 고칠 기회가 없습니다. 사람이 결과를 보고 다시 시키는 순간 원샷이 아니게 되므로, 검증을 생성 앞뒤로 나눠 붙였습니다.

앞쪽에서는 넘어온 SQLite 를 먼저 열어 테이블과 행 수를 확인합니다. 스키마가 비어 있거나 읽히지 않으면 Gemini 를 부르지 않고 그 자리에서 멈춥니다. 뒤쪽에서는 생성된 디렉터리가 실제로 돌아갈 물건인지를 여덟 가지로 봅니다. package.json 이 있고 파싱되는지, 이름·버전·의존성 필드가 채워졌는지, React 앱 구조와 index.html 이 있는지, SQLite 파일이 제자리에 복사됐는지, 필수 의존성과 시각화 라이브러리가 들어갔는지, README 가 있는지입니다.

이걸 붙인 뒤로 실패가 “돌려 봐야 아는 것” 에서 “끝날 때 목록으로 나오는 것” 으로 바뀌었습니다.

아키텍처와 프롬프트 계층의 상세는 VibeCraft: 민관협력 공모전 특별상 수상기 에 따로 적었습니다.

배운 점

• 프롬프트를 다듬는 일은 문장을 고르는 작업일 거라고 생각했는데, 실제로 한 것은 돌려 보고 깨진 자리를 금지 항목으로 적어 내려가는 일이었습니다. 지침이 길어질수록 결과가 안정됐고, 그 목록은 제가 밟아 본 실패를 그대로 옮긴 것입니다.
• 자동으로 고칠 기회가 없으니 검증이 양 끝으로 밀려났습니다. 들어오는 데이터를 먼저 막고 나가는 결과물을 나중에 재는 형태가 됐는데, 재시도를 못 붙인다는 제약이 어디에 무엇을 둘지를 정해 줬습니다.

대학 때 팀을 이뤄 대회를 다니던 친구들과 4년 만에 다시 해 본 것이 이 프로젝트에서 제일 기억에 남습니다.