코드를 식당처럼 설계하라 — 바이브마피아의 클린 아키텍처에서 얻은 인사이트

바이브마피아(수민)님이 식당 하나로 소프트웨어 설계의 핵심을 1시간 만에 설명해주셨다.
나는 이날 처음으로 "코드를 짜기 전에 설계를 해야 한다"는 말의 실체를 이해했다.

프롤로그 — 나는 왜 이 강의가 필요했나

솔직히 고백하자면, 나는 Claude Code에게 늘 이렇게 요청했다.

"이 기능 만들어줘요."

그러면 Claude가 코드를 뚝딱 만들어줬다. 작동도 됐다. 그런데 한 달 뒤에 같은 기능을 조금 바꾸려고 하면 Claude가 이렇게 말했다.

"이 부분을 수정하려면 저 부분도 바꿔야 하고, 그러면 저기도 영향을 받아서..."

수정이 수정을 낳고, 버그가 버그를 낳았다. 뭔가 근본적으로 잘못된 것 같았는데 뭐가 문제인지 몰랐다.

바이브마피아님의 이날 강의가 그 답이었다. 식당 비유 하나로.

1부. 냉장고를 보여주는 법 — 3계층의 탄생

당근마켓에서 냉장고를 검색할 때 무슨 일이 일어나는가

바이브마피아님이 화면을 공유하며 물었다.

"이 냉장고 검색 화면 하나에서 어떤 일이 일어나고 있을까요?"

처음엔 단순해 보였다. 검색어 입력하면 냉장고가 나오는 것 아닌가. 그런데 단계별로 쪼개면 전혀 달랐다.

1. 사용자가 "냉장고"를 입력한다

2. 화면에 검색창과 결과가 표시된다 ← 화면(Presentation)

3. "내 동네 2km 이내인가?" 판단한다 ← 정책(Logic)

4. "아직 안 팔렸나?" 판단한다 ← 정책(Logic)

5. DB에서 냉장고 목록을 불러온다 ← 데이터(Data)

6. 결과를 화면에 보여준다 ← 화면(Presentation)

7. 최근 검색어에 "냉장고"를 추가한다 ← 데이터(Data)

같은 "냉장고 검색" 화면 하나에 Presentation, Logic, Data가 섞여 있다. 이것을 분리하는 것이 3계층 설계다.

식당으로 바꿔 생각하면

"코딩과 관련된 용어가 하나도 없죠? 개발 지식이 없어도 이 구분은 누구나 할 수 있어요."

원샷의 인사이트 #1

나는 이 설명을 들으면서 CMDS 시스템을 떠올렸다. CLAUDE.md는 Presentation(Claude가 어떻게 반응할지), 스킬 파일은 Logic(어떤 작업을 어떻게 할지), 옵시디언 볼트는 Data(실제 저장소). 나도 모르는 사이에 3계층을 운영하고 있었다. 이름은 몰랐지만.

2부. 왜 굳이 나누는가 — 분리의 세 가지 이득

첫째, 버그의 책임 소재가 명확해진다

"스테이크 조리 상태가 엉망이에요. 홀 서빙 직원한테 뭐라고 할 건가요? 주방으로 가야죠."

소프트웨어도 마찬가지다.

• 화면이 이상하다 → Presentation에서 찾는다

• 데이터가 잘못 들어왔다 → Data에서 찾는다

• 로직이 틀렸다 → Logic에서 찾는다

통으로 뭉쳐진 코드에서 버그를 찾는 것과, 계층이 나뉜 코드에서 버그를 찾는 것은 천지 차이다. 전자는 전체를 뒤져야 하고, 후자는 의심 가는 계층만 보면 된다.

둘째, 수정 범위가 줄어든다

인테리어를 바꾸고 싶다. 식당에서 홀 인테리어를 바꾼다고 주방 레이아웃이나 냉장고 위치를 바꿀 필요는 없다.

코드도 같다.

• UI 디자인만 바꾸고 싶다 → Presentation만 수정

• 데이터베이스를 Supabase에서 AWS로 바꾸고 싶다 → Data만 수정

바이브마피아님이 실제 사례를 들었다.

"코드가 하나로 뭉쳐져 있으면 Supabase 쓴 부분을 전체에서 다 찾아서 다 교체해야 해요. 그 중에 하나만 빠뜨려도 버그가 생깁니다. 반면 계층이 잘 분리돼 있으면 Data 부분만 수정하고 Data 부분만 검증하면 끝이에요."

셋째, 테스트가 가능해진다

바이브 코딩에서 테스트는 보통 Playwright 같은 가상 브라우저로 버튼을 클릭해가며 기능을 확인한다. 문제는 이게 엄청나게 느리고 무겁다는 것이다.

계층이 나뉘어 있으면 달라진다.

"계층별로 잘 작동하는지 테스트하고 조립만 하면 됩니다. 전체 기능을 써보지 않아도 서비스가 잘 작동함을 보장할 수 있어요."

Logic 계층이 제대로 작동하는지 따로 검증하고, Presentation이 제대로 표시하는지 따로 검증하면 — 조립한 전체는 신뢰할 수 있다.

원샷의 인사이트 #2

버그를 찾다가 포기한 적이 있다. Claude가 고쳐줬는데 다른 데서 또 터졌다. 이제 그 이유를 안다. 코드가 통으로 뭉쳐 있으면 한 곳을 건드릴 때 다른 곳에 영향을 준다. 계층 분리는 사치가 아니라 장기적으로 유지 가능한 코드를 위한 최소 조건이었다.

3부. 올바른 순서 — PRD → TID → 구현

"앞 단계를 좀 복잡하게 거치고 나서 구현하는 게 구현하고 나서 버그 잡는 것보다 완성 속도가 훨씬 빠릅니다."

바이브마피아님이 강조한 것은 순서였다.

1단계: PRD — 무엇을 만들 것인가

Product Requirement Document. 기능 목록과 사용자 시나리오를 정리한다.

포인트는 세세한 디자인까지 잡으려 하지 말 것.

"일단 핵심 원칙만 주고 간단하게 뽑아요. 쓰면서 반복 개선하는 편이 훨씬 유리합니다."

2단계: TID — 어떻게 만들 것인가

Technical Implementation Document. 기술 설계서다.

여기서 핵심 프롬프트:

PRD를 읽고 기술적 설계를 할 것입니다.
3-tier layered architecture를 반드시 준수하세요.
먼저 큰 그림을 소개하고 나서,
기술적으로 모호하거나 중요하게 결정해야 할 논의점을 소개하세요.
나는 기술적 배경이 깊지 않으니 비용/임팩트 위주로 설명해주세요.
모든 논의가 완료된 후 최종 문서를 작성해주세요.

"개발자를 고용하면 개발자가 설계해오라고만 해도 이해 안 되는 거 물어볼 거잖아요? AI한테도 그걸 시키는 겁니다. 먼저 논의하고 나서 설계해달라고요."

3단계: 구현

설계가 끝난 다음에야 코드를 짠다. 계층별로 나눠서 AI에게 요청한다.

4단계: 테스트 설계

이 프로젝트는 AI 에이전트에 의해 개발되며 요구사항이 자주 바뀔 것입니다.
언제나 정상 작동을 높은 신뢰도로 보증할 수 있도록
테스트 커버리지를 높여주세요.
계층별로 책임만 정확히 테스트해주세요.

원샷의 인사이트 #3

나는 항상 "만들어줘"부터 시작했다. PRD가 뭔지, TID가 뭔지 몰랐다. 이제 알았으니 다음 Claude Code 프로젝트는 반드시 이 순서를 지킬 것이다. 설계가 귀찮은 게 아니라 설계가 없으면 나중에 더 귀찮아진다는 것을 이제 이해했다.

4부. claude.md — AI에게 역할을 주어라

"많은 분들이 놓치시는 게 AI한테 역할을 잘 안 줘요. 역할을 주는 게 되게 중요합니다."

같은 기능도 맥락에 따라 코드가 달라진다

스타트업 개발자가 만드는 코드와 대기업 개발자가 만드는 코드는 다르다. 우리가 MVP를 만들 때는 스타트업 페르소나를 주는 것이 유리하다.

claude.md에 넣어야 할 것들

1. 역할: 나는 스타트업 공동창업자, 너는 내 기술 파트너

2. 목표: 단순하고 임팩트 있는 제품을 빠르게 만들고 가설을 검증한다

3. 기준: YCombinator 스타트업처럼 — 간결하고 빠르게

4. 구조: 3-tier layered architecture를 모든 프로젝트에 적용

"이 프롬프트는 웬만한 다른 프로젝트에도 그냥 그대로 쓰셔도 좋습니다."

OpenClo로 본 3계층 실전 분석

"OpenClo가 카카오톡뿐 아니라 슬랙, 디스코드에서도 작동하는 이유 — 슈타인버거씨가 계층을 잘 분리해서 설계했기 때문입니다."

원샷의 인사이트 #4

CLAUDE.md를 이미 쓰고 있지만, 나는 거기서 "3계층 구조로 설계하라"고 명시한 적이 없었다. 앞으로는 넣을 것이다. 그리고 "스타트업 공동창업자" 페르소나를 주는 것도 지금 당장 적용할 수 있다. 같은 요청을 해도 맥락이 달라지면 결과가 달라진다는 것을 다시 한번 확인했다.

5부. 나는 설계를 못 해도 된다 — 검토할 줄만 알면

강의 마지막에 바이브마피아님이 강조한 것이 있다.

"저희가 3계층 설계를 직접 할 줄 알 필요는 없어요. 잘 설계했는지 검토할 줄만 알면 됩니다."

그리고 이런 비유를 들었다.

"옷 잘 입는 것보다 누가 옷 잘 입었는지 못 입었는지 판단하는 게 더 쉽잖아요."

우리가 할 일은 AI가 설계한 것을 보고 "납득이 되느냐"만 판단하면 된다. 납득이 안 되는 부분만 재질문하면 AI가 설명하거나 수정한다.

실전에서 쓸 수 있는 한 줄

기존 프롬프트에서 달라지는 것은 딱 하나.

기존: "이 기능 만들어줘요."
변경: "이 기능 만들어줘요. 3계층으로 설계해서."

이 한 줄이 추가될 때 결과가 달라진다.

테스트도 마찬가지

기존: "테스트 코드 짜줘요."
변경: "계층별로 책임만 정확히 테스트해줘요."

"테스트 해달라"고 하면 AI가 무겁고 깨지기 쉬운 테스트를 짠다. 계층별로 명시하면 가볍고 신뢰할 수 있는 테스트가 나온다.

원샷의 인사이트 #5

이 부분에서 마음이 놓였다. 내가 설계 전문가가 되어야 하는 게 아니었다. "납득이 되느냐"만 판단하면 된다. 이것은 AI와 협업하는 모든 영역에 적용되는 원칙이기도 하다 — 구요한님이 말씀하신 "내가 모르는 시스템은 위험하다"와 같은 맥락. 이해하고 있어야 판단할 수 있다. 다 알 필요는 없지만, 판단은 내가 해야 한다.

에필로그 — 설계라는 습관

이날 강의를 들으면서 가장 많이 든 생각은 이것이었다.

"나도 이미 하고 있었다."

CMDS 헤드쿼터를 만들고, CLAUDE.md에 지침을 쓰고, 스킬 파일을 구분한 것 — 이것이 모두 계층을 나누는 행위였다. 이름만 달랐다.

차이는 이것을 의도적으로 하느냐, 우연히 하느냐다.

앞으로는 의도적으로 한다.

• 새 기능 시작 전 PRD 한 장 먼저

• "3계층으로 설계해서" 한 마디 추가

• AI 설계안 보고 "납득이 되느냐" 판단

• 계층별로 테스트 요청

식당을 운영할 때 홀과 주방과 창고 역할을 나누는 것은 당연하다. 코드도 마찬가지다. 역할이 나뉘어야 일하기 편하다.