폴더 구조 베스트 프랙티스 — 깔끔하고 유지보수 쉬운 프로젝트 구조 설계

폴더 구조 베스트 프랙티스 — 깔끔하고 유지보수 쉬운 프로젝트 구조 설계

프로젝트 시작할 때 폴더 구조를 잘 설계해 두면 협업과 유지보수 비용이 크게 줄어듭니다. 이 글에서는 원칙, 흔히 쓰이는 패턴(모노레포/멀티레포, 프론트엔드/백엔드), 그리고 예시 트리 구조와 체크리스트를 정리합니다.

핵심 원칙

• 의미 있게 그룹화 — 관련 파일/모듈을 같은 디렉터리에 모으세요.
• 관심사의 분리(Separation of Concerns) — UI, 비즈니스 로직, 데이터 접근을 분리합니다.
• 명확한 네이밍 — 폴더/파일명만 보고 역할을 예측할 수 있어야 합니다.
• 작은 단위(모듈화) — 한 폴더 안에 너무 많은 책임을 넣지 마세요.
• 일관성 — 팀 규칙(예: kebab-case vs snake_case)을 정하고 지키세요.

자주 쓰이는 패턴

1) 프론트엔드 (React / Vue / Next.js 등)

컴포넌트 기반 개발을 고려한 구조

/src
  /components       # 재사용 가능한 UI 컴포넌트
  /features         # 도메인 단위(또는 페이지 단위) 폴더
    /auth
      Login.jsx
      login.slice.js
  /pages            # Next.js 같은 라우트 기반 페이지
  /hooks            # 커스텀 훅
  /services         # API 호출, 외부 통합
  /styles           # 전역 스타일, 테마
  /utils            # 유틸 함수
  /assets           # 이미지, 폰트
/tests
/public
package.json
    

2) 백엔드 (Node.js / Spring / Django 등)

레이어드 아키텍처(Controller - Service - Repository)를 권장

/src
  /api
    /v1
      /users
        controller.js
        service.js
        repository.js
  /config           # 환경설정, DI 설정
  /db               # 마이그레이션, 시드
  /middlewares
  /models
  /utils
  /jobs             # 배치 작업, 스케줄러
/tests
/docs
package.json
    

3) 모노레포 (단일 저장소에 여러 패키지)

공유 코드(유틸, 디자인 시스템)를 쉽게 관리할 때 유용

/packages
  /web-app
  /api
  /ui-library
  /shared-utils
/scripts
/package.json
/lerna.json or pnpm-workspace.yaml
    

실전 팁 — 바로 적용 가능한 체크리스트

1. README.md를 각 최상위 폴더에 두고 목적·실행법·예시를 적으세요.
2. config는 코드와 분리하고 환경별 파일(.env.example) 제공.
3. 비밀정보는 절대 커밋 금지 — secrets는 Vault/환경변수/CI 시크릿을 사용.
4. 테스트 위치를 규칙화 — 예: __tests__ 또는 /tests 폴더.
5. 코드 생성/빌드 산출물은 분리 — /dist, /build, /out 등은 .gitignore에 포함.
6. CI 파일 위치는 루트(예: .github/workflows)로 통일.
7. 문서화 — /docs 또는 Storybook 같은 도구로 문서화 유지.

간단한 예시 트리 (React + Express)

/my-project
  /packages
    /frontend
      /src
      package.json
    /backend
      /src
      package.json
  /scripts
  package.json (workspace)
  README.md
    

→ 이렇게 분리하면 독립 배포, 독립 테스트가 쉬워집니다.

자주 하는 실수 & 피하는 방법

• 모든 것을 루트에 넣음 — 루트가 지저분해지면 진입 장벽이 올라갑니다. 기능별 하위 폴더로 정리하세요.
• 중첩이 너무 깊음 — 깊은 중첩은 파일 찾기와 네비게이션을 어렵게 합니다. 3~4 레벨을 넘지 않도록 고려.
• 이름 규칙이 혼재 — 팀 단위로 스타일 가이드를 만들고 PR에서 체크하세요.

요약

좋은 폴더 구조는 명확성, 일관성, 확장성을 목표로 설계해야 합니다. 프로젝트가 커질수록 초기에 세운 규칙과 문서(README, CONTRIBUTING)가 큰 힘을 발휘합니다.

필요하시면 내 프로젝트에 맞춘 폴더 구조 제안을 댓글로 알려주세요~