create-claude-pipeline 0.1.0

package/template/.claude/skills/api-integration/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: api-integration
+description: "FE 개발자가 BE API를 연동할 때 일관된 패턴을 유지하기 위해 참조하는 skill. 커스텀 훅 작성, 에러 핸들링, 타입 정의 방법을 제공한다. API 연동 코드를 작성하거나, 새 API 엔드포인트를 프론트엔드에 붙이거나, 에러 핸들링 로직을 구현할 때 반드시 사용한다. 'API 연동', 'API 호출', '에러 처리', 'useQuery', 'useMutation', 'fetch 함수 작성' 등의 상황에서 트리거된다."
+---
+
+# API Integration
+
+FE 개발자가 BE API를 연동할 때 따르는 패턴이다.
+
+API 연동은 "타입 → API 함수 → 커스텀 훅 → 에러 핸들링" 순서로 진행한다. 이 순서가 중요한 이유는, 타입을 먼저 정의해야 API 함수와 훅에서 타입 안전성을 확보할 수 있고, 에러 핸들링을 마지막에 일괄 적용해야 누락 없이 모든 API 호출을 커버할 수 있기 때문이다.
+
+---
+
+## STEP 1: 타입 정의
+
+API 명세(`context/03_api_spec.md`)를 읽고 각 엔드포인트의 타입을 정의한다.
+
+모든 API 호출에는 3종류의 타입이 필요하다:
+
+```tsx
+// types/[feature].ts
+
+// Request — API에 보내는 데이터
+export interface CreateOrderRequest {
+  productId: string;
+  quantity: number;
+  shippingAddress: string;
+}
+
+// Response — API에서 받는 데이터
+export interface Order {
+  id: string;
+  productId: string;
+  quantity: number;
+  status: "pending" | "confirmed" | "shipped" | "delivered";
+  totalPrice: number;
+  createdAt: string;
+}
+
+// Error — API 에러 응답 구조
+export interface ApiError {
+  statusCode: number;
+  message: string;
+  code?: string; // 비즈니스 에러 코드 (예: "INSUFFICIENT_STOCK")
+}
+```
+
+**판단 기준:**
+- GET 요청은 query params 타입 + Response 타입
+- POST/PUT 요청은 Request body 타입 + Response 타입
+- 공통 에러 타입은 프로젝트에 하나만 정의하고 재사용한다
+
+기존 프로젝트에 이미 `ApiError` 타입이 있으면 그것을 사용한다.
+
+---
+
+## STEP 2: API 함수 작성
+
+`lib/api/` 또는 `services/` 디렉토리에 API 함수를 작성한다. 기존 프로젝트의 디렉토리 구조를 따른다.
+
+```tsx
+// lib/api/orders.ts
+import { apiClient } from "./client";
+import type { CreateOrderRequest, Order } from "@/types/order";
+
+// GET — 목록 조회
+export async function fetchOrders(): Promise<Order[]> {
+  const { data } = await apiClient.get<Order[]>("/orders");
+  return data;
+}
+
+// GET — 단건 조회
+export async function fetchOrder(id: string): Promise<Order> {
+  const { data } = await apiClient.get<Order>(`/orders/${id}`);
+  return data;
+}
+
+// POST — 생성
+export async function createOrder(input: CreateOrderRequest): Promise<Order> {
+  const { data } = await apiClient.post<Order>("/orders", input);
+  return data;
+}
+
+// PUT — 수정
+export async function updateOrder(id: string, input: Partial<CreateOrderRequest>): Promise<Order> {
+  const { data } = await apiClient.put<Order>(`/orders/${id}`, input);
+  return data;
+}
+
+// DELETE — 삭제
+export async function deleteOrder(id: string): Promise<void> {
+  await apiClient.delete(`/orders/${id}`);
+}
+```
+
+**핵심 원칙:**
+- 성공 응답에 반드시 타입을 지정한다 (`apiClient.get<Order[]>`)
+- 에러는 throw해서 상위(훅)로 전달한다 — API 함수에서 try/catch하지 않는다
+- URL path에 변수가 들어가면 template literal을 사용한다
+
+---
+
+## STEP 3: 커스텀 훅으로 감싸기
+
+컴포넌트에서 API 함수를 직접 호출하지 않는다. 반드시 커스텀 훅으로 감싼다.
+
+프로젝트에 사용 중인 데이터 fetching 라이브러리에 따라 패턴이 달라진다. 기존 프로젝트를 확인하고 해당 패턴을 사용한다.
+
+### React Query (TanStack Query) 사용 시
+
+```tsx
+// hooks/useOrders.ts
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { fetchOrders, fetchOrder, createOrder, deleteOrder } from "@/lib/api/orders";
+import type { CreateOrderRequest } from "@/types/order";
+
+// GET → useQuery
+export function useOrders() {
+  return useQuery({
+    queryKey: ["orders"],
+    queryFn: fetchOrders,
+  });
+}
+
+export function useOrder(id: string) {
+  return useQuery({
+    queryKey: ["orders", id],
+    queryFn: () => fetchOrder(id),
+    enabled: !!id, // id가 없으면 요청하지 않음
+  });
+}
+
+// POST/PUT/DELETE → useMutation
+export function useCreateOrder() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (input: CreateOrderRequest) => createOrder(input),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["orders"] });
+    },
+  });
+}
+
+export function useDeleteOrder() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (id: string) => deleteOrder(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["orders"] });
+    },
+  });
+}
+```
+
+### SWR 사용 시
+
+```tsx
+// hooks/useOrders.ts
+import useSWR from "swr";
+import useSWRMutation from "swr/mutation";
+import { fetchOrders, createOrder } from "@/lib/api/orders";
+import type { CreateOrderRequest } from "@/types/order";
+
+// GET → useSWR
+export function useOrders() {
+  return useSWR("orders", fetchOrders);
+}
+
+// POST/PUT/DELETE → useSWRMutation
+export function useCreateOrder() {
+  return useSWRMutation(
+    "orders",
+    (_key: string, { arg }: { arg: CreateOrderRequest }) => createOrder(arg)
+  );
+}
+```
+
+### 라이브러리 없이 직접 구현 시
+
+```tsx
+// hooks/useOrders.ts
+import { useState, useEffect } from "react";
+import { fetchOrders } from "@/lib/api/orders";
+import type { Order } from "@/types/order";
+
+export function useOrders() {
+  const [data, setData] = useState<Order[] | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    fetchOrders()
+      .then(setData)
+      .catch(setError)
+      .finally(() => setIsLoading(false));
+  }, []);
+
+  return { data, isLoading, error };
+}
+```
+
+**반환값 규칙:**
+
+모든 커스텀 훅은 컴포넌트가 필요한 3가지를 반환한다:
+- `data` — 응답 데이터 (로딩 중이면 `undefined` 또는 `null`)
+- `isLoading` — 로딩 중 여부
+- `isError` 또는 `error` — 에러 발생 여부
+
+이 3가지가 있어야 컴포넌트에서 Loading/Error/Empty/Success 4상태를 처리할 수 있다.
+
+---
+
+## STEP 4: 에러 핸들링
+
+에러 핸들링은 두 레이어로 구성한다: **글로벌 인터셉터** (공통 에러)와 **컴포넌트 레벨** (개별 에러).
+
+### 글로벌 인터셉터
+
+HTTP 상태 코드별 공통 처리를 API 클라이언트에 설정한다. 모든 API 호출에 자동 적용되므로 개별 컴포넌트에서 반복하지 않아도 된다.
+
+```tsx
+// lib/api/client.ts
+import axios from "axios";
+
+export const apiClient = axios.create({
+  baseURL: process.env.NEXT_PUBLIC_API_URL || "/api",
+  timeout: 10000,
+});
+
+apiClient.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    const status = error.response?.status;
+
+    // 401 Unauthorized → 로그인 페이지로 리다이렉트
+    if (status === 401) {
+      window.location.href = "/login";
+      return Promise.reject(error);
+    }
+
+    // 403 Forbidden → 권한 없음 알림
+    // toast는 기존 프로젝트의 토스트 라이브러리를 사용한다
+    // (react-hot-toast, sonner, react-toastify 등)
+    if (status === 403) {
+      toast.error("접근 권한이 없습니다.");
+      return Promise.reject(error);
+    }
+
+    // 네트워크 오류 (서버 응답 자체가 없는 경우)
+    if (!error.response) {
+      toast.error("네트워크 연결을 확인해주세요.");
+      return Promise.reject(error);
+    }
+
+    // 그 외 에러는 상위로 전달 (컴포넌트에서 처리)
+    return Promise.reject(error);
+  }
+);
+```
+
+### 에러 핸들링 기준표
+
+| 상태 코드 | 처리 방식 | 처리 위치 |
+|-----------|-----------|-----------|
+| 401 Unauthorized | 로그인 페이지로 리다이렉트 | 글로벌 인터셉터 |
+| 403 Forbidden | 권한 없음 토스트 | 글로벌 인터셉터 |
+| 404 Not Found | 빈 상태 UI 표시 | 컴포넌트 |
+| 422 Validation Error | 폼 필드별 에러 메시지 | 컴포넌트 |
+| 500 Internal Server Error | 에러 상태 UI + 재시도 버튼 | 컴포넌트 |
+| 네트워크 오류 | 연결 확인 토스트 | 글로벌 인터셉터 |
+
+### 컴포넌트 레벨 에러 처리
+
+글로벌 인터셉터가 처리하지 않는 에러(404, 422, 500)는 컴포넌트에서 처리한다.
+
+```tsx
+// 404 — 빈 상태 UI
+export function OrderDetail({ orderId }: { orderId: string }) {
+  const { data, isLoading, error } = useOrder(orderId);
+
+  if (isLoading) return <OrderDetailSkeleton />;
+
+  if (error?.response?.status === 404) {
+    return <EmptyState message="주문을 찾을 수 없습니다." />;
+  }
+
+  if (error) {
+    return (
+      <ErrorMessage
+        message="주문 정보를 불러올 수 없습니다."
+        onRetry={() => window.location.reload()}
+      />
+    );
+  }
+
+  return <OrderInfo order={data} />;
+}
+```
+
+```tsx
+// 422 — 폼 유효성 에러
+export function CreateOrderForm() {
+  const { mutate, isPending, error } = useCreateOrder();
+
+  const fieldErrors = error?.response?.status === 422
+    ? error.response.data.errors
+    : {};
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); mutate(formData); }}>
+      <Input
+        name="quantity"
+        error={fieldErrors?.quantity}
+      />
+      <Button type="submit" loading={isPending}>주문하기</Button>
+    </form>
+  );
+}
+```
+
+```tsx
+// 500 — 에러 UI + 재시도
+// useQuery의 refetch 또는 직접 재호출로 재시도한다
+export function OrderList() {
+  const { data, isLoading, error, refetch } = useOrders();
+
+  if (error) {
+    return (
+      <ErrorMessage
+        message="서버 오류가 발생했습니다. 잠시 후 다시 시도해주세요."
+        onRetry={refetch}
+      />
+    );
+  }
+
+  // ...
+}
+```
+
+---
+
+## 구현 순서 체크리스트
+
+API 연동 시 아래 순서로 진행한다:
+
+1. [ ] `context/03_api_spec.md`에서 연동할 엔드포인트 확인
+2. [ ] `types/`에 Request / Response / Error 타입 정의
+3. [ ] `lib/api/`에 API 함수 작성 (타입 지정, 에러는 throw)
+4. [ ] `hooks/`에 커스텀 훅 작성 (useQuery / useMutation)
+5. [ ] 글로벌 에러 인터셉터 확인 (이미 있으면 스킵)
+6. [ ] 컴포넌트에서 훅 호출 + 4상태 처리 (Loading/Error/Empty/Success)
+7. [ ] 에러 시나리오별 UI 동작 확인 (401/403/404/500/네트워크)

package/template/.claude/skills/assemble-context/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: assemble-context
+description: "PM이 PHASE 3 진입 시 각 Agent에게 작업을 넘기기 전에 context/ 폴더의 산출물들(00_requirements.md, 01_plan.md, 02_design_spec.md, 03_api_spec.md 등)을 읽어서 Agent별 task 파일(04_task_*.md)을 조립할 때 사용하는 skill. 'task context 조립', '04_task 파일 생성', 'Agent에게 작업 넘기기', 'Phase 3 시작' 등의 상황에서 반드시 사용한다. QA Phase(Phase 4)에서 04_task_QA.md를 생성할 때도 이 skill을 사용한다."
+---
+
+# Assemble Context
+
+PM Agent가 Phase 0~2 산출물을 조합하여 각 실행 Agent에게 전달할 `04_task_*.md` 파일을 조립하는 skill이다.
+
+핵심 원칙은 **자족성(self-contained)**이다. 각 Agent는 자신의 task 파일 하나만 읽으면 작업에 필요한 모든 정보가 담겨 있어야 한다. 외부 파일을 추가로 참조할 필요가 없어야 한다.
+
+---
+
+## 조립 절차
+
+### Step 1: 소스 파일 읽기
+
+`context/` 폴더에서 아래 파일들을 읽는다. 파일이 없으면 해당 섹션은 건너뛴다.
+
+| 파일 | 용도 | 필수 여부 |
+|------|------|-----------|
+| `context/00_requirements.md` | Section 1(프로젝트 현황), Section 2(요구사항) | **필수** |
+| `context/01_plan.md` | Section 3(기획안 요약) | 있으면 포함 |
+| `context/02_design_spec.md` | Section 5 참고 자료 (FE, QA용) | 있으면 포함 |
+| `context/03_api_spec.md` | Section 5 참고 자료 (BE, FE, QA용) | 있으면 포함 |
+| `context/03_erd.md` | Section 5 참고 자료 (BE, Infra용) | 있으면 포함 |
+
+`00_requirements.md`가 없으면 조립을 중단하고 사용자에게 "Phase 0이 아직 완료되지 않았습니다"라고 알린다.
+
+### Step 2: 대상 Agent 확인
+
+호출 시 전달받은 Agent 목록을 확인한다. 일반적으로 `00_requirements.md`의 "필요 Agent" 섹션에 명시되어 있다.
+
+가능한 Agent 유형:
+- **FE** — 프론트엔드 개발
+- **BE** — 백엔드 개발
+- **INFRA** — 인프라/DevOps
+- **QA** — QA/테스트 (Phase 4에서 생성할 수도 있음)
+
+### Step 3: 공통 섹션 조립 (Section 1~3)
+
+모든 Agent에게 동일하게 들어가는 내용을 먼저 구성한다.
+
+```markdown
+# TASK CONTEXT
+
+## 1. 프로젝트 현황
+```
+
+`00_requirements.md`에서 서비스명, 기술 스택, 현재 서비스 상태 정보를 추출하여 작성한다. 코드베이스 탐색 결과가 있다면 그것도 반영한다.
+
+```markdown
+## 2. 이번 요구사항
+```
+
+`00_requirements.md`의 요청 내용과 분석 결과(작업 유형, 영향 범위)를 그대로 포함한다.
+
+```markdown
+## 3. 기획안 요약
+```
+
+`01_plan.md`의 핵심 내용을 요약하여 포함한다. 기능 명세, 화면 목록, API 목록, 엣지케이스 등을 포함한다. `01_plan.md`가 없으면 이 섹션은 "(기획안 없음 — 요구사항 기반으로 작업)" 으로 표기한다.
+
+### Step 4: Agent별 섹션 조립 (Section 4~5)
+
+각 Agent의 역할에 맞게 작업 지시와 참고 자료를 작성한다.
+
+#### Section 4: 네 역할과 작업 지시
+
+Agent마다 아래 항목을 구체적으로 작성한다:
+
+| 항목 | 설명 |
+|------|------|
+| **역할** | 이 Agent가 맡은 역할 (예: 프론트엔드 개발자) |
+| **해야 할 일** | 구체적인 작업 목록 (체크리스트 형태 권장) |
+| **산출물 형식** | 무엇을 만들어야 하는지 (파일, 컴포넌트, API 등) |
+| **완료 기준** | 이 작업이 "끝났다"의 기준 |
+| **건드리면 안 되는 것** | 이 Agent의 관할 밖인 것을 명시 |
+
+**Agent별 작성 가이드:**
+
+**FE Agent** — `02_design_spec.md`의 화면 시안과 컴포넌트 구조를 기반으로 해야 할 일을 도출한다. API 명세에서 FE가 호출해야 할 엔드포인트 목록도 포함한다.
+
+**BE Agent** — `03_api_spec.md`의 API 명세와 `03_erd.md`의 DB 스키마를 기반으로 해야 할 일을 도출한다. 각 엔드포인트의 요청/응답 형식, 비즈니스 로직, 에러 처리를 포함한다.
+
+**INFRA Agent** — DB 마이그레이션, Docker 설정 변경, CI/CD 파이프라인 수정 등 인프라 관련 작업을 도출한다.
+
+**QA Agent** — 기획안의 기능 명세와 엣지케이스를 기반으로 테스트 항목을 도출한다. FE/BE 구현 결과물을 검증하는 관점에서 작성한다.
+
+#### Section 5: 참고 파일
+
+Agent가 작업 중 참조해야 할 정보를 **인라인으로 포함**한다. 파일 경로만 나열하는 것이 아니라, 해당 Agent에게 필요한 부분을 발췌하여 직접 넣는다.
+
+**Agent별 참고 자료 선별 기준:**
+
+| Agent | 포함하는 것 | 포함하지 않는 것 |
+|-------|------------|----------------|
+| FE | 화면 시안, 컴포넌트 구조, 호출할 API 목록(엔드포인트+요청/응답) | ERD, DB 스키마, 인프라 설정 |
+| BE | API 명세 전체, ERD/DB 스키마, 비즈니스 로직 규칙 | 화면 시안, CSS 구조 |
+| INFRA | DB 스키마(마이그레이션용), 배포 관련 설정, 환경 변수 목록 | 화면 시안, 상세 API 로직 |
+| QA | 기능 명세, 화면 플로우, API 엔드포인트 목록, 엣지케이스 목록 | DB 스키마 상세, 인프라 설정 |
+
+### Step 5: 파일 저장
+
+완성된 task 파일을 `context/` 폴더에 저장한다:
+
+```
+context/04_task_FE.md
+context/04_task_BE.md
+context/04_task_INFRA.md
+context/04_task_QA.md
+```
+
+필요한 Agent의 파일만 생성한다. 예를 들어 FE만 필요한 작업이면 `04_task_FE.md`만 생성한다.
+
+기존 `04_task_*.md`가 있으면 덮어쓰기 전에 사용자에게 확인한다.
+
+### Step 6: 결과 보고
+
+생성 완료 후 아래 형식으로 보고한다:
+
+```
+Task Context 조립 완료:
+- context/04_task_FE.md ✓
+- context/04_task_BE.md ✓
+- context/04_task_QA.md ✓
+
+각 파일의 Section 구성:
+  Section 1~3: 공통 (프로젝트 현황, 요구사항, 기획안)
+  Section 4: Agent별 작업 지시
+  Section 5: Agent별 참고 자료
+```
+
+---
+
+## 완성 파일 구조 예시
+
+```markdown
+# TASK CONTEXT
+
+## 1. 프로젝트 현황
+- 서비스명: MyApp
+- 기술 스택: React + NestJS + PostgreSQL
+- 현재 단계: MVP 운영 중
+
+## 2. 이번 요구사항
+- 작업 유형: 기능 수정
+- 영향 범위: FE, BE
+- 내용: 소셜 로그인(Google, Kakao) 추가
+
+## 3. 기획안 요약
+- Google/Kakao OAuth 2.0 연동
+- 기존 이메일 로그인과 병행 운영
+- 소셜 계정으로 첫 로그인 시 자동 회원가입
+- 엣지케이스: 같은 이메일로 이메일 가입 + 소셜 가입 시 계정 연동
+
+## 4. 네 역할과 작업 지시
+- 역할: 프론트엔드 개발자
+- 해야 할 일:
+  - [ ] 로그인 페이지에 Google/Kakao 소셜 로그인 버튼 추가
+  - [ ] OAuth 리다이렉트 콜백 페이지 구현
+  - [ ] 소셜 로그인 상태 관리 (토큰 저장/갱신)
+- 산출물: React 컴포넌트 + OAuth 콜백 페이지
+- 완료 기준: 소셜 로그인 버튼 클릭 → OAuth 인증 → 토큰 수신 → 로그인 완료
+- 건드리면 안 되는 것: API 서버 코드, DB 스키마
+
+## 5. 참고 파일
+
+### 화면 시안
+(02_design_spec.md에서 발췌한 로그인 화면 관련 내용)
+
+### 호출할 API
+| Method | Endpoint | 설명 |
+|--------|----------|------|
+| GET | /auth/google | Google OAuth 시작 |
+| GET | /auth/google/callback | Google 콜백 처리 |
+| GET | /auth/kakao | Kakao OAuth 시작 |
+| GET | /auth/kakao/callback | Kakao 콜백 처리 |
+```
+
+---
+
+## 품질 체크리스트
+
+파일을 저장하기 전에 점검한다:
+
+- [ ] `00_requirements.md`를 읽었는가?
+- [ ] Section 1~3이 모든 Agent 파일에서 동일한가?
+- [ ] Section 4의 "해야 할 일"이 구체적이고 체크리스트 형태인가?
+- [ ] Section 5에 경로만 나열하지 않고 실제 내용을 발췌했는가?
+- [ ] 각 Agent에게 불필요한 정보를 포함하지 않았는가? (FE에게 ERD 등)
+- [ ] Agent가 이 파일 하나만 읽으면 작업을 시작할 수 있는가? (자족성)