21장 프로토타입에서 프로덕션으로
Leysys는 기획 단계에서 실제로 동작하는 프로토타입을 만들고, 그 결과를 실제 서비스로 넘깁니다. 프로토타입은 목표 화면과 상호작용의 기준(reference)이지 구현 정본이 아닙니다. 이 장은 프로토타입이 무엇을 넘기고 무엇을 넘기지 않는지 설명합니다.
왜 필요한가
AI 에이전트와 잘 정리된 디자인 시스템 덕분에, 기획 산출물이 그림이 아니라 실제로 동작하는 화면이 됐습니다. 프로토타입이 동작할수록 두 가지 유혹이 생깁니다.
- 프로토타입 코드를 그대로 실제 서비스에 덮어쓰는 것. 데모 계정, 브라우저 저장소, 하드코딩한 데이터가 운영으로 따라 들어갈 수 있습니다.
- 프로토타입에 실제 서비스의 데이터베이스와 인증을 붙이는 것. 실제 서비스를 만드는 팀은 자기 인프라와 이행 방식이 있어 그 코드를 다시 쓰지 않습니다. 셋업과 운영 시간만 듭니다.
그래서 경계를 정했습니다. 프로토타입은 화면·상호작용·업무 규칙을 증명하고, 서버가 맡을 계약은 문서로 넘깁니다.
파이프라인
text
Phase 0 요구사항 스케칭 (PO)
Phase 1 CSS 컴포넌트 + 쇼케이스 (PO + 디자이너)
Phase 2 리뷰와 승인 (PO + CTO)
Phase 3 Vue SFC 구현 (개발자)
Phase 4 시각 QA (PO + CTO)- 부족한 컴포넌트와 패턴은 화면보다 먼저
leysys-design에 만듭니다. 화면에서 임시로 만들지 않습니다 (7장). - Phase 2 리뷰는 EDS 화면을 1440px, MDS 화면을 412px 폭에서 봅니다.
- 개발자는 디자인 시스템의 클래스와 컴포넌트를 가져다 쓰고 업무 로직을 구현합니다.
프로토타입 저장소
프로토타입 저장소에는 -proto 접미사를 붙입니다(19장). 역할은 다음과 같이 나뉩니다.
| 책임 | 정본 |
|---|---|
| 디자인 토큰·CSS·컴포넌트 계약 | leysys-design의 게시된 패키지 |
| 기능·도메인·데이터·권한 | 실제 제품 저장소 |
| 비교할 수 있는 목표 화면과 상호작용 | 대응하는 -proto 저장소 |
프로토타입 코드를 실제 제품에 그대로 덮어쓰지 않습니다. 프로토타입은 잠시 멈춰도 되므로, 구조 변경을 먼저 시험하는 곳으로도 씁니다. 예를 들어 디자인 시스템 패키지 전환은 프로토타입 저장소에서 먼저 했습니다.
프로토타입을 끝낼 때는 둘 중 하나를 고릅니다. 프로토타입 저장소를 참고용으로 보관하고 정식 저장소를 따로 운영하거나, 같은 저장소를 정식으로 바꿀 명확한 이유가 있을 때만 이행 결정 기록을 남기고 이름을 바꿉니다.
저장 원칙
오너가 2026-10-04 KST에 저장소 선택을 이렇게 정했습니다.
| 단계 | 저장소 |
|---|---|
| 프로토타입 | 기본은 브라우저 localStorage, 서버가 꼭 필요한 기능만 Supabase |
| 초기 MVP | Supabase. 초기에 Supabase로 시작한 실제 서비스는 그대로 이어 쓰기도 합니다 |
| 실제 서비스 고도화 | MariaDB |
localStorage를 쓰는 프로토타입에는 실행되지 않는 SQL이나 서버 참고 구현을 새로 두지 않습니다. 역할·권한·데이터의 서버 구현은 실제 백엔드가 맡고, 프로토타입은 그 계약을 인계 문서로 넘깁니다.
Leyve Console은 이 원칙을 이렇게 적용합니다.
- 프로토타입 상태는 localStorage에 둡니다. 저장 키에 앱 접두어를 붙여 다른 앱의 저장분을 읽거나 지우지 않습니다.
- 업무 규칙은 composable(Vue의 로직 함수)에 두고, 저장은 adapter 한 겹 뒤에 숨깁니다. localStorage를 API로 바꿀 때 한 곳만 고치기 위해서입니다. 데이터베이스 호출을 컴포넌트 곳곳에 흩지 않습니다.
- 공개 배포되는 프로토타입의 localStorage는 같은 브라우저의 누구나 읽을 수 있으므로 실제 개인정보와 실제 비밀번호를 넣지 않습니다.
결함은 덧대지 않고 다시 씁니다
일부 제품 저장소는 디자인 정본이 없던 때에 만들었습니다. 그 코드에는 즉석 마크업과 비표준 구조가 남아 있을 수 있습니다. 그런 곳에서 결함을 찾으면 그 자리에서 덧대지 않습니다. 디자인 시스템 컴포넌트·정본 패턴·웹 표준 구조에 맞게 다시 씁니다.
- 임시 JS 헬퍼나 우회로 증상만 덮지 않습니다.
- 오버레이는 native
<dialog>와 Popover API, 드롭다운 위치는 CSS anchor positioning으로 만듭니다. 프레임워크 JS로 표준을 대체하지 않습니다(14장). - 일부 브라우저가 아직 표준을 다 지원하지 않으면, JS로 우회하지 않고 표준의 현재 상태를 받아들입니다.
실제 사례가 있습니다. Leyve Console 안에는 입주민 포털 화면이 있었습니다. 확인해 보니 MDS로 이미 완성된 모바일 포털의 오래된 EDS 사본이었습니다. 새 저장소로 옮기는 계획을 세웠다가, 옮길 코드가 없고 디자인 시스템도 맞지 않는다는 사실을 확인하고 삭제했습니다. 포털은 MDS 저장소 하나로 정리했습니다. 「있으니까 옮긴다」가 아니라 「백지라면 무엇이 맞는가」로 판단한 결과입니다(2장).
백엔드 인계 문서
인계 문서(handoff)는 프로토타입이 실제 백엔드에 넘기는 서버 계약입니다. 제품 저장소에 둡니다. Leyve는 Console 저장소의 인계 문서를 Leyve Docs가 개발자용 문서로 게시합니다. 대표 항목은 다음과 같습니다.
- 목표 계약: 저장할 값과 관계, 상태와 전이, 지켜야 할 불변식
- 권한 키와 서버 판정 위치, 거절할 때의 응답
- 화면이 기대하는 응답 모양(payload)과 행위 주체 필드
- 현재 참고물과 목표 값의 대응표
예를 들어 Leyve Console이 접근 역할 체계(22장)를 채택할 때, 화면과 localStorage 프로토타입은 새 역할 체계로 바꿨습니다. 백엔드 참고 코드는 옮기지 않았습니다. 대신 인계 문서에 「목표 역할 계약」을 적었습니다. 역할 값, 조직 소유 관계와 상태, 상속, 권한 키, 로그인, 거절 응답, 화면이 기대하는 필드, 옛 값과 새 값의 대응표가 그 내용입니다.
상태를 정직하게 적습니다
프로토타입과 실제 서비스 사이에는 여러 단계가 있습니다. Leysys 문서는 계획(planned), 로컬 전용(local-only), 배포(deployed), 운영 준비(production-ready)를 나눠 적습니다.
- 문서 정리, SDK 설치, staging(운영 전 시험 환경) 실행만으로 운영 준비를 선언하지 않습니다.
- package manifest는 게시의 증거가 아니고, migration 파일은 운영 DB 적용의 증거가 아닙니다.
- 문서를 바꿨다고 런타임이 그 내용을 채택한 것은 아닙니다. 채택은 소유 저장소의 코드·테스트·배포로 확인합니다.
경계와 예외
- 저장 원칙은 프로토타입과 실제 서비스의 저장소 종류를 정합니다. 각 제품의 실제 실행 구조와 배포는 그 제품의 아키텍처 결정이 소유합니다.
-proto저장소도 등록부에 배포 주인으로 등록되면 공개 주소를 가질 수 있습니다. 주소만 보고 프로토타입인지 판단하지 않습니다.- 프로토타입도 디자인 시스템 규칙을 지킵니다. 게시된 패키지를 exact version으로 쓰고, 한 페이지에 EDS와 MDS를 섞지 않습니다.
정리
- 프로토타입은 목표 화면·상호작용의 기준이고, 기능·데이터·권한의 정본은 실제 제품입니다.
- 프로토타입은 localStorage(꼭 필요하면 Supabase), 초기 MVP는 Supabase, 고도화된 실제 서비스는 MariaDB를 씁니다.
- 프로토타입에 실행되지 않는 SQL을 새로 두지 않고, 서버 계약은 인계 문서로 넘깁니다.
- 디자인 정본 이전의 코드는 덧대지 않고 정본 구조로 다시 씁니다.
- 계획·로컬·배포·운영 준비를 구분해 적습니다.
정본
leysys-designdocs/process/leysys-prototyping-pipeline.md— 파이프라인과 역할leysys-designdocs/process/PRODUCT-V1-SSOT-MIGRATION-PLAN-2026-07-19.md§1–2 — 프로토타입과 실제 제품의 책임leysys-designAGENTS.md「제품 레포 재작성 원칙」 — 덧대지 않고 다시 쓰기- 저장소·호스트 네이밍 상세 규칙 §12 —
-proto와 프로토타입 종료 - 아키텍처 경계, 현재 제공 상태 — 상태 구분
- 아키텍처 경계 「단계별 데이터 저장소」 — 저장 원칙(오너 결정 2026-10-04 KST). Leyve Console의 적용은 그 저장소의
LOCAL-STORAGE-PROTOTYPE-2026-09-23과PLANNING-STAGE-DB-SUPABASE-2026-07-09§2가 기록합니다.