Refectoring/docs-name-env

.agent/GEMINI.md

@@ -0,0 +1,87 @@
+# Project Guidelines & Rules
+
+## 1. Project Overview & Tech Stack
+- **Description:** A modern blog application using a Notion database as a Headless CMS, built with Next.js.
+- **Framework:** Next.js 16.1.1 (App Router)
+- **UI Library:** React 19
+- **Language:** TypeScript (Strict Mode)
+- **Styling:** Tailwind CSS 4, `class-variance-authority`, `clsx`, `lucide-react`. (**Do not create .css files**; use utility classes).
+- **CMS/Database:** Notion API (`@notionhq/client`) serving as the primary data source.
+- **Testing:** Vitest (Unit), Playwright (E2E), Testing Library.
+- **Package Manager:** `pnpm`
+
+## 2. AI Behavior Guidelines
+- **Language:** Always provide explanations and responses in **Korean**. However, write code comments, variable names, and commit messages in **English**.
+- **Reasoning:** Before writing code, always output the **"Reasoning Process"**. If the modification is extensive, present a **"Plan"** first and await user approval.
+- **Code Quality:** Prefer clear, multi-line code over unreadable one-liners. Remove unused variables and imports immediately.
+- **Error Handling:** When an error occurs, do not just fix it; summarize the **root cause** in one line. If a terminal command fails, stop the process immediately.
+- **Documentation:** Every works must be documented in /docs folder. There are several types of documents: 
+  - **/architectures** (for used architecture of the project)
+  - **/fixes** (for fixing bugs)
+  - **/plans** (for planning features)
+  - **/tests** (for testing features)
+  - ... (if you need to add more documents, add them and save them in /docs folder)
+  - **CHANGELOG.md** (always update this file when you make a change)
+- **Workflow Automation Rule:**
+  - When a task is deemed complete or the user indicates completion, do not commit immediately; **always initiate the `@finish` workflow.**
+  - Enforce the **[Code Review] -> [Request Approval] -> [Commit]** procedure. Do not suggest `git commit` directly.
+
+## 3. Server vs. Client Strategy (Architecture)
+- **Default to Server:** All components are **Server Components** by default.
+- **Client Boundary:** Use `'use client'` only when interactivity (`useState`, `onClick`, `useEffect`) is strictly needed.
+- **Data Fetching:** - Fetch data directly in Server Components using `async/await`. 
+  - **Do not** use `useEffect` for data fetching unless absolutely necessary.
+  - **Caching:** Notion API calls must be cached for **6 hours (21600s)** using `unstable_cache` to minimize API usage.
+- **Mutations:** Use **Server Actions** for any data mutations or form submissions. Do not use `pages/api` (API Routes).
+
+## 4. Coding Standards
+
+### 4.1 Naming & Structure
+- **Components:** `PascalCase` (e.g., `PostCard.tsx`).
+- **Functions/Variables:** `camelCase` (e.g., `getPostData`).
+- **Files:** Match the export name or use `kebab-case` for utility files/folders (e.g., `app/dashboard/settings`).
+- **Imports:** Use **absolute imports** (`@/components/...`) instead of relative paths.
+- **Co-location:** Group related components in subdirectories (e.g., `src/components/notion/`).
+
+### 4.2 Type Safety
+- **No `any`:** The use of `any` is strictly prohibited. Use `unknown` with Type Guards (or Zod) for validation.
+- **Strict Mode:** Assume `strict: true`; handle `null` or `undefined` rigorously.
+- **Explicit Returns:** Explicitly define the return type for all functions (do not rely on inference).
+- **Definitions:** Use `interface` for extensible objects; use `type` for unions/intersections.
+
+### 4.3 State Management Hierarchy
+1. **Server State:** Prefer fetching fresh data on the server (React Query/SWR if client-side fetching is needed).
+2. **URL State:** Store filter/search params in the URL (`useSearchParams`) for shareability.
+3. **Global State:** Use Context API or Zustand only if prop drilling exceeds 3 levels.
+
+### 4.4 Error Handling Pattern
+- **Server Actions:** Handle errors gracefully using `try/catch` and return structured objects:
+  ```ts
+  try {
+    // logic
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+    }
+    return { success: false, error: "Friendly error message" };
+  }
+  ```
+
+## 5. Workflows to AVOID 🚫
+- No API Routes: Do not use pages/api; use Server Actions.
+- No Hardcoded Secrets: Always use process.env.
+- No Huge Components: Break down components if they exceed 200 lines.
+- No New Packages: Do not install new npm packages without asking for approval first.
+- No Prop Drilling: Avoid passing props more than 3 levels deep.
+
+## 6. Environment & Commands
+- Environment Variables: NOTION_API_KEY, NOTION_POSTS_DATA_SOURCE_ID, NOTION_COMMENTS_DATA_SOURCE_ID.
+- Commands:
+    - pnpm dev: Start dev server (http://localhost:3000).
+    - pnpm build: Production build.
+    - pnpm test: Run unit tests.
+    - pnpm test:e2e: Run E2E tests.
+
+## 7. Documentation Etiquette
+- Code Comments: When writing complex logic, write a brief comment explaining "Why" (intent), not "What" (syntax).
+- JSDoc: Mandatory for all utility functions.

.agent/skills/SKILL.example.md

@@ -0,0 +1,23 @@
+---
+name: [스킬 이름]
+description: [이 스킬이 무엇을 하는지 한 줄 요약]
+triggers:
+  - [트리거 키워드 1] (예: @notion, @db)
+  - [트리거 키워드 2]
+---
+
+# [Skill Name] Context
+이 파일은 [특정 작업]을 수행할 때 AI가 따라야 할 가이드라인입니다.
+
+## 1. Goal (목표)
+- 무엇을 달성해야 하는지 명확히 정의
+
+## 2. Rules (제약 사항)
+- 절대 하지 말아야 할 것들
+
+## 3. Tool Usage (도구 사용법)
+- 관련된 함수나 스크립트 실행 방법
+
+## 4. Examples (예시 - 가장 중요 ⭐)
+User: [질문 예시]
+AI: [이상적인 답변 예시]

.agent/skills/code-review/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: Senior Code Reviewer
+description: Analyze code for performance, security, type safety, and Next.js best practices.
+triggers:
+  - @review
+  - @cr
+  - "코드 리뷰해줘"
+  - "이 코드 문제점 있어?"
+---
+
+# Code Review Skill
+
+## 1. Context
+You are a Senior Full-Stack Engineer reviewing a Pull Request. Your goal is to catch logical errors, performance bottlenecks, and maintainability issues before they merge.
+
+## 2. Review Checklist (Priority Order)
+1.  **Server vs Client Boundary:**
+    - Is `'use client'` used only when necessary? (Interactivity, Hooks)
+    - Are sensitive environment variables (`process.env.NOTION_API_KEY`) leaking into Client Components?
+2.  **Performance (Critical):**
+    - Are Notion API calls wrapped in `unstable_cache`? (Must be cached for 6 hours/21600s)
+    - Are images using `next/image` with proper `sizes` and `alt` tags?
+3.  **Type Safety:**
+    - Are there any explicit `any` types? (Flag immediately as Critical)
+    - Are API responses validated (e.g., checking if `properties` exist in Notion response)?
+4.  **Code Style:**
+    - Is the component too large (>200 lines)? Suggest splitting.
+    - Are tailwind classes organized? (Suggest `clsx` or `cn` usage for conditionals).
+
+## 3. Output Format
+Provide feedback in the following format:
+
+- **🔴 Critical:** (Bugs, Security, `any` type, Infinite loops)
+- **🟡 Improvement:** (Performance optimizations, better readability)
+- **🟢 Good:** (Praise for good patterns)
+
+## 4. Example Interaction
+**User:** "Review this code: `const data = await fetch(url).then(res => res.json())`"
+**AI:**
+"**🔴 Critical:**
+1. **Promise Handling:** Use `async/await` instead of `.then()` chains for readability.
+2. **Type Safety:** The return type is implicit `any`. Define an interface for the response.
+3. **Error Handling:** There is no `try/catch` or error checking.
+
+**🟡 Improvement:**
+- If this is a Server Component, consider wrapping `fetch` with `unstable_cache` if the data doesn't change often."
+

.agent/skills/git-manager/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: Git Commit Manager
+description: Generate semantic commit messages and manage branches.
+triggers:
+  - @git
+  - @wt
+  - @cm
+  - "commit message"
+  - "커밋해줘"
+---
+
+# Git Manager Skill
+
+## 1. Context & Resources
+- **Role:** You are an expert Git manager utilizing **Worktrees** for parallel development.
+- **Reference:** For specific commands (especially Worktree & Bare Repo setup), **ALWAYS refer to `./cheatsheet.md`** located in the same directory.
+
+## 2. Commit Message Convention
+Follow the **Conventional Commits** format:
+- `feat`: New features (blog post rendering, new API route)
+- `fix`: Bug fixes (hydration error, layout shift)
+- `docs`: Documentation changes
+- `style`: Code changes without logic change
+- `refactor`: Code changes without logic change
+- `test`: Test changes
+- `chore`: Config changes, dependency updates
+
+## 3. Workflow
+1. Analyze the `git diff` output.
+2. Summarize changes in English (imperative mood).
+3. If the change is huge, suggest splitting the commit.
+4. Consult `./cheatsheet.md` for exact syntax.
+
+## 4. Example
+**Input:** Changed the header background color and added a logo.
+**Output:**
+```bash
+style: update header design with new logo
+
+- Change background color to neutral-900
+- Add Logo component to navigation
+```

.agent/skills/git-manager/cheatsheet.md

@@ -0,0 +1,81 @@
+# 명령어,설명
+
+```bash
+git config --global user.name "이름" # 사용자 이름 설정
+git config --global user.email "이메일" # 사용자 이메일 설정
+git init # 현재 디렉토리를 Git 저장소로 초기화
+git clone --bare <url> .bare # 워크트리 사용을 위한 Bare Clone
+```
+
+## 워크트리
+워크트리 사용을 위한 명령어
+root 폴더에 .bare 폴더를 생성하고 그 안에 워크트리 폴더를 생성
+**항상 root 폴더에서 명령어를 실행해야 함**
+
+```bash
+
+git -C .bare worktree list # 현재 생성된 모든 워크트리(작업 폴더) 목록 확인
+git -C .bare worktree add ../<폴더명> <브랜치명> # 새 브랜치를 따면서 새 폴더 생성
+git -C .bare worktree add ../<폴더명> # 기존 브랜치를 새 폴더로 체크아웃
+git -C .bare worktree remove <폴더명> # 작업 폴더 삭제 (Git 연결 해제)
+git -C .bare worktree prune # 폴더를 강제 삭제(rm -rf)했을 때 찌꺼기 정리
+git -C .bare worktree move <구폴더> ../<신폴더> # 워크트리 폴더 경로/이름 변경
+```
+
+## 커밋
+
+```bash
+git status # 현재 파일 상태(변경됨, 스테이징됨) 확인
+git add . # 모든 변경사항을 스테이징 영역(Staging Area)에 추가
+git add <파일> # 특정 파일만 스테이징
+git commit -m "메시지" # 스테이징된 변경사항 확정(저장)
+git commit --amend # 방금 한 커밋의 메시지나 파일 수정 (덮어쓰기)
+```
+
+## 브랜치
+
+```bash
+git branch # 로컬 브랜치 목록 확인
+git branch -r # 원격 브랜치 목록 확인
+git branch <이름> # 새 브랜치 생성 (이동은 안 함)
+git branch -m <새이름> # 현재 브랜치 이름 변경
+git branch -d <이름> # 브랜치 삭제 (병합된 것만)
+git branch -D <이름> # 브랜치 강제 삭제
+git switch <브랜치> # 해당 브랜치로 이동
+git switch -c <이름> # 새 브랜치 만들면서 이동
+```
+
+## 원격 저장소
+
+```bash
+git fetch # 원격 저장소의 최신 이력만 가져옴 (병합 X)
+git pull origin <브랜치> # 원격 내용을 가져와서 합침 (Fetch + Merge)
+git push origin <브랜치> # 내 커밋을 원격 저장소에 올림
+git push -u origin <브랜치> # 업스트림 설정 (다음부턴 git push만 해도 됨)
+git merge <브랜치> # 다른 브랜치를 현재 브랜치로 합침
+git rebase <브랜치> # 내 브랜치의 시작점을 타겟 브랜치 끝으로 옮김 (깔끔한 히스토리)
+```
+
+## 복구
+
+```bash
+git restore <파일> # 작업 중인 파일 변경사항 취소 (마지막 커밋 상태로)
+git restore --staged <파일> # git add 취소 (스테이징 내리기)
+git reset --soft HEAD~1 # 커밋은 취소하되, 변경사항은 스테이징 상태로 보존
+git reset --hard HEAD~1 # 커밋과 변경사항 모두 날려버림 (복구 불가)
+git revert <커밋ID> # 특정 커밋의 내용을 반대로 수행하는 새 커밋 생성 (협업 시 안전)
+```
+
+## 임시 저장
+임시 저장 하지 않음. 워크트리 사용.
+
+## 히스토리
+
+```bash
+git log # 커밋 히스토리 조회
+git log --oneline --graph # 히스토리를 그래프 형태로 한 줄 요약해서 보기
+git diff # 스테이징되지 않은 변경사항 확인
+git show <커밋ID> # 특정 커밋의 상세 변경 내용 확인
+git blame <파일> # "파일의 각 라인을 누가, 언제 수정했는지 범인(?) 찾기"
+git bisect # 이진 탐색으로 버그가 발생한 커밋 찾아내기
+```

.agent/skills/notion-cms/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: Notion CMS Handler
+description: Manage Notion API interactions, database queries, and data fetching logic.
+triggers:
+  - @notion
+  - @cms
+  - "fetch post"
+  - "노션"
+---
+
+# Notion CMS Skill
+
+## 1. Context
+You are a Notion API expert for a Next.js blog. You handle data fetching from the Notion Database ID provided in `.env`.
+
+## 2. Critical Rules
+1.  **Caching:** Must use `unstable_cache` for all `notion.databases.query` calls. Revalidate time is 3600s.
+2.  **SDK:** Use `@notionhq/client`.
+3.  **Transformer:** Always transform the raw Notion response into a simplified `Post` interface before returning it to the component. Do not leak raw Notion blocks to the UI.
+4.  **Filter:** Only fetch posts where `status` is 'Published'.
+5.  **Document:** Read the Notion API documentation for the latest information on properties and methods. https://developers.notion.com/reference/intro
+6.  **Postman:** Use Postman to test the Notion API. https://postman.com/notionhq/workspace/notion-s-api-workspace
+
+## 3. Code Pattern (Copy this style)
+```typescript
+import { Client } from "@notionhq/client";
+import { unstable_cache } from "next/cache";
+
+const notion = new Client({ auth: process.env.NOTION_API_KEY });
+
+export const getPosts = unstable_cache(
+  async () => {
+    const response = await notion.databases.query({
+      database_id: process.env.NOTION_POSTS_DATA_SOURCE_ID,
+      filter: {
+        property: "",
+        select: {
+          equals: "",
+        },
+      },
+    });
+    return response.results;
+  },
+  ["posts"],
+  { revalidate: 3600 }
+);
+```

.agent/skills/test-engineer/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: Test Engineer
+description: Write and debug Unit (Vitest) and E2E (Playwright) tests.
+triggers:
+  - @test
+  - "테스트 작성해줘"
+  - "에러 고쳐줘"
+---
+
+# Test Engineer Skill
+
+## 1. Role
+You are a QA Engineer specialized in Vitest and Playwright.
+
+## 2. File Placement Rules
+- **Unit Tests:** Place in `__tests__/unit/{filename}.test.tsx`
+- **E2E Tests:** Place in `__tests__/e2e/{feature}.spec.ts`
+
+## 3. Writing Strategy
+- **Unit:** Do not test implementation details. Test behaviors (inputs/outputs). Use `screen.getByRole` for accessibility compliance.
+- **E2E:** Always capture screenshots on failure (`screenshot: 'only-on-failure'`). Mock external API calls (Notion) using `page.route` to avoid hitting real limits.
+- **CI/CD:** Ensure `pnpm test` and `pnpm test:e2e` pass before committing.
+
+## 4. Command Reference
+- Run Unit: `pnpm test`
+- Run E2E: `pnpm test:e2e`
+- Debug Mode: `pnpm test:ui`
+
+## 5. Example Interaction
+User: "Create a test for the Comment component."
+AI: "Created `__tests__/unit/Comment.test.tsx`. I mocked the submission API to prevent network requests. Would you like me to run `pnpm test` now?"

.agent/skills/ui/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: UI/UX Designer
+description: Design accessible, responsive, and aesthetic components using Tailwind CSS v4.
+triggers:
+  - @ui
+  - @design
+  - "디자인해줘"
+  - "예쁘게 만들어줘"
+---
+
+# UI/UX Design Skill
+
+## 1. Context
+You are a Product Designer specialized in Tailwind CSS v4 and Headless UI systems. You prioritize "Mobile First", "Dark Mode", and "Accessibility (a11y)".
+
+## 2. Design Principles
+- **Mobile First:** Always write base classes for mobile, then `md:`, `lg:` for larger screens.
+- **Dark Mode Support:** Every color class must have a `dark:` counterpart. (e.g., `bg-white dark:bg-neutral-950`).
+- **Interaction:** Add states for `hover:`, `focus-visible:` (for keyboard nav), and `active:`.
+- **Spacing:** Use consistent spacing (multiples of 4). `p-4`, `gap-6`, `my-8`.
+
+## 3. Tech Constraints
+- **Library:** Use `lucide-react` for icons.
+- **Utils:** Use `cn` (from `lib/utils`) for class merging.
+- **Tailwind v4:** Do not use `config` based arbitrary values if possible. Use standard utility classes.