바이브코딩으로 MVP 만들 때 무너지지 않는 폴더 구조: AI가 길 잃지 않는 4가지 원칙

왜 폴더 구조가 AI 코딩의 속도를 결정할까

바이브코딩으로 MVP를 만들면 초반 속도는 꽤 빠릅니다. 문제는 기능이 5개, 10개로 늘어난 뒤입니다. 로그인 코드는 어디에 있는지, 결제 상태는 어느 파일이 책임지는지, API 응답 타입은 누가 관리하는지 흐려지면 사람도 AI도 같은 실수를 반복합니다.

AI 코딩 도구는 현재 파일과 주변 컨텍스트를 보고 다음 코드를 제안합니다. 그래서 폴더 구조는 단순한 정리 취향이 아니라, AI에게 주는 지도에 가깝습니다. 지도가 명확하면 “이 기능은 여기서 고치면 된다”는 판단이 쉬워지고, 지도가 흐리면 관련 없는 파일까지 건드릴 가능성이 커집니다.

원칙 1. 기능별 모듈을 먼저 나눈다

초기 MVP에서는 components, utils, hooks처럼 기술 종류별로 나누기 쉽습니다. 작은 앱에서는 괜찮지만, 기능이 늘면 “이 버튼이 어떤 도메인에 속하는지”가 폴더명만으로 보이지 않습니다.

대체로 1인 빌더에게는 기능별 모듈 구조가 더 오래 버팁니다.

src/
  features/
    auth/
    submission/
    billing/
    profile/
  shared/
  app/

핵심은 관련 파일을 한곳에 모으는 것입니다. submission 기능이라면 화면, 서버 호출, 검증 스키마, 타입, 작은 컴포넌트를 같은 경계 안에 둡니다. AI에게도 “submission 기능만 보고 수정해”라고 말하기 쉬워집니다.

원칙 2. shared는 작게 유지한다

shared나 common은 편하지만, 금방 잡동사니 폴더가 됩니다. 모든 기능에서 한 번이라도 쓸 것 같다는 이유로 넣기 시작하면, 나중에는 어떤 변경이 어디까지 영향을 주는지 추적하기 어렵습니다.

처음에는 다음 정도만 shared 후보로 두는 편이 안전합니다.

반대로 “제출 상태”, “유료 플랜”, “프로필 완성도”처럼 도메인 의미가 들어간 코드는 각 기능 폴더에 두는 편이 낫습니다. 공유는 나중에 빼도 됩니다. 너무 일찍 공유하면 되돌리기 어렵습니다.

원칙 3. 파일 이름은 AI가 추론할 수 있게 쓴다

AI에게 좋은 파일명은 짧은 암호가 아니라 역할이 드러나는 이름입니다. helpers.ts, data.ts, misc.ts는 사람에게도 AI에게도 힌트가 적습니다. 대신 다음처럼 책임을 드러내는 이름이 좋습니다.

• submission.schema.ts: 제출 폼 검증
• submission.actions.ts: 제출 관련 서버 액션
• submission.repository.ts: 저장소 접근
• submission-card.tsx: 제출 카드 UI
• use-submission-draft.ts: 제출 임시 저장 훅

네이밍은 멋보다 일관성이 중요합니다. 한 기능에서 actions라고 불렀다면 다른 기능에서도 비슷한 서버 동작은 actions로 맞추는 편이 좋습니다. 그러면 AI에게 “billing도 submission과 같은 패턴으로 만들어”라고 지시했을 때 결과가 안정적으로 나옵니다.

원칙 4. 컨벤션을 짧게 문서화한다

폴더 구조는 코드만으로 완전히 전달되지 않습니다. 특히 AI 도구를 자주 쓴다면 루트나 docs/에 짧은 컨벤션 문서를 두는 것이 효과적입니다.

예를 들면 docs/code-structure.md에 다음 내용을 적습니다.

- 새 기능은 `src/features/{feature-name}` 아래에 만든다.
- 도메인 로직은 `shared`로 올리지 않는다.
- 서버 변경은 `{feature}.actions.ts`에 둔다.
- 검증 스키마는 `{feature}.schema.ts`에 둔다.
- 공통 UI만 `shared/ui`에 둔다.

긴 문서보다 중요한 것은 실제로 프롬프트에 붙이기 쉬운 길이입니다. 새 기능을 만들 때 이 문서를 함께 읽게 하면, AI가 기존 구조를 벗어나는 빈도가 줄어듭니다.

MVP 단계에서 추천하는 최소 구조

처음부터 완벽한 아키텍처를 만들 필요는 없습니다. MVP에서는 아래 정도면 충분한 출발점이 됩니다.

src/
  app/                  # 라우팅, 페이지 조립
  features/
    feature-name/
      components/
      feature-name.actions.ts
      feature-name.schema.ts
      feature-name.types.ts
      index.ts
  shared/
    ui/
    lib/
    config/
  docs/
    code-structure.md

여기서 중요한 규칙은 app은 조립을 담당하고, 실제 기능의 판단은 features 안에 둔다는 것입니다. 페이지 파일이 비대해지기 시작하면 AI가 수정 범위를 넓게 잡기 쉽습니다. 화면 조립과 기능 구현을 분리하면 작은 요청으로도 정확히 수정할 수 있습니다.

AI에게 줄 프롬프트까지 구조화하기

폴더 구조를 정했다면 프롬프트도 그 구조를 기준으로 씁니다.

새 기능은 src/features/submission 안에서만 구현해줘.
공통 UI가 꼭 필요할 때만 src/shared/ui에 추가해줘.
docs/code-structure.md의 규칙을 따라줘.
기존 billing 폴더의 파일명 패턴을 참고해줘.

이런 식으로 경계를 먼저 알려주면 결과물이 앱 전체로 퍼지는 일을 줄일 수 있습니다. 특히 1인 개발자는 리뷰할 시간도 제한적이기 때문에, AI가 만든 변경의 범위를 작게 유지하는 것이 중요합니다.

정리: 좋은 구조는 느리게 만들기 위한 것이 아니다

폴더 구조를 잡는 이유는 완벽한 설계를 하기 위해서가 아닙니다. 다음 기능을 더 빠르게 붙이고, 잘못된 변경을 더 빨리 발견하기 위해서입니다.

바이브코딩으로 MVP를 만들수록 구조는 더 단순하고 명시적이어야 합니다. 기능별로 모으고, shared를 작게 두고, 파일명을 역할 중심으로 맞추고, 컨벤션을 짧게 남기세요. 그러면 AI는 길을 덜 잃고, 1인 빌더는 제품을 계속 앞으로 밀 수 있습니다.