📝 docs: Add core folders and file structure, update project info

Author: 0disoft

.clinerules

@@ -1,60 +1,157 @@
-# Project Rules
-
-## 📁 디렉터리 개요
-- /README.md
-  # TL;DR, 프로젝트 목표·범위·주요 용어 5줄 요약
-- /.handbook/              # 상세 레퍼런스 전용
-
-## ⬇️ 문서 우선순위 & 역할 (참고)
-### 1. 핵심 (모든 프로젝트)
-- .handbook/architecture.md
-  # C4 다이어그램, 폴더·네이밍 규칙, 데이터 흐름
-
-### 2. 권장 (중·대형)
-- .handbook/stack.md
-  # 언어·런타임·프레임워크 선정 이유·버전
-- .handbook/dev-guidelines.md
-  # 코드 스타일, 브랜치·PR·커밋 가이드라인
-- .handbook/api-contract.yaml
-  # OpenAPI / GraphQL 스펙 – 엔드포인트·스키마·에러 모델
-- .handbook/data-model.md
-  # DB ERD·인덱스·제약·마이그레이션 규칙
-- .handbook/api-optimization.md
-  # API 호출 최적화 및 비용 절감 가이드라인
-
-### 3. 확장 (대형·프로덕션)
-- .handbook/quality.md
-  # 테스트 전략, SLO·보안·로깅·모니터링 목표
-- .handbook/ci-cd.md
-  # 빌드→테스트→배포→롤백 파이프라인
-- .handbook/env.example
-  # 필수 환경변수 샘플
-- .handbook/secrets.md
-  # 키 관리·회전·GDPR·CCPA 체크
-- .handbook/adr/000x-*.md
-  # Architecture Decision Record: 문제·대안·결정·근거
-- .handbook/ai-collab.md
-  # AI 프롬프트 형식·금지어·출력 포맷·override 규칙
-
-## 🧑‍💻 작업 가이드라인
-1. **파일 존재 여부 먼저 확인** → 있으면 참고, 없으면 기본 관습 적용을 고려합니다.
-2. **아키텍처에 영향을 미치는 중요한 결정 또는 기술/의존성 도입 시** ⇒ `.handbook/adr/`에 ADR 템플릿 추가를 제안합니다. (예: 새 프레임워크 도입, 핵심 데이터 모델 변경 등)
-3. **필요 문서가 없을 때**  
-   - *단순* : README 또는 관련 파일에 간단 설명 추가를 제안합니다.  
-   - *스펙* : 최소 스켈레톤(예: OpenAPI 3.1) 생성을 고려합니다.
-4. **커밋 메시지** ⇒ Gitmoji 스타일을 권장합니다 (`.handbook/dev-guidelines.md` 참고).
-5. **PR 병합 조건** ⇒ `.handbook/quality.md`의 테스트 커버리지·SLO 목표 충족 시 병합을 고려합니다.
-
-## 🤖 응답 포맷 가이드라인
-- 기본 : 코드 먼저, 설명 ≤3줄
-- 정보 부족 : “Clarify needed: …” 짧게 질문
-- 금지 : `any` 타입, `console.log`, 미승인 라이브러리
-- 코드 스타일: 레거시 코드는 LLM 재량으로 모던 스타일로 변경 가능
-
-## 🏷 셀프체크
-- [ ] 수정/추가 파일 실제 존재?
-- [ ] .handbook/stack.md 버전·라이브러리 준수? (없으면 README 참고)
-- [ ] quality.md 있을 때만 테스트·SLO 강제
-- [ ] 아키텍처에 중요한 변경/기술 도입 시 ADR 작성?
-
-# 끝
+# .clinerules
+# 중요: 이 '.clinerules' 파일 자체는 AI가 인식할 수 있도록 반드시 프로젝트의 루트(최상위) 디렉토리에 위치해야 합니다.
+#
+# 이 파일은 AI에게 프로젝트 진행 시 각 주요 파일의 역할과 참고 방식을 안내하기 위한 가이드라인입니다.
+#
+# 참고: 본 규칙 파일에 언급된 모든 문서 파일(예: .md, .toml)은 기본적으로 프로젝트 루트 내 'vibe-workflow/' 폴더에 위치하는 것을 기준으로 합니다.
+# 만약 다른 경로를 사용한다면, 아래 규칙들의 파일 경로를 그에 맞게 수정해야 합니다.
+
+# --- 최상위 원칙 ---
+# 이 섹션의 원칙은 모든 AI 행동의 기반이 됩니다.
+- AI는 본 가이드라인 및 참고 파일에 명시된 내용을 바탕으로, 이 레포지토리의 목적(LLM 규약 및 워크플로우 설정)에 부합하는 범위 내에서 사용자의 요청에 따라 프로젝트의 파일(소스 코드, 설정 파일, 문서 등)을 추가, 수정, 삭제할 수 있습니다.
+- 특정 작업 유형(새로운 외부 라이브러리/패키지 설치, 주요 의존성 변경, 시스템 환경에 큰 영향을 미치는 작업 등)에 대해서는 AI가 실행 전, 해당 작업의 필요성과 예상 범위를 사용자에게 알리고 명시적인 승인을 받은 후에만 실행합니다. 이는 "최상위 원칙"의 이전 버전에 상세히 기술된 바와 같습니다.
+- 파일 수정이나 업데이트는 기본적으로 사용자 요청 시 수행되지만, AI는 대화의 맥락이나 주어진 작업의 성격에 따라 특정 문서의 업데이트 필요성을 인지하고 사용자에게 제안하거나 관련 정보를 제공할 수 있습니다.
+
+# --- 일반적인 프로젝트 상황 및 의사 결정 ---
+# 파일: vibe-workflow/meeting_notes.toml
+# 역할: 프로젝트 관련 논의 및 결정 사항 기록, LLM의 주요 의사결정 참고 자료
+# LLM 참고 가이드:
+# - 이 파일은 사용자와의 대화에서 도출된 주요 결정 사항, 요구사항 변경, 작업 지시 등 프로젝트 히스토리를 이해하는 데 중요한 정보를 담고 있습니다.
+# - AI는 새로운 작업을 시작하거나 의사결정이 필요한 경우, 이 파일의 내용을 참고하여 과거 맥락과의 일관성을 유지하고, 관련된 최신 정보를 바탕으로 작업을 수행합니다.
+# - 사용자의 요청에 따라, 대화 중 발생한 중요 내용은 이 파일에 기록하여 관리할 수 있습니다.
+
+# --- 설계 및 요구사항 ---
+# 이 섹션의 문서들은 코드와 동기화된 최신 상태 유지를 목표로 하며, LLM은 각 문서의 역할을 이해하고 작업 시 적극 활용합니다.
+
+# 파일: vibe-workflow/requirements_definition.md
+# 역할: 프로젝트의 전반적인 목표와 핵심 요구사항 정의
+# LLM 참고 가이드:
+# - 이 문서는 프로젝트가 무엇을 만들려고 하는지에 대한 상위 수준의 요구사항을 정의합니다.
+# - AI는 코드 변경이나 새로운 기능 설계 시, 이 문서에 명시된 핵심 요구사항을 우선적으로 고려하여 작업 방향을 설정합니다.
+# - 요구사항에 변경이 발생하면, 해당 내용이 이 문서에 반영될 수 있도록 사용자와 소통합니다.
+
+# 파일: vibe-workflow/feature_specification.md
+# 역할: 개별 기능에 대한 상세 명세 (동작 방식, 사용자 시나리오, 입출력 등)
+# LLM 참고 가이드:
+# - `requirements_definition.md`를 바탕으로 각 기능의 구체적인 사양을 기술합니다.
+# - AI는 특정 기능 개발 또는 수정 시, 이 문서의 상세 명세를 기준으로 작업합니다.
+# - 기능의 세부 사항 변경 시, 이 문서의 내용도 함께 업데이트되는 것이 이상적입니다.
+
+# 파일: vibe-workflow/api_specification.yaml (OpenAPI/Swagger 형식 권장)
+# 역할: 프로젝트 API의 엔드포인트, 요청/응답 구조, 인증 방식 등 기술적 명세
+# LLM 참고 가이드:
+# - AI는 API 관련 코드(예: 컨트롤러, 서비스, 클라이언트 SDK 등) 작업 시 이 명세를 기준으로 합니다.
+# - 새로운 API가 추가되거나 기존 API의 사양이 변경될 경우, 이 파일의 업데이트 필요성을 인지하고 관련 작업을 지원합니다.
+# - 프론트엔드 또는 다른 백엔드 서비스와의 명확한 계약(contract) 역할을 합니다.
+
+# 파일: vibe-workflow/database_schema.dbml
+# 역할: 데이터베이스 스키마(테이블, 컬럼, 관계 등) 정의 및 LLM의 데이터 구조 이해 자료
+# LLM 참고 가이드:
+# - AI는 데이터베이스 관련 코드(모델, 마이그레이션, 쿼리 등) 작업 시 이 스키마를 참고하여 데이터의 전체 구조와 관계를 파악합니다.
+# - 이 파일은 LLM이 스키마의 의도와 큰 그림을 이해하는 데 중점을 두며, 엄격한 실행 SQL 문법보다는 가독성과 이해 용이성을 우선합니다.
+# - 스키마 변경 시, 이 파일에도 해당 내용이 반영되도록 합니다.
+
+# 파일: vibe-workflow/ui_guidelines.md
+# 역할: UI/UX 디자인 원칙, 컴포넌트 스타일, 레이아웃 규격 등 정의
+# LLM 참고 가이드:
+# - AI는 UI 관련 코드(예: 프론트엔드 컴포넌트, 스타일시트) 작업 시 이 가이드라인을 참고하여 일관된 사용자 경험을 제공하도록 노력합니다.
+# - 새로운 UI 컴포넌트 설계 또는 기존 UI 개선 시, 이 문서의 원칙을 따릅니다.
+
+# --- 코딩 표준 및 컨벤션 ---
+# 파일: vibe-workflow/coding_conventions.md
+# 역할: 프로젝트의 코딩 스타일, 명명 규칙, 주석 가이드 등 표준 정의
+# LLM 참고 가이드:
+# - AI는 모든 코드 생성 및 수정 시 이 문서에 정의된 코딩 표준과 컨벤션을 따르는 것을 목표로 합니다.
+# - 일관된 코드 스타일 유지를 위한 기준으로 삼으며, 기존 코드가 컨벤션에 맞지 않거나 더 나은 컨벤션이 제안될 경우 이 문서의 개선을 고려할 수 있습니다.
+
+# --- 프로젝트 구조 및 파일 관리 ---
+# 파일: vibe-workflow/project_structure.toml
+# 역할: 프로젝트의 주요 디렉터리 및 파일 구조, 각 부분의 역할 설명
+# LLM 참고 가이드:
+# - AI는 이 파일을 통해 프로젝트의 전반적인 아키텍처와 파일 구성을 이해하고, 파일 생성/이동/삭제 작업 시 참고합니다.
+# - `node_modules`, `dist`, `build` 등 LLM 작업에 직접적이지 않은 대량의 파일/폴더는 이 파일에서 제외하여 가독성을 유지합니다.
+# - 프로젝트 구조에 변경이 있을 시, 이 파일의 내용도 업데이트하여 최신 상태를 반영하는 것이 좋습니다.
+
+# --- 프로젝트 설정 및 환경 ---
+# (주의: 의존성 변경 등 실제 환경에 영향을 주는 작업은 "최상위 원칙"의 사용자 승인 절차를 따릅니다.)
+
+# 파일: package.json, pyproject.toml, requirements.txt 등 (프로젝트 루트 위치)
+# 역할: 프로젝트 의존성 및 관련 스크립트 정의
+# LLM 참고 가이드:
+# - AI는 라이브러리 추가/삭제/버전 변경 등의 작업 시 이 파일들을 참고하고, 사용자 승인 하에 수정합니다.
+
+# 파일: vibe-workflow/.env.example
+# 역할: 필요한 환경 변수 목록과 예시 제공 (실제 비밀값은 포함하지 않음)
+# LLM 참고 가이드:
+# - AI는 이 파일을 참고하여 어떤 환경 변수들이 프로젝트 실행에 필요한지 이해합니다. 실제 `.env` 파일은 AI가 직접 수정하지 않습니다.
+
+# 파일: vibe-workflow/configuration_guide.md
+# 역할: 프로젝트 설정 방법, 주요 설정 항목, 환경 변수 등에 대한 상세 설명
+# LLM 참고 가이드:
+# - AI는 프로젝트 설정과 관련된 문의 응답 또는 스크립트 작성 시 이 문서를 참고합니다.
+# - 새로운 설정 옵션 추가 등 변경 사항 발생 시 이 문서의 업데이트를 고려합니다.
+
+# --- 테스트 및 배포 ---
+# (주의: 배포 관련 작업 중 시스템 환경에 큰 영향을 줄 수 있는 경우, "최상위 원칙"의 사용자 승인 절차를 따릅니다.)
+
+# 파일: vibe-workflow/test_case_template.md
+# 역할: 테스트 케이스 작성 표준 형식 및 가이드 제공
+# LLM 참고 가이드:
+# - AI는 새로운 기능 추가나 코드 변경 시, 이 템플릿과 기존 테스트 코드 패턴을 참고하여 테스트 코드 작성을 지원합니다.
+# - 테스트 코드의 일관성과 품질 유지를 위한 기준으로 활용합니다.
+
+# 파일: Dockerfile, docker-compose.yml, deploy_script.sh 등 (프로젝트 루트 또는 지정된 위치)
+# 역할: 애플리케이션의 빌드, 배포, 실행 환경 구성
+# LLM 참고 가이드:
+# - AI는 배포 환경 구성 및 스크립트 관련 작업 시 이 파일들을 참고합니다.
+# - 관련 설정 변경 필요시, 사용자 승인 하에 또는 사용자의 요청에 따라 이 파일들을 수정할 수 있습니다.
+
+# --- AI 행동 및 결과물 형식 ---
+# 목표: AI는 사용자의 의도를 파악하고, 제공된 파일들의 역할을 이해하여 효율적으로 협업합니다.
+- AI는 새로운 것을 제안하기 전에 기존 프로젝트 유틸리티나 라이브러리, 그리고 본 가이드라인에 언급된 파일들의 내용을 우선적으로 확인하고 참고합니다.
+- AI는 사용자와의 대화에서 요청이 모호하거나 세부 정보가 부족하다고 판단되면, 가장 합리적인 방향을 제안하거나 필요한 추가 정보를 요청할 수 있습니다.
+- AI는 작업의 근거가 된 주요 참고 문서나 규칙을 사용자와의 대화 중 자연스럽게 언급하여 투명성을 높일 수 있습니다.
+
+# --- 주요 파일별 역할 및 LLM 참고 지침 (요약) ---
+# 이 섹션은 위에서 설명된 주요 파일들의 핵심 역할과 LLM이 참고해야 할 방식을 다시 한번 요약합니다.
+# AI는 각 파일의 목적을 이해하고, 사용자와의 효율적인 협업을 위해 아래 내용을 숙지합니다.
+
+# vibe-workflow/api_specification.yaml
+#   - 역할: API의 기술적 명세 (엔드포인트, 데이터 구조 등).
+#   - LLM 참고: API 관련 코드 작업 시 기준으로 활용. 변경 시 업데이트 필요성 인지.
+
+# vibe-workflow/coding_conventions.md
+#   - 역할: 일관된 코드 스타일을 위한 표준 및 컨벤션.
+#   - LLM 참고: 코드 생성/수정 시 준수 목표. 개선 제안 가능.
+
+# vibe-workflow/configuration_guide.md
+#   - 역할: 프로젝트 설정 방법 및 환경 변수 상세 안내.
+#   - LLM 참고: 설정 관련 문의 응답 및 스크립트 작성 시 참고.
+
+# vibe-workflow/database_schema.dbml
+#   - 역할: 데이터베이스 구조 및 관계 정의 (LLM의 이해 중심).
+#   - LLM 참고: 데이터 관련 코드 작업 시 전체 구조 파악용.
+
+# vibe-workflow/feature_specification.md
+#   - 역할: 개별 기능의 상세 동작 방식 및 요구사항.
+#   - LLM 참고: 기능 개발/수정 시 구체적인 구현 지침으로 활용.
+
+# vibe-workflow/meeting_notes.toml
+#   - 역할: 프로젝트 논의사항, 결정사항 등 히스토리 기록.
+#   - LLM 참고: 과거 맥락 파악 및 일관된 의사결정 지원.
+
+# vibe-workflow/project_structure.toml
+#   - 역할: 프로젝트 파일 및 디렉터리 구조와 역할 설명.
+#   - LLM 참고: 프로젝트 아키텍처 이해 및 파일 관리 시 참고.
+
+# vibe-workflow/requirements_definition.md
+#   - 역할: 프로젝트의 핵심 목표 및 상위 요구사항.
+#   - LLM 참고: 작업 방향 설정 및 핵심 요구사항 준수 여부 판단 기준.
+
+# vibe-workflow/test_case_template.md
+#   - 역할: 테스트 케이스 작성 표준 및 가이드.
+#   - LLM 참고: 테스트 코드 작성 지원 시 형식 및 내용 참고.
+
+# vibe-workflow/ui_guidelines.md
+#   - 역할: UI/UX 디자인 원칙 및 스타일 가이드.
+#   - LLM 참고: UI 관련 코드 작업 시 일관성 유지 위해 참고.

.github/workflows/deploy.yml

@@ -0,0 +1,72 @@
+name: Deploy SvelteKit Site to GitHub Pages
+
+on:
+  # main 브랜치에 푸시될 때마다 실행됩니다.
+  push:
+    branches:
+      - main
+  # GitHub Actions 탭에서 수동으로 실행할 수도 있게 합니다.
+  workflow_dispatch:
+
+# Actions가 GITHUB_TOKEN을 사용하여 GitHub Pages에 배포할 수 있도록 권한을 설정합니다.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# 한 번에 하나의 배포만 실행되도록 동시성 설정을 합니다.
+# 동일한 그룹에 대한 새 워크플로우 실행 시 이전 실행은 취소됩니다.
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4 # pnpm/action-setup 액션의 최신 버전을 확인하는 것도 좋습니다.
+        with:
+          version: 10 # 요청하신 pnpm 버전 10으로 변경
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4 # actions/setup-node 액션의 최신 버전을 확인하는 것도 좋습니다.
+        with:
+          node-version: "22" # 요청하신 Node.js 버전 22로 변경
+          cache: "pnpm" # pnpm 의존성 캐싱
+
+      - name: Install dependencies (frontend)
+        working-directory: ./frontend # frontend 폴더로 이동하여 명령어 실행
+        run: pnpm install
+
+      - name: Build SvelteKit site (frontend)
+        working-directory: ./frontend # frontend 폴더로 이동하여 명령어 실행
+        run: pnpm run build # SvelteKit 빌드 명령 (adapter-static 필요)
+
+      - name: Setup GitHub Pages
+        uses: actions/configure-pages@v5
+        # SvelteKit의 adapter-static이 `base` 경로를 자동으로 처리하므로
+        # 이 Action에서 base path를 별도로 설정할 필요가 없을 수 있습니다.
+        # 만약 username.github.io가 아닌 username.github.io/repo-name 형태라면
+        # SvelteKit의 paths.base 설정이 중요합니다.
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # SvelteKit의 adapter-static에서 설정한 빌드 출력 폴더 경로를 지정합니다.
+          # 기본적으로 'build' 폴더입니다. frontend 폴더 내의 경로로 지정해야 합니다.
+          path: ./frontend/build
+
+  deploy:
+    needs: build # build 작업이 성공해야 실행됨
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }} # 배포된 사이트 URL을 출력
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4