제가 작업했던 모든 SvelteKit 프로젝트는 20번째 라우트를 전후하여 비슷한 벽에 부딪힙니다. 앱은 정상적으로 실행되지만, '이 파일은 어디에 두어야 하나요?'라는 간단한 질문에 아무도 답할 수 없습니다. 비즈니스 로직이 +page.server.ts로 들어가고, utils.ts는 600줄까지 늘어나며, 어느 날 갑자기 데이터베이스 클라이언트가 컴포넌트에 직접 임포트된 것을 발견하게 됩니다.

폴더 구조에 대한 조언은 많이 있지만, 대부분은 초보자용 튜토리얼이거나 유일한 정답처럼 제시되는 단 하나의 의견 기반 레이아웃입니다. 실제 프로젝트는 그보다 훨씬 복잡합니다. 세 개의 라우트로 구성된 소규모 사이트에 완벽한 구조가 40명의 엔지니어가 참여하는 플랫폼에는 적합하지 않으며, 그 반대도 마찬가지입니다.

그래서 저는 Claude 스킬을 만들었습니다. 이 스킬은 시니어 아키텍트처럼 프로젝트 구조를 다룹니다. 즉, 규모와 팀에 대해 질문하고, 규칙을 강요하기보다 트레이드오프(tradeoffs)를 설명하며, 단 하나의 정답 레이아웃이 존재한다고 절대 가장하지 않습니다.

기능

이 스킬은 두 가지 모드로 작동합니다.

1. 처음부터 설계 (Design from scratch). 단순히 폴더 트리를 제시하는 것으로 끝나지 않습니다. 먼저 규모, 팀, 도메인, 프로젝트의 예상 수명에 대해 질문한 다음, 너무 빨리 재작업할 필요가 없을 가장 간단한 구조를 추천해 줍니다. 작은 앱을 과도하게 엔지니어링(over engineering) 하는 것은 큰 앱을 충분히 엔지니어링하지 않는 것만큼이나 비용이 많이 듭니다.

2. 기존 프로젝트 검토 (Review an existing project). 이 부분이 진가를 발휘하는 곳입니다. 기능 전체를 끝까지 추적하고, 서버와 클라이언트 경계를 조사하며, 체크리스트를 실행한 다음, 요약 보고서(executive summary), 강점, 영향도 순으로 나열된 약점, 10점 만점의 아키텍처 점수, 즉각적 및 장기 개선 사항, 제안된 폴더 트리, 마이그레이션 계획, 위험 요소, 그리고 최종 권장 사항을 담은 보고서를 생성합니다.

다음은 지저분한 샘플 앱 검토에서 나온 약점 섹션의 예시입니다:

- [Critical] 서버/클라이언트 경계 누수. lib/stripe.ts가 시크릿 키를 사용하며 컴포넌트 내부에 임포트되었습니다. 브라우저로 자격 증명이 유출될 위험이 있습니다.
- [High] 모듈 범위의 사용자별 상태. lib/store.ts가 currentUser를 내보냅니다.
...

각 발견 사항은 어디에 나타나는지, 프로젝트가 성장함에 따라 왜 문제가 될 수 있는지, 그리고 앱이 매 단계마다 배포 가능하도록 점진적으로 어떻게 수정할 수 있는지와 함께 제공됩니다.

SvelteKit에 특화된 이유

일반적인 프론트엔드 조언으로는 도움이 되지 않습니다. 왜냐하면 SvelteKit의 관례(conventions)가 핵심을 지탱하기 때문입니다. $lib/server 경계는 빌드에 의해 강제되는 실제 보안 보장입니다. $env 모듈은 브라우저에 무엇이 도달할 수 있는지 결정합니다. 라우트 그룹(Route groups)은 세그먼트를 추가하지 않으면서 URL 트리를 구성합니다. Runes는 공유 상태가 어떻게 조직되는지를 변경했습니다. 이 스킬은 이러한 메커니즘을 중심으로 구축되었으며, 프레임워크가 진화함에 따라 안내가 정직하게 유지되도록 기능을 안정적(stable), 실험적(experimental), 또는 사용 중단(deprecated)으로 분류합니다.

또한 버전 번호나 공식 문서 링크를 코드 내부에 하드코딩하는 것을 피하여, 새로운 버전이 출시될 때마다 내용이 구식이 되는 것을 방지했습니다.

설치하기

이 스킬은 GitHub에 있으며, Claude Code 및 다른 에이전트와 함께 작동하는 skills CLI를 통해 단일 명령어로 설치할 수 있습니다:

npx skills add poolcamacho/sveltekit-project-structure

그 후 자연스럽게 질문하기만 하면 됩니다.