학습 목표
- 커져도 이해하기 쉬운 프로젝트 구조의 역할과 적용 조건을 설명할 수 있다.
- 현재 폴더와 주요 요청 흐름을 먼저 기록하세요.
- 작은 리팩터링 후 기존 화면과 저장 동작이 유지되는지 확인하세요.
사전 지식
앞선 사용자가 이해하는 UI/UX 설계를 먼저 읽으면 용어를 이해하기 쉽습니다. 이미 아는 내용이면 이 장부터 시작해도 됩니다.
개념 이해
처음부터 폴더를 많이 만드는 것이 좋은 설계는 아닙니다. 파일을 바꾸는 이유가 비슷한 기능을 묶고, 여러 곳이 쓰는 코드만 공통 영역으로 옮깁니다.
폴더별 역할
app은 라우트·화면 진입, components는 UI, features는 인증·사용자·프로젝트 같은 기능, services는 외부 통신, hooks는 화면 상태 로직, utils는 작은 도구, types는 공유 형태, styles는 디자인을 담을 수 있습니다.
관심사와 API 호출 분리
로그인 UI 안에 관리자 키와 모든 DB 조회를 넣지 않습니다. 서버 요청 처리와 화면 상태를 분리하면 권한과 오류를 독립적으로 검토하기 쉽습니다.
상태와 환경설정
입력 중인 값·로그인 정보·서버 데이터를 구분합니다. 환경별 주소·비밀은 코드 상수와 섞지 말고 서버 전용·공개 설정을 나눕니다.
이름과 의존성
의미가 드러나는 파일·함수 이름을 씁니다. 공통 UI가 특정 기능 전체를 불러오는 순환 의존을 피하고 라이브러리는 필요한 경우만 추가합니다.
점진적 확장
작을 때는 app/components/lib로 충분할 수 있습니다. 여러 파일이 같은 이유로 자주 바뀔 때 feature로 묶습니다. 프레임워크 라우트 규칙은 임의 예시보다 우선합니다.
실제 사용 사례
서비스 등록 폼에서 외부 메타데이터 API 호출을 lib 또는 services로 옮기고 검증 함수를 분리하세요. 화면 오류와 서버 오류가 어느 파일에서 생겼는지 더 빨리 찾을 수 있습니다.
단계별 실습
실습은 운영 서비스가 아닌 별도 연습 프로젝트에서 진행하세요. 기존 파일이 있다면 변경 전 기록을 남깁니다.
- 현재 폴더와 주요 요청 흐름을 먼저 기록하세요.
- 공통 버튼과 기능 전용 컴포넌트를 구분하세요.
- API 호출·검증·비즈니스 규칙을 이름이 명확한 모듈로 나누세요.
- 작은 리팩터링 후 기존 화면과 저장 동작이 유지되는지 확인하세요.
코드와 프롬프트
아래 코드는 일반적인 기능 중심 앱의 설계 예시이며 실제 라우트 규칙에 맞게 조정하는 환경의 예시입니다. 실제 프로젝트의 버전과 기존 구성을 확인한 뒤 필요한 부분만 적용하세요.
src/
app/
components/common/
components/ui/
features/auth/
features/users/
features/projects/
services/api/
services/firebase/
hooks/
utils/
types/
styles/아래 요청에서 대괄호 부분을 내 프로젝트에 맞게 바꾼 뒤 AI 도구에 전달하세요.
[프로젝트 경로]의 구조와 의존성을 먼저 설명해줘. 기능별 책임, 공통 UI, API 계층, 상태, 환경설정을 분리할 최소 계획을 제안하고 기존 동작을 유지하는 작은 단계로 진행해줘.자주 발생하는 문제와 해결
| 문제와 원인 | 해결 방법과 확인 기준 |
|---|---|
| 한 파일을 무조건 줄이기만 함 | 변경 이유가 다른 책임을 분리하고 무의미한 한 줄 파일은 늘리지 않습니다. |
| 예시 폴더를 그대로 복사해 라우트가 깨짐 | Next.js 등 실제 프레임워크의 파일 규칙을 먼저 확인합니다. |
핵심 요약
- 폴더 수보다 책임의 경계가 중요합니다.
- 프레임워크가 정한 라우트 규칙을 유지합니다.
완료 확인
참고자료
확인 기준일: 2026-10-20. 요금·사용 한도·제품 기능·설정 경로는 변경될 수 있으므로 작업 직전 공식 문서와 설치 버전을 확인하세요.