@choblue/claude-code-toolkit 1.2.5 → 1.2.7

package/.claude/.project-map-cache

@@ -1 +1 @@
-e48648429d9686e998960a4fddaa11593ee785d5
+97eedbf98bcf7cd6a3c3c2e61afd04ae61af9b7c

package/.claude/CLAUDE.md

@@ -55,33 +55,89 @@ Step 4: 수정/삭제 → 확인
 
 ---
 
-## 3. 티어별 워크플로우
+## 2-1. 완료 기준 (Definition of Done)
+
+각 작업 단위는 다음 조건을 **모두 만족**해야 "완료"로 판단한다.
+에이전트는 구현 후 이 체크리스트를 자체 검증한다.
+
+### 공통 DoD
+- [ ] 타입 에러 없음 (`tsc --noEmit` 통과)
+- [ ] 미사용 import/변수 없음
+- [ ] 기존 테스트가 깨지지 않음
+- [ ] 기존 프로젝트 패턴과 일관성 유지
+
+> FE/BE별 추가 DoD는 프로젝트 루트 `CLAUDE.md`에서 오버라이드한다.
+
+---
+
+## 3. Task Header (의사결정 가시화)
+
+모든 티어에서 작업 시작 시 Task Header를 출력하여 의사결정을 가시화한다.
+
+### S 티어 헤더
+```
+📋 [작업명]
+⚡ S — [판단 근거 한 줄]
+📁 [대상 파일]
+```
+
+### M 티어 헤더
+```
+📋 [작업명]
+⚡ M — [판단 근거 한 줄]
+📚 [사용할 스킬 목록]
+🔄 [에이전트 흐름]
+📁 [예상 파일 수와 대상]
+```
+
+### L 티어 헤더
+```
+📋 [작업명]
+⚡ L — [판단 근거 한 줄]
+📚 [사용할 스킬 목록]
+🔄 [에이전트 흐름]
+📁 [예상 파일 수와 대상]
+📌 Plan:
+  ○ Step 1: [작업 단위]
+  ○ Step 2: [작업 단위]
+  ...
+```
+
+L 티어에서는 각 Step 진행에 따라 상태를 갱신한다:
+- `○` 대기 → `▶ ⏳` 진행 중 → `✔` 완료
+
+---
+
+## 4. 티어별 워크플로우
 
 ### S 티어 (trivial)
 Main Agent가 직접 처리한다. 서브에이전트 위임 불필요.
-1. 파일 읽기 → 직접 수정 → 완료
-2. 필요 시 `git-manager`로 커밋
+1. **Task Header 출력**
+2. 파일 읽기 → 직접 수정 → 완료
+3. 필요 시 `git-manager`로 커밋
 
 ### M 티어 (moderate)
 TDD/Review를 생략하고 핵심 단계만 수행한다.
-1. **Planning**: 요구사항 정리, 필요 시 `explore`로 탐색
-2. **Implementation**: `code-writer` 에이전트에 구현 위임 (단위별로 나눠 호출)
-3. **Commit**: `git-manager`로 커밋/PR 생성
+1. **Task Header 출력**
+2. **Planning**: 요구사항 정리, 필요 시 `explore`로 탐색
+3. **Implementation**: `code-writer` 에이전트에 구현 위임 (단위별로 나눠 호출)
+4. **Commit**: `git-manager`로 커밋/PR 생성
 
 ### L 티어 (complex)
 파일 기반 설계 후 **단위별로** 구현한다.
-1. **Research**: `explore`로 탐색 → `research.md` 작성 (관련 코드 분석, 제약 조건)
-2. **Plan**: `plan.md` 작성 (접근 방식, 변경 파일, 트레이드 오프, **단위별 작업 순서**)
-3. **주석 사이클**: 사용자가 plan.md에 메모 → 반영 → **승인 전까지 구현 금지**
-4. **Implementation + Test**: plan.md의 각 단위를 순서대로 `implementer`에 위임 (단위당 1회 호출)
-5. **Review**: `code-reviewer`로 리뷰 → `git-manager`로 커밋/PR
+1. **Task Header 출력**
+2. **Research**: `explore`로 탐색 → `research.md` 작성 (관련 코드 분석, 제약 조건)
+3. **Plan**: `plan.md` 작성 (접근 방식, 변경 파일, 트레이드 오프, **단위별 작업 순서**)
+4. **주석 사이클**: 사용자가 plan.md에 메모 → 반영 → **승인 전까지 구현 금지**
+5. **Implementation + Test**: plan.md의 각 단위를 순서대로 `implementer`에 위임 (단위당 1회 호출)
+6. **Review**: `code-reviewer`로 리뷰 → `git-manager`로 커밋/PR
 
 ### 풀스택 작업 (FE + BE 동시 변경)
 티어는 영향도 기준으로 판단하되, 위임 순서는 BE 선행 → FE 후행을 따른다.
 
 ---
 
-## 4. 문서 참조 가이드
+## 5. 문서 참조 가이드
 
 ### Agents (서브에이전트 프롬프트)
 - `.claude/agents/explore.md` - 코드베이스 탐색 전문가
@@ -93,9 +149,8 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 - `.claude/agents/git-manager.md` - Git 작업 전문가
 
 ### Skills (도메인 지식)
-- `.claude/skills/Coding/` - 코딩 원칙 및 패턴
-  - `SKILL.md` - 공통 원칙
-  - `backend.md` - NestJS 백엔드 규칙
+- `.claude/skills/Coding/SKILL.md` - 공통 코딩 원칙
+- `.claude/skills/NestJS/SKILL.md` - NestJS 백엔드 규칙 (레이어, DTO, DI, 에러 핸들링)
 - `.claude/skills/React/SKILL.md` - React 컴포넌트, 훅, 상태 관리
 - `.claude/skills/NextJS/SKILL.md` - Next.js App Router, SSR, Server Actions
 - `.claude/skills/TailwindCSS/SKILL.md` - Tailwind CSS 유틸리티 패턴
@@ -106,11 +161,18 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 - `.claude/skills/TypeORM/SKILL.md` - TypeORM Entity, Repository, QueryBuilder
 - `.claude/skills/TDD/` - TDD 테스트 원칙 및 패턴
   - `SKILL.md` - 공통 TDD 원칙
-  - `frontend.md` - React 테스트 규칙
-  - `backend.md` - NestJS 테스트 규칙
+  - `references/frontend.md` - React 테스트 규칙
+  - `references/backend.md` - NestJS 테스트 규칙
 - `.claude/skills/DDD/SKILL.md` - DDD 전술적 패턴 (Entity, VO, Aggregate, Repository, Domain Event)
 - `.claude/skills/Planning/SKILL.md` - 작업 계획 (티어 판단, 작업 분해, 의존성 확인)
 - `.claude/skills/Git/SKILL.md` - Git 커밋/PR/브랜치 규칙
+- `.claude/skills/FailureRecovery/SKILL.md` - 실패 복구 프로토콜 (진단, 처방, 에스컬레이션)
+- `.claude/skills/Curation/SKILL.md` - AI 결과물 큐레이션 체크리스트
+
+### Prompts (커스텀 커맨드)
+- `.claude/prompts/feature.md` - /feature [기능명] -> 새 기능 구현 시작
+- `.claude/prompts/fix.md` - /fix [증상] -> 버그 수정
+- `.claude/prompts/review.md` - /review -> 현재 변경사항 리뷰
 
 ### Scripts
 - `.claude/scripts/generate-project-map.sh` - PROJECT_MAP.md 자동 생성
@@ -121,7 +183,7 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 
 ---
 
-## 5. 프로젝트별 오버라이드
+## 6. 프로젝트별 오버라이드
 
 프로젝트 루트에 `CLAUDE.md`가 있으면 이 글로벌 규칙보다 우선한다.
 프로젝트별 규칙은 글로벌 규칙을 확장하되, 충돌 시 프로젝트 규칙을 따른다.

package/.claude/hooks/prompt-hook.sh

@@ -12,10 +12,10 @@ INPUT=$(cat)
 
 # ─── 1. Quality Gate ───
 cat << 'EOF'
-[Quality Gate] 티어를 판단하고 워크플로우를 따르라.
-- S (1-2파일, 단순수정): Main Agent 직접 처리
-- M (3-5파일, 명확한 기능): code-writer → git-manager
-- L (6+파일, 설계 필요): 풀 프로세스 (TDD → 구현 → 리뷰)
+[Quality Gate] 티어를 판단하고 Task Header를 출력한 후 워크플로우를 따르라.
+- S: 📋 ⚡ 📁
+- M: 📋 ⚡ 📚 🔄 📁
+- L: 📋 ⚡ 📚 🔄 📁 📌Plan
 EOF
 
 # ─── 2. Skill Detector ───

package/.claude/prompts/feature.md

@@ -0,0 +1,11 @@
+새 기능 구현을 시작한다.
+
+## 입력
+- 기능명: $ARGUMENTS
+- 관련 도메인: (사용자가 지정)
+
+## 절차
+1. 티어를 판단하라
+2. PROJECT_MAP.md를 읽어라
+3. 티어별 워크플로우를 따라라
+4. 구현 후 DoD 체크리스트를 검증하라

package/.claude/prompts/fix.md

@@ -0,0 +1,11 @@
+버그를 수정한다.
+
+## 입력
+- 증상: $ARGUMENTS
+
+## 절차
+1. 에러 메시지/증상을 분석하라
+2. 관련 코드를 explore로 탐색하라
+3. 원인을 파악하고 수정 범위를 결정하라
+4. 수정 후 관련 테스트가 통과하는지 확인하라
+5. 같은 유형의 버그가 다른 곳에도 있는지 검색하라

package/.claude/prompts/review.md

@@ -0,0 +1,7 @@
+현재 변경사항을 리뷰한다.
+
+## 절차
+1. `git diff`로 변경 내용을 확인하라
+2. Curation 스킬의 체크리스트를 적용하라
+3. 코드 품질 체크리스트 (Coding SKILL.md)를 적용하라
+4. 발견사항을 심각도별로 분류하라: 필수 수정 / 권장 / 제안

package/.claude/skills/Coding/SKILL.md

@@ -6,9 +6,9 @@ description: 공통 코딩 원칙과 패턴. 코드 작성 시 항상 참조하
 # Coding Skill - 공통 원칙
 
 이 문서는 모든 코드 작성 시 적용되는 공통 원칙을 정의한다.
-FE/BE별 상세 규칙은 각각의 파일을 참고한다.
-- `frontend.md` - React 프론트엔드 규칙
-- `backend.md` - NestJS 백엔드 규칙
+FE/BE 상세 규칙은 기술별 스킬에서 다룬다.
+- BE: `../NestJS/SKILL.md`, `../TypeORM/SKILL.md`
+- FE: `../React/SKILL.md`, `../NextJS/SKILL.md`, `../TailwindCSS/SKILL.md` 등
 
 ---
 
@@ -208,4 +208,5 @@ try {
 - [ ] 시스템 경계에서 에러 핸들링이 되어 있는가?
 - [ ] 불필요한 복잡도가 없는가?
 - [ ] `any` 타입을 사용하지 않았는가?
-- [ ] 기존 프로젝트 패턴과 일관성이 있는가?
+- [ ] 기존 프로젝트 패턴과 일관성이 있는가?
+

package/.claude/skills/Curation/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: curation
+description: AI 결과물의 품질을 인간 관점에서 검증하는 체크리스트. code-reviewer 에이전트가 참조하거나, 사용자가 직접 리뷰할 때 활용한다.
+---
+
+# Curation Skill
+
+AI가 만든 80점짜리 결과물에서 나머지 20점을 채우기 위한 인간 리뷰 관점.
+
+---
+
+## 1. 코드 큐레이션 체크리스트
+
+### 자연스러움 (AI스러움 제거)
+- [ ] 불필요하게 과한 주석이 없는가 (모든 줄에 주석 금지)
+- [ ] 변수명이 지나치게 장황하지 않은가
+- [ ] 사용하지 않는 예외 처리가 없는가 (방어적 코딩 과잉)
+- [ ] 기존 코드베이스의 톤과 맞는가
+
+### 실용성
+- [ ] 실제로 사용될 엣지 케이스만 처리하는가 (과잉 방어 금지)
+- [ ] 추상화 수준이 적절한가 (너무 이르거나 과한 추상화 금지)
+- [ ] import가 실제로 존재하는 모듈을 참조하는가
+- [ ] 하드코딩된 값이 없는가 (환경변수, 상수로 분리)
+
+### 일관성
+- [ ] 기존 파일들과 디렉토리 위치가 맞는가
+- [ ] 네이밍 패턴이 주변 코드와 통일되는가
+- [ ] 에러 핸들링 방식이 프로젝트 관례와 맞는가
+
+## 2. 리뷰 우선순위
+
+1. **먼저 빌드/테스트 통과** 확인 (자동화 가능)
+2. **비즈니스 로직 정확성** -- 요구사항과 일치하는지
+3. **기존 패턴 일관성** -- 프로젝트 컨벤션을 따르는지
+4. **AI스러움 제거** -- 과잉 주석, 과잉 방어, 불필요한 추상화

package/.claude/skills/FailureRecovery/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: failure-recovery
+description: 에이전트가 잘못된 결과를 냈을 때의 디버깅 및 재시도 프로토콜. 단순 재실행이 아닌 원인 분석 후 처방한다.
+---
+
+# Failure Recovery Skill
+
+에이전트 결과물이 기대와 다를 때, "다시 해"가 아닌 **원인 진단 -> 처방 -> 재시도** 사이클을 따른다.
+
+---
+
+## 1. 실패 분류 및 처방
+
+| 유형 | 증상 | 처방 |
+|------|------|------|
+| **방향 오류** | 요구사항과 전혀 다른 결과 | 요구사항을 재정의하고 배경 컨텍스트 보강 |
+| **패턴 불일치** | 동작은 하지만 기존 코드와 스타일이 다름 | 참조할 기존 파일 경로를 명시적으로 전달 |
+| **부분 구현** | 일부만 되고 나머지가 빠짐 | 작업을 더 작은 단위로 재분해 |
+| **타입/런타임 에러** | 빌드 실패, 런타임 크래시 | 에러 메시지 + 관련 타입/인터페이스를 함께 전달 |
+| **반복 실패** | 같은 에러를 2회 이상 반복 | 접근 방식 자체를 변경하거나 사용자에게 에스컬레이션 |
+
+## 2. 재시도 프로토콜
+
+### Step 1: 진단 (바로 "다시 해" 금지)
+```
+실패 진단:
+- 기대한 결과: [구체적으로]
+- 실제 결과: [구체적으로]
+- 차이 원인: 방향 오류 / 패턴 불일치 / 부분 구현 / 에러
+```
+
+### Step 2: 처방
+- 방향 오류 -> 요구사항 문서를 수정하고 재전달
+- 패턴 불일치 -> "X파일의 패턴을 따라서" 참조 경로 추가
+- 부분 구현 -> 빠진 부분만 별도 작업으로 분리
+- 에러 -> 에러 메시지 + 관련 타입/인터페이스를 함께 전달
+
+### Step 3: 재시도
+- 처방 내용을 프롬프트에 반영하여 재호출
+- 동일 실패 2회 반복 시 -> 접근 방식 자체를 변경하거나 사용자에게 에스컬레이션
+
+## 3. 에스컬레이션 기준
+
+다음 중 하나라도 해당하면 사용자에게 판단을 요청한다:
+- 동일 유형 실패가 2회 반복
+- 처방 후에도 새로운 유형의 에러 발생
+- 아키텍처/설계 수준의 변경이 필요한 경우

package/.claude/skills/{Coding/backend.md → NestJS/SKILL.md}

@@ -1,7 +1,12 @@
-# Coding Skill - Backend (NestJS)
+---
+name: nestjs
+description: NestJS 백엔드 개발 가이드. 레이어별 책임, DTO, 에러 핸들링, DI, 네이밍 컨벤션 등 NestJS 코드 작성 시 참조한다.
+---
+
+# NestJS Skill - 백엔드 핵심 규칙
 
 NestJS 백엔드 코드에 적용되는 규칙이다.
-공통 원칙은 `SKILL.md`를 함께 참고한다.
+공통 코딩 원칙은 `../Coding/SKILL.md`를 함께 참고한다.
 
 ---
 

package/.claude/skills/NextJS/SKILL.md

@@ -98,307 +98,7 @@ export function UserTabs() {
 
 ---
 
-## 3. 데이터 페칭
-
-### Server Component에서 직접 fetch
-- Server Component에서 `async/await`로 직접 데이터를 가져온다
-- `useEffect`로 데이터를 가져오지 않는다
-
-```typescript
-// Good - Server Component에서 직접 페칭
-export default async function UserPage({ params }: { params: { id: string } }) {
-  const user = await getUser(params.id);
-  return <UserProfile user={user} />;
-}
-```
-
-### Revalidation 전략
-- **Time-based**: `next: { revalidate: 60 }` - 일정 시간마다 갱신
-- **On-demand**: `revalidateTag()`, `revalidatePath()` - 특정 이벤트 시 갱신
-
-```typescript
-// Time-based revalidation
-const data = await fetch('https://api.example.com/users', {
-  next: { revalidate: 3600 }, // 1시간마다 갱신
-});
-
-// Tag-based revalidation
-const data = await fetch('https://api.example.com/users', {
-  next: { tags: ['users'] },
-});
-
-// Server Action에서 revalidation 트리거
-'use server';
-import { revalidateTag } from 'next/cache';
-
-export async function createUser(formData: FormData) {
-  await saveUser(formData);
-  revalidateTag('users');
-}
-```
-
----
-
-## 4. Route Handlers
-
-### 위치 및 구조
-- `app/api/` 디렉토리 하위에 `route.ts` 파일로 정의한다
-- HTTP 메서드를 named export로 정의한다
-
-```typescript
-// app/api/users/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-
-export async function GET(request: NextRequest) {
-  const users = await getUsers();
-  return NextResponse.json(users);
-}
-
-export async function POST(request: NextRequest) {
-  const body = await request.json();
-  const user = await createUser(body);
-  return NextResponse.json(user, { status: 201 });
-}
-```
-
-### 동적 라우트
-```typescript
-// app/api/users/[id]/route.ts
-export async function GET(
-  request: NextRequest,
-  { params }: { params: { id: string } },
-) {
-  const user = await getUser(params.id);
-  if (!user) {
-    return NextResponse.json({ error: 'Not Found' }, { status: 404 });
-  }
-  return NextResponse.json(user);
-}
-
-export async function PUT(
-  request: NextRequest,
-  { params }: { params: { id: string } },
-) {
-  const body = await request.json();
-  const user = await updateUser(params.id, body);
-  return NextResponse.json(user);
-}
-
-export async function DELETE(
-  request: NextRequest,
-  { params }: { params: { id: string } },
-) {
-  await deleteUser(params.id);
-  return new NextResponse(null, { status: 204 });
-}
-```
-
----
-
-## 5. Middleware
-
-### 용도
-- 인증/인가 체크
-- 리다이렉트 처리
-- 요청/응답 헤더 수정
-- 국제화(i18n) 라우팅
-
-### 작성 패턴
-```typescript
-// middleware.ts (프로젝트 루트)
-import { NextResponse } from 'next/server';
-import type { NextRequest } from 'next/server';
-
-export function middleware(request: NextRequest) {
-  const token = request.cookies.get('token')?.value;
-
-  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
-    return NextResponse.redirect(new URL('/login', request.url));
-  }
-
-  return NextResponse.next();
-}
-
-export const config = {
-  matcher: ['/dashboard/:path*', '/admin/:path*'],
-};
-```
-
----
-
-## 6. Metadata
-
-### 정적 Metadata
-```typescript
-// app/about/page.tsx
-import type { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: '소개 - 서비스명',
-  description: '서비스 소개 페이지입니다.',
-};
-```
-
-### 동적 Metadata
-```typescript
-// app/users/[id]/page.tsx
-import type { Metadata } from 'next';
-
-export async function generateMetadata({
-  params,
-}: {
-  params: { id: string };
-}): Promise<Metadata> {
-  const user = await getUser(params.id);
-
-  return {
-    title: `${user.name} - 프로필`,
-    description: `${user.name}의 프로필 페이지입니다.`,
-  };
-}
-```
-
----
-
-## 7. Server Actions
-
-### 정의 및 사용
-- `'use server'` 지시문으로 서버 액션을 정의한다
-- form의 `action` 속성이나 이벤트 핸들러에서 호출한다
-
-```typescript
-// actions/user.ts
-'use server';
-
-import { revalidatePath } from 'next/cache';
-
-export async function createUser(formData: FormData) {
-  const name = formData.get('name') as string;
-  const email = formData.get('email') as string;
-
-  await db.user.create({ data: { name, email } });
-  revalidatePath('/users');
-}
-
-export async function deleteUser(userId: string) {
-  await db.user.delete({ where: { id: userId } });
-  revalidatePath('/users');
-}
-```
-
-### Form에서 사용
-```typescript
-// components/CreateUserForm.tsx
-import { createUser } from '@/actions/user';
-
-export function CreateUserForm() {
-  return (
-    <form action={createUser}>
-      <input name="name" type="text" required />
-      <input name="email" type="email" required />
-      <button type="submit">생성</button>
-    </form>
-  );
-}
-```
-
----
-
-## 8. 디렉토리 구조 패턴
-
-### Route Groups - `(group)`
-- URL에 영향을 주지 않고 라우트를 그룹화한다
-
-```
-app/
-  (marketing)/
-    about/page.tsx      # /about
-    blog/page.tsx       # /blog
-  (dashboard)/
-    layout.tsx          # dashboard 전용 레이아웃
-    settings/page.tsx   # /settings
-    profile/page.tsx    # /profile
-```
-
-### Private Folders - `_folder`
-- 라우팅에서 제외되는 내부 폴더
-
-```
-app/
-  _components/          # 라우팅에 포함되지 않음
-    Header.tsx
-    Footer.tsx
-  _lib/                 # 내부 유틸리티
-    utils.ts
-```
-
-### Parallel Routes - `@slot`
-- 동일 레이아웃에서 여러 페이지를 동시에 렌더링한다
-
-```
-app/
-  layout.tsx            # children + @analytics + @team 동시 렌더링
-  @analytics/
-    page.tsx
-  @team/
-    page.tsx
-```
-
-### Intercepting Routes - `(.)`, `(..)`, `(...)`
-- 현재 레이아웃 내에서 다른 라우트를 가로채서 표시한다
-
-```
-app/
-  feed/
-    page.tsx
-    (..)photo/[id]/     # /photo/:id를 모달로 가로챔
-      page.tsx
-  photo/[id]/
-    page.tsx            # 직접 접근 시 전체 페이지
-```
-
----
-
-## 9. Image/Font 최적화
-
-### next/image
-- 모든 이미지는 `next/image`를 사용한다
-- `width`, `height`를 명시하거나 `fill` 속성을 사용한다
-
-```typescript
-import Image from 'next/image';
-
-// 크기 지정
-<Image src="/hero.png" alt="히어로 이미지" width={800} height={400} />
-
-// fill 모드 (부모 기준 채움)
-<div className="relative h-64 w-full">
-  <Image src="/banner.png" alt="배너" fill className="object-cover" />
-</div>
-```
-
-### next/font
-- Google Fonts는 `next/font/google`을 사용한다
-- 커스텀 폰트는 `next/font/local`을 사용한다
-
-```typescript
-// app/layout.tsx
-import { Inter } from 'next/font/google';
-
-const inter = Inter({ subsets: ['latin'] });
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="ko" className={inter.className}>
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-
----
-
-## 10. 네이밍 컨벤션
+## 3. 네이밍 컨벤션
 
 | 대상 | 규칙 | 예시 |
 |------|------|------|
@@ -416,7 +116,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 ---
 
-## 11. 금지 사항
+## 4. 금지 사항
 
 - Client Component에서 무거운 데이터 페칭 로직 작성 금지
 - 불필요한 `'use client'` 선언 금지 - 서버에서 가능하면 서버에서 처리
@@ -426,4 +126,14 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 - `<img>` 태그 직접 사용 금지 - `next/image` 사용
 - 외부 폰트를 `<link>` 태그로 로드 금지 - `next/font` 사용
 - `router.push()`를 Server Component에서 사용 금지 - `redirect()` 사용
-- API Route에서 비즈니스 로직 직접 구현 금지 - 별도 서비스 레이어로 분리
+- API Route에서 비즈니스 로직 직접 구현 금지 - 별도 서비스 레이어로 분리
+
+---
+
+## 심화 참조
+
+| 파일 | 내용 |
+|------|------|
+| `references/data-fetching.md` | 데이터 페칭 (Server Component fetch, Revalidation) + Route Handlers (CRUD, 동적 라우트) |
+| `references/middleware-actions.md` | Middleware (인증, 리다이렉트, matcher) + Server Actions (form action, revalidation) |
+| `references/optimization.md` | Metadata (정적/동적) + 디렉토리 구조 패턴 (Route Groups, Parallel/Intercepting Routes) + Image/Font 최적화 |