structured-file-layoutlisted

# structured-file-layout 코드 작성 전에 파일과 폴더 구조를 책임 단위로 설계한다. ## 핵심 원칙 > **1 파일 = 1 책임. 파일명이 그 책임을 드러낸다.** > 500줄 차단은 이 원칙이 상류에서 실패했다는 신호다 — 결과를 고치는 것이 아니라 원인을 잡는다. ## 발동 조건 - 새 파일을 만들기 전 - exec-plan 작성 시 - ��존 파일을 크게 수정하기 전 - 새 기능/모듈을 설계할 때 ## 설계 순서 ### 1단계 — 책임 한 줄 정의 파일을 만들기 전에 "이 파일은 ___만 한다"를 한 문장으로 완성한다. ``` # 올바른 예 auth_service.py → "JWT 발급과 검증만 한다" user_router.py → "유저 CRUD HTTP 라우팅만 한다" useAuthStore.ts → "인증 상태(토큰·사용자)만 관리한다" # 잘못된 예 (책임 2개 이상) utils.py → "여러 유틸 함수들" helpers.ts → "공통으로 쓰는 것들" ``` 한 문장에 "그리고", "또한", "및"이 들어가면 책임이 2개다 → 파일을 나눈다. ### 2단계 — 폴더 배치 결정 파일 타입이 아니라 **도메인/기능 단위**로 폴더를 구성한다. ``` # 올바른 예 (도메인 기준) features/ auth/ auth_service.py auth_router.py auth_schema.py task/ task_service.py task_router.py # 잘못된 예 (타입 ���준 — 도메인 파악 불가) services/ auth_service.py task_service.py routers/ auth_router.py task_router.py ``` 도메인이 명확히 다르면 폴더로 분리. 같은 폴더 내 파일이 5개를 넘으면 하위 폴더를 검토한다. ### 3단계 — 배럴 파일 계획 각 도메인 폴더에 `index.ts` / `__init__.py`를 두어 import 경로를 단순하게 유지한다. ```python # features/auth/__init__.py from .auth_service import AuthService from .auth_schema import TokenResponse ``` 외부에서는 `from features.auth import AuthService`만 알면 된다. ### 4단계 — exec-plan에 파일 트리 명시 계획 문서에 예상 파일 트리와 각 파일의 책임을 한 줄씩 기록한다. ```markdown ## 파일 구조 features/auth/ auth_service.py # JWT 발급·검증 auth_router.py # 로그인·로그아웃 엔드포인트 auth_schema.py # 요청/응답 Pydantic 모델 __init__.py # 배럴 export ``` 파일 트리 없이 코딩을 시작하지