[미니사례] 설계 먼저, 구현은 AI가 — 바이브마피아 3-tier 아키텍처 실습 후기

# [Claude Code] 설계 먼저, 구현은 AI가 — 바이브마피아 3-tier 아키텍처 실습 후기

## 📝 한줄 요약

바이브마피아님의 3계층 분리 설계 가이드를 Claude Code로 직접 실습하며, 기획-설계-구현-테스트를 하루에 완성했다.

**바쁘시면 이것만 읽어도 돼요:**
- Claude Code로 미니멀 가계부 앱(Vibe Ledger) 기획부터 구현까지 하루 완성
- 설계 논의를 먼저 충분히 하고 구현을 시킨 것이 핵심
- TypeScript 오류 0건, 빌드 성공, API 테스트 한 번에 통과
- 레이어 분리 원칙을 미리 명확히 정의하면 AI가 일관성 있게 구현한다는 걸 체험
- 바이브마피아 가이드의 내용이 코드로 어떻게 표현되는지 직접 확인 가능
- 이 방법을 다른 프로젝트에도 적용할 예정

---

## 🎯 이런 분들께 도움돼요

- 바이브마피아님의 가이드를 보고 직접 따라해보고 싶은 분
- AI한테 "만들어줘" 한 마디만 했는데 결과가 늘 엉망이었던 분
- 3-tier 아키텍처가 실제 코드에서 어떻게 보이는지 궁금한 분

---

## 😫 시작 계기

바이브마피아님의 3계층 분리 설계 가이드를 읽고 "이론은 이해했는데, 실제로 AI랑 하면 어떻게 되는 거지?" 싶었다.

가이드에서 강조하는 핵심은 **설계를 먼저 정의하고, AI는 구현 도구로 쓰라**는 것. 그런데 막상 실습을 해보지 않으면 그게 얼마나 중요한지 체감하기 어렵다.

그래서 직접 작은 프로덕트를 하나 골라 가이드대로 따라해보기로 했다. 주제는 미니멀 가계부 앱, 이름은 **Vibe Ledger**.

---

## 🛠️ 사용한 도구

- **도구**: Claude Code
- **모델**: Claude Sonnet 4.6
- **특이사항**: 코드 한 줄 직접 작성 없이 대화만으로 진행

---

## 🔧 작업 과정

### 페르소나 설정 — AI에게 역할을 먼저 줬다

가장 먼저 한 건 `CLAUDE.md` 작성이었다. AI에게 "구글 출신 시니어 개발자이자 이 스타트업의 CTO"라는 역할을 부여하고, 설계 철학을 명시했다.

```
단순하고 임팩트 있는 제품을 빠르게 만들고 가설을 검증하는 것이 목표.
UX를 가장 중요한 가치로 여기며, simplicity가 정답이라고 믿는다.
```

이렇게 하면 이후 모든 대화에서 AI가 같은 기준으로 판단한다. "이 코드 너무 복잡한 거 아니야?"라고 물었을 때 "맞아요, 줄이죠"라고 바로 답하는 게 이 설정 덕분이다.

---

### 설계 논의 — 구현 전에 30분을 여기에 썼다

PRD를 전달하고 바로 "만들어줘"를 하지 않았다. 대신 이렇게 요청했다.

```
3 tier layered architecture를 반드시 준수해야 하며,
presentation / logic / data layer를 사용할 것입니다.
최종 설계서를 작성하기 앞서, 큰 그림을 먼저 내게 소개한 뒤
기술적으로 모호한 부분, 중요하게 결정해야 할 논의점들을 소개하세요.
나는 기술적 배경이 깊지 않으니 쉽게, resource 소모와 impact 위주로 설명해주세요.
```

AI가 제시한 논의점은 4가지였다.

- 데이터를 새로고침해도 유지할지 (localStorage vs 서버 저장)
- 그래프를 라이브러리로 만들지, 직접 만들지
- 애니메이션 라이브러리를 쓸지
- Next.js의 서버 기능을 얼마나 활용할지

각 항목에 대해 비용과 효과를 쉽게 설명해줬고, 의사결정은 내가 직접 했다.

```
1 SQLite
2 SVG
3 Framer
```

이 세 글자로 방향이 확정됐다. 그리고 AI가 이를 반영한 TRD(Technical Requirements Document)를 완성했다.

---

### 구현 — 지시 한 번에 24개 파일

설계가 확정된 뒤 구현 지시는 단 한 줄이었다.

```
좋습니다. 이제 확정된 설계대로 구현하고, 테스트까지 해주세요
```

AI가 만든 것들:

- **Data Layer**: SQLite 연결, API 라우트 (조회/생성/삭제)
- **Logic Layer**: 잔액 계산, 그래프 좌표 변환, 지출 지표 계산
- **Presentation Layer**: 12개 UI 컴포넌트 (입력 시트, 그래프, 인사이트 모달 등)

그리고 결과는 이랬다.

```
TypeScript 컴파일: 오류 0건
Production build: 성공
API 테스트 (GET/POST/DELETE): 전체 통과
```

설계 논의에 시간을 쏟은 덕분에 구현이 한 번에 통과됐다. **설계가 명확하면 AI는 흔들리지 않는다.**

---

## ✅ 결과

### Before vs After

| 항목 | Before | After |
|------|--------|-------|
| 가이드 이해도 | 이론으로만 이해 | 코드로 직접 확인 |
| 설계-구현 프로세스 | 막연함 | 재현 가능한 순서로 정립 |
| 소요 시간 | — | 오후 반나절 |

### 결과물

- `docs/TRD.md` — 3-tier 아키텍처 기술 설계서
- `app/` — SQLite + Custom SVG + Framer Motion 기반 가계부 앱
- `http://localhost:3000` 에서 실행 가능

---

## 💬 실습에서 배운 AI 활용 팁

### 효과적이었던 것

1. **레이어 원칙을 먼저 정의하기**: `CLAUDE.md`와 설계 논의로 원칙을 명확히 했더니 AI가 24개 파일에서 일관된 구조를 유지했다
2. **의사결정은 내가, 구현은 AI가**: 기술 선택(SQLite/SVG/Framer)을 직접 결정하고 AI는 그 결정을 충실히 구현하는 역할로 분리했다
3. **"만들어줘" 전에 "논의하자"**: 설계 논의 단계를 반드시 거치는 것이 핵심

### 이렇게 하면 안 돼요

1. **설계 없이 바로 구현 지시**: AI가 즉흥적으로 구조를 만들면 나중에 레이어가 뒤섞인다
2. **모든 결정을 AI에게 맡기기**: 기술 스택, 아키텍처 원칙 같은 핵심 결정은 직접 내려야 일관성이 유지된다

---

## 🌍 다른 프로젝트에 적용한다면?

이 프로세스 자체가 재사용 가능하다.

1. `CLAUDE.md`에 프로젝트 철학과 설계 원칙 정의
2. PRD 작성 후 설계 논의 요청 (기술 결정은 직접)
3. TRD 확정 후 구현 지시
4. 테스트로 검증

어떤 프로덕트든, 어떤 기술 스택이든 이 순서를 지키면 된다.

---

## 🚀 앞으로의 계획

바이브마피아님의 가이드를 다른 프로젝트들에 동일하게 적용해볼 예정이다. 이번 실습으로 프로세스가 검증됐으니, 다음엔 더 복잡한 프로덕트에도 적용해보려 한다.

---

## 📋 재사용 가능한 프롬프트

### 프롬프트 1: 설계 논의 요청

> [아키텍처 원칙]을 반드시 준수해야 합니다.
> 구현하기 전에 큰 그림을 먼저 소개하고,
> 기술적으로 모호한 부분과 중요한 결정사항들을 알려주세요.
> 기술적 배경이 깊지 않으니 비용과 효과 위주로 쉽게 설명해주세요.

### 프롬프트 2: 구현 지시

> 지금까지 논의한 설계대로 구현하고, 테스트까지 완료해주세요.
> [레이어 원칙]을 반드시 지켜주세요.