바이브코딩으로 만든 프로젝트가 커지다 보면 어느 순간 AI가 엉뚱한 파일에 코드를 추가하거나, 비슷한 기능이 여러 곳에 중복되거나, 전체 구조가 엉망이 되는 경험을 해요. 이건 프로젝트 구조 설계를 처음부터 생각하지 않았기 때문이에요.
왜 구조가 중요한가요
집을 지을 때 설계도 없이 벽돌을 쌓으면 어떻게 될까요? 처음에는 빨라 보여도 나중에 문을 달거나 배관을 연결하기 어려워져요. 소프트웨어도 마찬가지예요. 프로젝트 구조가 명확하지 않으면 기능이 늘어날수록 수정이 어려워져요.
AI와 함께 작업할 때는 특히 중요해요. AI는 구조가 명확하면 “기존 패턴에 맞게” 새 기능을 추가해줘요. 구조가 불명확하면 AI도 일관성 없는 코드를 만들어요.
폴더 구조의 기본 원칙
다음은 React/Next.js 기반 프로젝트의 일반적인 폴더 구조예요. 기술 스택마다 차이는 있지만 원칙은 비슷해요.
src/ components/ → 재사용 가능한 UI 조각들 pages/ (또는 app/) → 각 화면 hooks/ → 재사용 가능한 로직 lib/ (또는 utils/) → 유틸리티 함수들 types/ → TypeScript 타입 정의 styles/ → 전역 스타일
각 폴더의 역할이 명확하면 어떤 코드가 어디 있어야 하는지 예측 가능해요. AI에게도 “components 폴더에 있는 것들처럼 만들어줘”라고 할 수 있어요.
실제 폴더 구조 예시 (Next.js)
my-app/
├── app/ ← 페이지 파일들
│ ├── page.tsx ← 홈 페이지
│ ├── login/
│ │ └── page.tsx
│ └── dashboard/
│ └── page.tsx
├── components/ ← 재사용 컴포넌트
│ ├── Button.tsx
│ ├── Card.tsx
│ └── Header.tsx
├── lib/ ← 유틸리티, API 호출
│ └── api.ts
└── types/ ← TypeScript 타입 정의
└── index.ts
처음부터 이 구조를 완벽하게 만들 필요는 없어요. AI에게 “Next.js로 프로젝트를 시작할 건데, 기본 폴더 구조를 잡아줘. 로그인, 대시보드, 설정 페이지가 필요해”라고 하면 적합한 구조를 제안해줘요.
컴포넌트 분리의 원칙
UI를 만들 때 모든 걸 하나의 파일에 쓰는 것보다 작은 컴포넌트로 나누는 게 좋아요. 기준은 간단해요. 같은 코드가 두 번 이상 나오면 분리해요. 그리고 하나의 컴포넌트가 너무 길어지면 분리해요.
예를 들어 상품 목록 페이지에서 각 상품 카드가 반복된다면, ProductCard 컴포넌트를 만들어서 분리해요. 나중에 카드 디자인을 바꿀 때 ProductCard 하나만 수정하면 돼요.
AI에게 구조 설계를 도움받기
처음 프로젝트를 시작할 때 AI에게 이렇게 물어보세요. “독서 기록 공유 앱을 Next.js 14, TypeScript, Tailwind로 만들 거야. 어떤 폴더 구조로 시작하는 게 좋을까? 기본 폴더 구조를 만들어줘.”
AI가 제안하는 구조가 업계 관행과 맞는지 검증할 필요는 없어요. 일단 AI가 제안한 구조로 시작하고, 프로젝트가 커지면서 필요에 따라 조정하면 돼요. 프론트엔드와 백엔드의 차이를 이해하면 폴더를 어떻게 나눠야 할지 더 명확해져요.
일관성이 완벽함보다 중요해요
어떤 구조를 쓰느냐보다 선택한 구조를 일관되게 유지하는 게 더 중요해요. AI에게도 “이 프로젝트는 이런 구조를 써”라고 알려주면 일관성을 지켜줘요. 규칙을 문서화해서 Cursor의 Rules for AI에 넣어두면 더 효과적이에요. 처음 잘 잡은 구조 하나가 나중에 수백 시간의 수고를 아껴줘요.
댓글 0