프로젝트 파일을 화면, 페이지, 통신, 공용 기능으로 나누는 초보 폴더 구조를 설명합니다. 파일이 늘어도 수정 위치를 찾는 정리 기준입니다.
폴더 구조의 목적은 파일을 많이 나누는 것이 아니라 다음 수정 위치를 예측할 수 있게 만드는 것입니다.
연재 안내: 27편 전체 순서와 현재 공개된 글은 비개발자 바이브코딩 로드맵에서 확인할 수 있습니다.
폴더를 나누기 전에 화면·서버·DB가 움직이는 순서를 이해하면 파일 역할을 정하기 쉽습니다.
한 줄 답변
프로젝트 파일 정리는 파일 수를 늘리는 일이 아니라 다음에 수정할 위치를 예측할 수 있게 역할별로 모으는 일입니다. 초보자는 화면 조각, 페이지, API 통신, 공용 도구 네 구역부터 시작하면 충분합니다.
파일이 적을 때 구조가 필요할까
첫날에는 파일이 대여섯 개뿐이라 한 폴더에 두어도 불편하지 않습니다. 하지만 화면과 기능이 늘면 버튼, 날짜 계산, 서버 요청, 설정 파일이 섞입니다. 그때 AI가 “관련 파일을 보내달라”고 해도 무엇을 보여줘야 할지 알기 어렵습니다.
좋은 폴더 구조는 대기업 구조를 흉내 내는 것이 아닙니다. 미래의 내가 파일 이름만 보고 역할을 추측할 수 있게 만드는 책상 서랍입니다.
초보자를 위한 네 개의 서랍
프로젝트 종류에 따라 이름은 달라도 역할은 비슷합니다.
src/
components/
pages/
services/
utils/components: 반복해서 쓰는 화면 조각
버튼, 입력창, 카드, 메뉴처럼 여러 화면에서 다시 쓰는 UI를 둡니다. 한 파일은 가능하면 한 화면 역할에 집중합니다. Common.js보다 ReservationCard.js처럼 무엇을 보여주는지 드러나는 이름이 좋습니다.
pages: 사용자가 방문하는 한 화면
예약 등록, 예약 목록, 로그인처럼 주소와 연결되는 큰 화면을 둡니다. 페이지는 여러 component를 조합하지만 데이터 저장 규칙과 외부 통신을 모두 직접 떠안지 않게 합니다.
services 또는 api: 외부와 통신하는 코드
서버에 예약을 저장하거나 목록을 가져오는 함수, 외부 API 호출을 모읍니다. 화면 파일 곳곳에 서버 주소가 반복되면 주소가 바뀔 때 여러 파일을 수정해야 하므로 통신 역할을 한곳으로 모읍니다.
utils: 작고 재사용 가능한 공용 기능
날짜 표시, 금액 형식, 문자열 정리처럼 특정 화면에만 속하지 않는 작은 함수를 둡니다. 모든 것을 utils에 넣으면 다시 잡동사니 서랍이 되므로 입력과 출력이 분명하고 여러 곳에서 쓰는 기능만 넣습니다.
설정 파일은 어디에 둘까
package.json, .env.example, README, 빌드 설정은 프로젝트 루트에서 관리하는 경우가 많습니다. 실제 비밀값이 들어 있는 .env는 Git에 올리지 않고, 필요한 변수 이름만 적은 .env.example을 공유합니다.
README에는 최소한 설치 명령, 실행 명령, 필요한 환경변수 이름, 주요 폴더 역할을 적습니다. AI 대화가 사라져도 다른 사람이 프로젝트를 실행할 수 있어야 합니다.
파일을 나누기 전에 확인할 기준
줄 수만 보고 자르지 마세요. 다음 질문 중 하나에 예라면 분리를 검토합니다.
- 화면 코드와 서버 요청이 한 함수 안에 섞여 있는가?
- 같은 날짜 계산이나 검증 코드가 여러 파일에 복사됐는가?
- 파일 이름으로 역할을 알기 어려운가?
- 작은 수정에도 관련 없는 코드까지 함께 열어야 하는가?
- AI가 매번 파일 전체를 교체하려 하는가?
반대로 열 줄짜리 파일을 역할 없이 여러 개로 나누면 이동만 늘어납니다. 한 파일이 한 가지 책임을 설명할 수 있는지가 기준입니다.
AI에게 폴더 정리를 요청하는 방법
현재 프로젝트 파일 트리를 보고 화면, 페이지, API 통신, 공용 기능으로 분류해줘. 코드는 아직 옮기지 말고 각 파일의 현재 역할과 이동 후보만 표로 보여줘. 기존 실행 명령과 import 경로(파일끼리 서로 불러오는 연결 주소)가 깨지지 않는 3단계 이동 계획을 제안해줘.
계획을 확인한 뒤 한 폴더씩 옮기고 매 단계 앱을 실행합니다. 한 번에 전체 구조를 바꾸면 import 경로 오류가 어디서 생겼는지 찾기 어렵습니다.
정리된 폴더는 AI에게 수정 범위를 알려주는 지도입니다.
현재 폴더를 정리하는 안전한 순서
먼저 프로젝트 파일 트리를 텍스트로 저장하고 현재 실행 결과를 확인합니다. 각 파일 옆에 화면, 통신, 계산, 설정, 모름 중 하나를 표시하세요. 역할이 분명한 파일부터 폴더 후보로 옮기고 import 경로를 수정한 뒤 즉시 실행합니다.
역할이 모름인 파일은 억지로 이동하지 않습니다. 어떤 화면과 함수가 사용하는지 검색한 뒤 결정합니다. 같은 이름의 백업 파일이나 final, final2처럼 출처가 불명확한 복사본은 바로 삭제하지 말고 Git 추적 여부와 실제 import 여부를 먼저 확인합니다.
한 단계가 끝날 때마다 변경 파일 목록과 실행 결과를 커밋합니다. 폴더 정리 중 기능 개선 욕심이 생겨도 별도 작업 목록으로 옮기세요. 파일 이동과 로직 수정이 섞이면 오류 원인을 찾기 어려워집니다.
정리가 끝나면 새 기능 하나의 위치를 예상해보세요. 새 페이지, 재사용 버튼, 서버 요청, 날짜 변환 코드가 각각 어디에 들어갈지 망설이지 않고 말할 수 있다면 폴더 구조가 역할을 잘 설명하고 있는 것입니다. 여전히 모든 코드가 한 폴더로 모이거나 어느 서랍에도 맞지 않는다면 프로젝트의 실제 책임에 맞게 이름과 구분을 한 번 더 조정합니다.
프로젝트 파일 정리 최종 점검
프로젝트 파일 정리는 폴더 수를 늘리는 일이 아니라 파일마다 한 가지 역할과 예측 가능한 이름을 주는 일입니다. 프로젝트 파일 정리를 시작하기 전 화면, 페이지, API 통신, 공용 기능으로 현재 파일을 분류하고 어디에도 속하지 않는 파일의 책임부터 확인하세요.
파일을 옮길 때는 한 번에 한 묶음만 이동하고 import 경로를 고친 뒤 핵심 화면을 실행하세요. 이동 전후 동작이 같다는 것을 확인하고 커밋하면 구조 정리 때문에 기능 오류가 생겨도 변경 범위를 빠르게 되돌릴 수 있습니다.
프로젝트 구조를 정리했다면 다음 글인 API 키 저장 방법: 환경변수 사용법에서 비밀값을 코드와 Git 기록에서 분리하는 방법을 확인하세요.
바이브코딩 전체 순서 보기
바이브코딩 뜻, 하는법, 도구 선택, API 연결, 데이터베이스, 배포 흐름은 바이브코딩 가이드에서 이어서 볼 수 있습니다.
