aiskillstore Project Structure
프로젝트 폴더 구조를 업계 표준에 맞게 정리하는 스킬입니다.
Core Principles
"바탕화면에 코드를 두지 않는다" "분류 기준을 섞지 않는다"
Safety Rules
| 명령어 | 상태 | 대안 |
|---|---|---|
rm -rf |
🔴 금지 | _legacy/로 이동 |
rm |
🔴 금지 | _legacy/로 이동 |
mv to _legacy/ |
✅ 허용 | 기본 정리 방식 |
mkdir |
✅ 허용 | 새 구조 생성 |
정리 방식
# ❌ NEVER: 삭제
rm -rf old-folder
# ✅ ALWAYS: 레거시 폴더로 이동
mkdir -p _legacy
mv old-folder _legacy/old-folder_$(date +%Y%m%d)
Part 1: 개발 루트 디렉토리
권장 루트 위치
~/dev # 가장 추천
~/code
~/workspace
~/git
컨텍스트(목적) 중심 구조 (추천)
~/dev/
├── work/ # 회사 업무
│ ├── company-a/
│ │ ├── backend-api/
│ │ └── frontend-ui/
│ └── company-b/
├── personal/ # 개인/사이드 프로젝트
│ ├── my-blog/
│ └── todo-app/
├── study/ # 강의/책 실습
│ ├── algorithm-101/
│ └── react-course/
├── open-source/ # Fork/기여 프로젝트
│ └── some-lib/
├── playground/ # 일회성 테스트 (샌드박스)
│ └── test-script.py
└── dotfiles/ # 개인 설정 파일 버전관리
호스트(Source) 중심 구조 (Go 스타일)
~/dev/
├── github.com/
│ ├── my-username/
│ │ └── project-a/
│ └── other-user/
│ └── awesome-lib/
├── gitlab.com/
│ └── company-group/
│ └── company-project/
└── bitbucket.org/
Part 2: 프로젝트 내부 구조
기본 프로젝트 스캐폴딩
project-name/
├── src/ # 실제 소스 코드
├── assets/ # 이미지, 폰트, 정적 파일
├── config/ # 설정 파일
├── docs/ # 문서화 자료
├── scripts/ # 빌드/배포 스크립트
├── tests/ # 테스트 코드
├── dist/ # 빌드 결과물 (Git 제외)
├── _legacy/ # 정리된 레거시 코드
├── .gitignore
├── .env.example # 환경변수 예시 (.env는 Git 제외)
├── README.md
└── LICENSE
Part 3: 프론트엔드 아키텍처 패턴
Pattern A: Next.js App Router + Colocation
라우트(페이지) 기준으로 폴더 생성, 필요한 파일을 같은 폴더에 배치
app/
├── (marketing)/ # Route Group (URL에 미반영)
│ ├── page.tsx
│ ├── components/ # 이 라우트 전용 컴포넌트
│ │ └── Hero.tsx
│ └── styles.css
├── dashboard/
│ ├── layout.tsx
│ ├── page.tsx
│ ├── loading.tsx
│ ├── error.tsx
│ └── components/
│ ├── DashboardHeader.tsx
│ └── DashboardStats.tsx
├── api/
│ └── users/
│ └── route.ts
└── globals.css
lib/ # 공용 유틸리티
components/ # 전역 공용 컴포넌트
적합한 경우: Next.js 기반 프로젝트
Pattern B: Bulletproof React (Feature-based)
기능(Feature) 단위로 묶어서 유지보수 용이한 구조
src/
├── app/ # 앱 초기화 (라우터, 엔트리, 전역 설정)
│ ├── routes/
│ ├── App.tsx
│ └── main.tsx
├── assets/
├── components/ # 완전 공용 UI
│ ├── Button/
│ ├── Modal/
│ └── Form/
├── config/
├── features/ # 🔑 핵심: 기능 단위
│ ├── auth/
│ │ ├── api/
│ │ ├── components/
│ │ ├── hooks/
│ │ ├── types/
│ │ └── index.ts
│ ├── users/
│ │ ├── api/
│ │ ├── components/
│ │ ├── hooks/
│ │ └── index.ts
│ └── dashboard/
├── hooks/ # 전역 훅
├── lib/ # 외부 라이브러리 래퍼
├── providers/
├── stores/
├── testing/
├── types/ # 전역 타입
└── utils/ # 전역 유틸리티
적합한 경우: 팀 규모가 크거나 기능이 많은 React 프로젝트
Pattern C: Feature-Sliced Design (FSD)
계층(Layer)으로 분류하는 아키텍처 방법론
src/
├── app/ # Layer 1: 앱 초기화
│ ├── providers/
│ ├── styles/
│ └── index.tsx
├── pages/ # Layer 2: 페이지 (라우트)
│ ├── home/
│ ├── profile/
│ └── settings/
├── widgets/ # Layer 3: 독립적인 UI 블록
│ ├── header/
│ ├── sidebar/
│ └── footer/
├── features/ # Layer 4: 사용자 시나리오
│ ├── auth/
│ ├── comments/
│ └── likes/
├── entities/ # Layer 5: 비즈니스 엔티티
│ ├── user/
│ ├── post/
│ └── comment/
└── shared/ # Layer 6: 공유 리소스
├── ui/
├── lib/
├── api/
└── config/
적합한 경우: 규칙을 팀이 같이 지킬 수 있는 중대형 프로젝트
Part 4: 하이브리드 패턴 (Next.js + Feature)
Next.js App Router를 뼈대로, features 방식을 섞은 실용적 구조
app/ # Next.js App Router
├── (marketing)/
├── dashboard/
└── api/
src/
├── components/ # 전역 공용 컴포넌트
├── features/ # Bulletproof 스타일 기능 단위
│ ├── auth/
│ ├── users/
│ └── analytics/
├── hooks/
├── lib/
├── types/
└── utils/
Workflow: 폴더 정리
1. 현재 구조 분석
# 최상위 폴더 확인
ls -la
# 트리 구조 확인 (2단계)
find . -maxdepth 2 -type d | head -30
2. 레거시 폴더 생성
mkdir -p _legacy
3. 정리 대상 이동
# 날짜 태그 붙여서 이동
mv messy-folder _legacy/messy-folder_$(date +%Y%m%d)
4. 새 구조 생성
# Bulletproof 구조 예시
mkdir -p src/{app,assets,components,config,features,hooks,lib,types,utils}
mkdir -p src/features/{auth,users}/{api,components,hooks,types}
5. 파일 이동
# 기능별로 파일 이동
mv src/components/LoginForm.tsx src/features/auth/components/
mv src/hooks/useAuth.ts src/features/auth/hooks/
Naming Conventions
| 규칙 | 예시 | 설명 |
|---|---|---|
| kebab-case | my-project |
폴더명 (공백 금지) |
| PascalCase | UserProfile.tsx |
React 컴포넌트 |
| camelCase | useAuth.ts |
훅, 유틸리티 |
| UPPER_CASE | API_URL |
상수 |
Anti-patterns
❌ 언어별 분류
~/dev/python/
~/dev/javascript/
→ React + Django 프로젝트는 어디에?
❌ 바탕화면 사용
~/Desktop/새 폴더/test1/asdf/
→ ~/dev/playground/ 사용
❌ 공백 있는 폴더명
My Project/
→ my-project/
❌ 타입별로만 분류 (규모가 클 때)
src/
├── components/ # 100개 컴포넌트
├── hooks/ # 50개 훅
└── utils/ # 30개 유틸
→ features/ 단위로 그룹화
Quick Setup Scripts
macOS/Linux: 개발 루트 생성
mkdir -p ~/dev/{work,personal,study,open-source,playground,dotfiles}
프로젝트 스캐폴딩
# 프로젝트 기본 구조
mkdir -p {src,assets,config,docs,scripts,tests,_legacy}
touch README.md .gitignore .env.example
Bulletproof React 구조
mkdir -p src/{app/routes,assets,components,config,features,hooks,lib,providers,stores,testing,types,utils}