Hook

AI 디자인 도구로 페이지를 만들었습니다. 멋진 그라데이션, 깔끔한 카드 레이아웃, 완벽한 폰트. 그런데 막상 개발을 시작하려 보니. “이 카드에 들어갈 데이터는 어디서 오지?”, “이 버튼을 누르면 무슨 API를 호출하지?”, “데이터가 없으면 뭘 보여주지?”.

프리뷰는 답을 주지 않습니다. 성공 상태의 시각적 아름다움만 보여줄 뿐입니다. 이 글에서는 프리뷰가 개발 순서를 지배하는 문제를 4단계 게이트로 통제한 방법을 공유합니다.

TL;DR

• 근본 원인은 “순서 역전”: 프리뷰(결과)를 먼저 만들고 데이터 구조(원인)를 나중에 맞추면 데드 버튼, 목 데이터, 상태 누락이 필연적으로 발생합니다
• 4단계 게이트로 올바른 순서를 강제합니다: 도메인 모델 → 데이터 스키마 → API 컨트랙트 → UI 구현 → 디자인 적용
• 3가지 불변 규칙: Data First, Contract First, No Dead Buttons
• 게이트를 우회하는 유일한 예외는 prototype/ 브랜치뿐입니다

Background: 프리뷰 역설이 만드는 부채

금지된 흐름

✗ 금지: Open Design 프리뷰 → 코드 작성 → 데이터 구조 설계

  이 흐름을 따르면:
  ├── 하드코딩된 목 데이터 (const workingOut = 3; 대신 fetch('/api/active-users'))
  ├── 데드 버튼 (onclick={}, href="#", TODO 인터랙티브 요소)
  ├── UI를 위한 임시 필드 (badge_color 대신 subscription_tier)
  ├── 에러 무시 (프리뷰에 에러가 없으니 성공 케이스만 구현)
  └── 상태 누락 (loading, error, empty, unauthorized 없음)

왜 AI 도구가 이 문제를 유발하는가

AI 디자인 도구는 완성된 화면을 생성하도록 훈련되어 있습니다. 완성된 화면에는:

• 데이터가 있습니다 (실제로는 하드코딩된 목 데이터)
• 에러가 없습니다 (성공 케이스만 렌더링)
• 모든 버튼이 작동합니다 (시각적으로는)

개발자는 이 “완성된” 프리뷰를 보고 “남은 건 API만 연결하면 되겠네”라고 착각합니다. 하지만 API가 없고, 에러 상태가 없고, 권한 모델이 없습니다.

Solution: 4단계 게이트 프로세스

필수 흐름

도메인 모델      데이터 스키마     API 컨트랙트      UI 구현        디자인 적용
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ 비즈니스  │ →  │ D1 /     │ →  │ 엔드포인트│ →  │ 핸들러   │ →  │ 스타일링  │
│ 도출     │    │ Storage  │    │ 정의     │    │ 연결     │    │          │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
  Gate 1          Gate 1          Gate 2          Gate 3          Gate 4

게이트별 통과 조건

3가지 불변 규칙

① Data First: 프리뷰에서 역추론 금지

스키마는 도메인에서 도출합니다. 프리뷰에 “뱃지 색상” 필드가 있다고 해서 badge_color 컬럼을 만들지 않습니다. 대신 의미 있는 도메인 속성(subscription_tier)에서 색상을 파생합니다.

// ✗ 안티패턴: 프리뷰에 맞춘 임시 필드
{ badge_color: "gold" }

// ✓ 올바름: 도메인에서 파생
{ subscription_tier: "premium" }
// → UI에서 tier에 따라 색상 매핑

② Contract First: 인터랙티브 요소는 API 정의 선행

모든 클릭 가능한 요소는 구현 전에 API 엔드포인트와 조작이 정의되어야 합니다. “나중에 연결할게”라는 버튼은 존재하지 않습니다.

③ No Dead Buttons: 데드 버튼 프로덕션 배포 금지

<!-- ✗ 데드 버튼 -->
<button onclick="{}">저장</button>
<a href="#">더 보기</a>
<button>삭제</button> <!-- TODO: 구현 예정 -->

<!-- ✓ 올바름: 미구현은 명시적으로 -->
<button disabled title="다음 버전에서 사용 가능">저장</button>

게이트 우회 금지

유일한 예외: prototype/ 브랜치에서만 스파이크 허용 (main 머지 금지).

필수 상태 처리

프리뷰는 성공만 보여주므로, 반드시 4가지 상태를 직접 구현해야 합니다:

인터랙티브 요소 추적 표

페이지별로 모든 클릭 가능 요소를 추적 표에 등록합니다:

| 요소        | 타입   | API 엔드포인트          | 상태 처리        |
|------------|--------|------------------------|-----------------|
| 저장 버튼   | button | POST /api/v1/workouts  | loading/error   |
| 삭제 버튼   | button | DELETE /api/v1/workouts| confirm/error   |
| 더 보기     | link   | GET /api/v1/feed?page=2| loading/empty   |

프리뷰 만료 규칙

구현 완료 후 30일 경과 시 프리뷰는 보관 자료로 전환됩니다. 이후 프리뷰와 코드가 충돌하면 항상 구현 코드가 우선입니다.

Result: 게이트 도입 전후

마치며

AI 디자인 도구를 처음 썼을 때 가장 큰 착각은, 프리뷰를 “설계 명세”로 받아들였다는 점입니다. 멋진 카드 레이아웃과 완벽한 폰트를 보면 마치 모든 것이 결정된 것처럼 느껴집니다. 하지만 막상 개발을 시작하려 하면 프리뷰는 아무 질문에도 답해주지 않는다는 것을 깨닫게 됩니다. “데이터는 어디서 오는가”, “버튼을 누르면 무슨 일이 일어나는가”, “데이터가 비어 있으면 어떻게 되는가”. 이 질문들은 프리뷰에 존재하지 않는 실패 상태와 빈 상태에 관한 것이었습니다. 프리뷰는 성공의 아름다움만을 보여줄 뿐, 소프트웨어의 진짜 복잡도를 감추고 있었습니다.

이 환상에서 벗어나기 위해 도입한 것이 4단계 게이트입니다. 도메인 모델 → 데이터 스키마 → API 컨트랙트 → UI 구현 → 디자인이라는 순서를 강제하면, 처음에는 번거롭게 느껴집니다. 하지만 순서를 우회해서 생기는 재작업 비용이 훨씬 크다는 것을 반복적으로 경험했습니다. 게이트가 강제하는 것은 결국 “원인을 먼저 생각하고 결과를 나중에 만들라”는 소프트웨어 설계의 기본 원칙이었습니다.

프리뷰를 “영구 명세”가 아니라 “30일 만료되는 임시 참고 자료”로 대우하기로 한 것도 중요한 전환점이었습니다. 구현이 완료된 후에는 항상 코드가 프리뷰를 이겨야 합니다. 그렇지 않으면 AI 에이전트가 오래된 프리뷰를 근거로 이미 바뀐 코드를 과거 상태로 되돌리는 일이 벌어집니다. 앞으로 AI 디자인 도구가 더 정교해지더라도, “결과가 원인을 지배하게 두지 않는다”는 원칙은 변하지 않을 것입니다.