create-claude-pipeline 0.1.0

package/template/.claude/skills/explore-infra/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: explore-infra
+description: "인프라 엔지니어가 작업 전 기존 인프라 설정을 파악할 때 사용하는 skill. Dockerfile, docker-compose, CI/CD 파이프라인, 환경변수, 배포 플랫폼을 탐색해서 기존 설정과 일관된 작업이 가능하게 한다. Infra Agent가 04_task_INFRA.md를 받고 작업에 착수하기 전, 코드베이스를 처음 접하는 상황, 또는 기존 인프라에 새 서비스를 추가할 때 반드시 사용한다."
+context: fork
+agent: Explore
+---
+
+# Explore Infra
+
+Infra Agent가 작업을 시작하기 전에 기존 인프라 설정과 배포 환경을 파악하는 skill이다.
+
+기존 프로젝트에 인프라를 추가하거나 변경할 때, 기존 설정과 다른 방식으로 구성하면 환경이 일관성을 잃는다. 이 skill은 기존 인프라를 탐색해서 "이 프로젝트에서는 이렇게 배포한다"를 파악하고, Infra Agent가 동일한 패턴으로 작업할 수 있도록 현황을 정리한다.
+
+신규 프로젝트(기존 인프라 없음)의 경우에도 실행하되, "기존 인프라 없음 — 처음부터 구성"으로 보고한다.
+
+---
+
+## 탐색 절차
+
+Explore agent를 사용하여 아래 항목들을 순서대로 탐색한다.
+
+### 1. Dockerfile 확인
+
+```
+Glob: **/Dockerfile*
+Glob: **/.dockerignore
+```
+
+확인할 항목:
+
+| 항목 | 왜 중요한가 |
+|------|-----------|
+| Dockerfile 수 | 모노레포면 서비스별 Dockerfile이 있을 수 있다 |
+| 베이스 이미지 | `node:20-alpine` vs `node:20` 등 — 새 Dockerfile도 동일 계열로 |
+| 멀티 스테이지 여부 | 기존이 멀티 스테이지면 새 것도 맞춘다 |
+| .dockerignore 내용 | 빠진 항목이 없는지 확인 |
+
+### 2. docker-compose 확인
+
+```
+Glob: docker-compose*.yml
+Glob: docker-compose*.yaml
+Glob: compose*.yml
+Glob: compose*.yaml
+```
+
+확인할 항목:
+- 정의된 서비스 목록과 각 역할
+- 네트워크 구성 (커스텀 네트워크 / 기본)
+- 볼륨 설정 (DB 영속성, 로컬 마운트)
+- 포트 매핑 현황
+- 환경변수 주입 방식 (`environment` / `env_file`)
+- 헬스체크 설정 여부
+- 개발용 / 프로덕션용 분리 여부
+
+### 3. CI/CD 파이프라인 확인
+
+```
+Glob: .github/workflows/*.yml
+Glob: .github/workflows/*.yaml
+Glob: .gitlab-ci.yml
+Glob: Jenkinsfile
+Glob: .circleci/**/*
+Glob: bitbucket-pipelines.yml
+```
+
+확인할 항목:
+- CI/CD 도구 (GitHub Actions / GitLab CI / Jenkins 등)
+- 트리거 조건 (PR / push / tag)
+- 파이프라인 단계 (lint → test → build → deploy)
+- 시크릿 참조 방식 (`${{ secrets.XXX }}`)
+- 배포 대상 환경 (staging / production)
+- 캐싱 설정 (node_modules, Docker layer 등)
+
+### 4. 환경변수 확인
+
+```
+Glob: .env.example
+Glob: .env.sample
+Glob: .env.template
+Glob: .env.*.example
+Grep: process\.env\.|os\.environ|import\.meta\.env
+```
+
+확인할 항목:
+- 정의된 환경변수 목록과 용도
+- FE용 / BE용 / 공통 분류
+- 시크릿 변수 (DB 비밀번호, API 키 등)
+- 환경별 분기 여부 (.env.development / .env.production)
+
+### 5. package.json scripts 확인
+
+```
+Glob: **/package.json
+```
+
+확인할 항목 (scripts 섹션):
+- 빌드 명령어 (`build`, `build:prod`)
+- 개발 서버 (`dev`, `start:dev`)
+- 테스트 (`test`, `test:e2e`)
+- 린트 (`lint`, `lint:fix`)
+- DB 관련 (`migrate`, `seed`, `db:push`)
+- 배포 관련 (`deploy`, `docker:build`)
+
+### 6. 배포 플랫폼 설정 확인
+
+```
+Glob: vercel.json
+Glob: netlify.toml
+Glob: railway.toml
+Glob: fly.toml
+Glob: app.yaml
+Glob: appspec.yml
+Glob: Procfile
+Glob: render.yaml
+Glob: **/terraform/**/*
+Glob: **/k8s/**/*
+Glob: **/kubernetes/**/*
+```
+
+확인할 항목:
+- 사용 중인 배포 플랫폼
+- 빌드 설정 (빌드 명령어, 출력 디렉토리)
+- 리전/존 설정
+- 스케일링 설정
+- 도메인/라우팅 설정
+
+### 7. 외부 서비스 확인
+
+```
+Grep: postgresql|mysql|mongodb|redis|elasticsearch|rabbitmq|kafka|s3|cloudfront|sentry
+Glob: prisma/schema.prisma
+```
+
+docker-compose, .env.example, package.json 의존성에서 외부 서비스를 추론한다:
+
+| 단서 | 외부 서비스 |
+|------|-----------|
+| `pg`, `@prisma/client`, `DATABASE_URL` | PostgreSQL |
+| `mysql2`, `MYSQL_` | MySQL |
+| `mongoose`, `MONGODB_URI` | MongoDB |
+| `ioredis`, `redis`, `REDIS_URL` | Redis |
+| `@aws-sdk/client-s3`, `S3_BUCKET` | AWS S3 |
+| `@sentry/node`, `SENTRY_DSN` | Sentry |
+| `bull`, `bullmq` | Redis (큐) |
+
+---
+
+## 출력 형식
+
+탐색 결과를 아래 형식으로 정리하여 반환한다:
+
+```markdown
+# 기존 인프라 현황
+
+## 컨테이너화
+
+| 항목 | 상태 |
+|------|------|
+| Dockerfile | FE: Dockerfile / BE: Dockerfile.be |
+| 베이스 이미지 | node:20-alpine |
+| 멀티 스테이지 | 사용 (builder → runner) |
+| docker-compose | 개발용: docker-compose.yml / 프로덕션: docker-compose.prod.yml |
+| 서비스 | app, db (postgres:15), redis |
+| 네트워크 | 커스텀 (app-network) |
+
+## CI/CD
+
+| 항목 | 상태 |
+|------|------|
+| 도구 | GitHub Actions |
+| CI | .github/workflows/ci.yml (PR → lint, test, build) |
+| CD | .github/workflows/cd.yml (main → staging → production) |
+| 캐싱 | node_modules 캐싱 설정됨 |
+| 시크릿 | DEPLOY_KEY, DATABASE_URL 등 사용 |
+
+## 배포 플랫폼
+
+| 항목 | 상태 |
+|------|------|
+| 플랫폼 | AWS ECS / Vercel / Railway 등 |
+| 환경 | staging, production |
+| 배포 방식 | 롤링 / 블루-그린 등 |
+
+## 환경변수
+
+| 변수 | 분류 | 용도 |
+|------|------|------|
+| DATABASE_URL | BE | DB 연결 |
+| JWT_SECRET | BE | 토큰 서명 |
+| NEXT_PUBLIC_API_URL | FE | API 엔드포인트 |
+| NODE_ENV | 공통 | 환경 구분 |
+| PORT | 공통 | 서버 포트 |
+
+## 외부 서비스
+
+| 서비스 | 종류 | 연결 방식 |
+|--------|------|----------|
+| PostgreSQL 15 | DB | docker-compose (로컬) / RDS (프로덕션) |
+| Redis 7 | 캐시/큐 | docker-compose (로컬) |
+
+## 재사용 가능한 설정
+
+- (기존 Dockerfile 패턴, CI/CD 워크플로우 등)
+- 예: "기존 CI에 lint + test + build 3단계가 있으므로 새 서비스도 동일 구조로"
+- 예: "docker-compose에 DB 서비스가 이미 있으므로 새로 추가하지 않아도 됨"
+
+## 새로 만들어야 할 것
+
+- (04_task_INFRA.md 기준으로 기존에 없는 설정)
+- 예: "CD 파이프라인 없음 — 새로 작성 필요"
+- 예: "BE용 Dockerfile 없음 — 기존 FE Dockerfile 패턴 참고하여 작성"
+
+## 주의사항
+
+- (기존 설정과 충돌 가능성, 따라야 할 규칙)
+- 예: "포트 3000은 FE가 사용 중 — BE는 다른 포트를 써야 함"
+- 예: "docker-compose 네트워크가 커스텀이므로 새 서비스도 같은 네트워크에 연결"
+- 예: ".env 파일이 .gitignore에 없음 — 추가 필요"
+```
+
+---
+
+## 신규 프로젝트인 경우
+
+인프라 관련 파일이 전혀 없으면:
+
+```markdown
+# 기존 인프라 현황
+
+기존 인프라 없음 — 처음부터 구성.
+
+## 프로젝트 설정 감지
+
+- package.json: (있음/없음)
+- 감지된 기술: (있으면 나열)
+- .gitignore: (.env 포함 여부)
+
+## 권장사항
+
+(04_task_INFRA.md의 인프라 요구사항에 따름)
+```

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

@@ -0,0 +1,477 @@
+---
+name: implement-api
+description: "BE 개발자가 API를 구현할 때 일관된 레이어 구조와 패턴을 유지하기 위해 참조하는 skill. Route → Controller → Service → Repository 4계층 구조와 입력값 검증(Zod), 에러 처리, 응답 형식 패턴을 제공한다. BE Agent가 API 엔드포인트를 구현하거나, 새 API를 추가하거나, 기존 API를 수정할 때 반드시 사용한다. 'API 구현', 'API 추가', '엔드포인트 작성', 'Controller 작성', 'Service 로직', 'DB 쿼리', 'Zod 검증', 'REST API 만들기' 등의 상황에서 트리거된다."
+---
+
+# Implement API
+
+BE 개발자가 API를 구현할 때 따르는 패턴이다.
+
+API 구현은 "Route → Controller → Service → Repository" 4계층으로 나눈다. 각 레이어가 자기 역할만 하면 코드를 수정할 때 영향 범위가 해당 레이어로 한정된다. 예를 들어 DB를 Prisma에서 Drizzle로 바꿔도 Repository만 수정하면 되고, 검증 로직을 바꿔도 Controller만 수정하면 된다.
+
+API 명세(`context/03_api_spec.md`)를 읽고 각 엔드포인트를 아래 순서로 구현한다.
+
+---
+
+## 폴더 구조
+
+```
+src/
+├── routes/            # HTTP 경로 + 미들웨어 연결
+│   ├── index.ts       # 라우터 통합
+│   └── orders.ts
+├── controllers/       # 요청 파싱 + 검증 + 응답 반환
+│   └── orders.ts
+├── services/          # 비즈니스 로직
+│   └── orders.ts
+├── repositories/      # DB 쿼리
+│   └── orders.ts
+├── schemas/           # Zod 검증 스키마
+│   └── orders.ts
+├── errors/            # 커스텀 에러 클래스
+│   └── index.ts
+├── middleware/         # 인증, 권한, 에러 핸들링
+│   ├── auth.ts
+│   ├── errorHandler.ts
+│   └── validate.ts
+└── types/             # 공유 타입
+    └── orders.ts
+```
+
+기존 프로젝트에 이미 다른 구조가 있으면 **기존 구조를 따른다**. 이 구조는 신규 프로젝트이거나 구조가 없을 때의 기본값이다.
+
+---
+
+## STEP 1: Route 레이어
+
+HTTP 메서드, 경로, 미들웨어를 선언하고 Controller 함수를 연결한다. Route에는 로직을 넣지 않는다. "이 URL로 요청이 오면 어떤 미들웨어를 거쳐 어떤 Controller가 처리하는지" 한눈에 보이게 하는 것이 목적이다.
+
+```ts
+// routes/orders.ts
+import { Router } from "express";
+import { authenticate } from "@/middleware/auth";
+import { validate } from "@/middleware/validate";
+import { createOrderSchema, updateOrderSchema } from "@/schemas/orders";
+import * as ordersController from "@/controllers/orders";
+
+const router = Router();
+
+router.get("/orders", authenticate, ordersController.list);
+router.get("/orders/:id", authenticate, ordersController.getById);
+router.post("/orders", authenticate, validate(createOrderSchema), ordersController.create);
+router.put("/orders/:id", authenticate, validate(updateOrderSchema), ordersController.update);
+router.delete("/orders/:id", authenticate, ordersController.remove);
+
+export default router;
+```
+
+**규칙:**
+- 미들웨어 순서: 인증 → 권한 → 검증 → Controller
+- RESTful 규칙을 따른다 (GET=조회, POST=생성, PUT=수정, DELETE=삭제)
+- URL은 복수형 명사를 사용한다 (`/orders`, `/users`)
+
+---
+
+## STEP 2: Controller 레이어
+
+요청을 파싱하고, Service를 호출하고, 응답을 반환한다. Controller는 비즈니스 로직을 모른다. "요청에서 데이터를 꺼내고, Service에게 넘기고, 결과를 JSON으로 감싸서 돌려준다"가 Controller의 전부이다.
+
+```ts
+// controllers/orders.ts
+import { Request, Response, NextFunction } from "express";
+import * as ordersService from "@/services/orders";
+
+export async function list(req: Request, res: Response, next: NextFunction) {
+  try {
+    const { page = 1, limit = 20 } = req.query;
+    const result = await ordersService.getOrders({
+      page: Number(page),
+      limit: Number(limit),
+    });
+
+    res.json({
+      success: true,
+      data: result,
+    });
+  } catch (error) {
+    next(error);
+  }
+}
+
+export async function getById(req: Request, res: Response, next: NextFunction) {
+  try {
+    const order = await ordersService.getOrderById(req.params.id);
+
+    res.json({
+      success: true,
+      data: order,
+    });
+  } catch (error) {
+    next(error);
+  }
+}
+
+export async function create(req: Request, res: Response, next: NextFunction) {
+  try {
+    const order = await ordersService.createOrder(req.body);
+
+    res.status(201).json({
+      success: true,
+      data: order,
+    });
+  } catch (error) {
+    next(error);
+  }
+}
+
+export async function update(req: Request, res: Response, next: NextFunction) {
+  try {
+    const order = await ordersService.updateOrder(req.params.id, req.body);
+
+    res.json({
+      success: true,
+      data: order,
+    });
+  } catch (error) {
+    next(error);
+  }
+}
+
+export async function remove(req: Request, res: Response, next: NextFunction) {
+  try {
+    await ordersService.deleteOrder(req.params.id);
+
+    res.status(204).send();
+  } catch (error) {
+    next(error);
+  }
+}
+```
+
+**규칙:**
+- 모든 Controller 함수는 `try/catch`로 감싸고, catch에서 `next(error)`로 에러 미들웨어에 넘긴다
+- `req.body`는 이미 validate 미들웨어에서 검증된 상태이므로 Controller에서 재검증하지 않는다
+- HTTP 상태 코드: 생성=201, 삭제=204, 그 외=200
+- 성공 응답은 `{ success: true, data: ... }` 형식으로 통일한다
+
+---
+
+## STEP 3: 입력값 검증 (Zod)
+
+Zod 스키마로 요청 데이터를 검증한다. 검증은 Controller가 아니라 미들웨어에서 처리하므로, Controller에 도달한 시점에는 데이터가 이미 유효하다.
+
+### 검증 스키마
+
+```ts
+// schemas/orders.ts
+import { z } from "zod";
+
+export const createOrderSchema = z.object({
+  body: z.object({
+    productId: z.string().uuid("유효한 상품 ID가 필요합니다"),
+    quantity: z.number().int().min(1, "수량은 1 이상이어야 합니다"),
+    shippingAddress: z.string().min(1, "배송 주소를 입력해주세요"),
+  }),
+});
+
+export const updateOrderSchema = z.object({
+  params: z.object({
+    id: z.string().uuid(),
+  }),
+  body: z.object({
+    quantity: z.number().int().min(1).optional(),
+    shippingAddress: z.string().min(1).optional(),
+  }),
+});
+
+// 타입 추출 — 별도 타입 정의 없이 스키마에서 추론
+export type CreateOrderInput = z.infer<typeof createOrderSchema>["body"];
+export type UpdateOrderInput = z.infer<typeof updateOrderSchema>["body"];
+```
+
+### 검증 미들웨어
+
+```ts
+// middleware/validate.ts
+import { Request, Response, NextFunction } from "express";
+import { AnyZodObject, ZodError } from "zod";
+
+export function validate(schema: AnyZodObject) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    try {
+      schema.parse({
+        body: req.body,
+        query: req.query,
+        params: req.params,
+      });
+      next();
+    } catch (error) {
+      if (error instanceof ZodError) {
+        res.status(422).json({
+          success: false,
+          error: {
+            code: "VALIDATION_ERROR",
+            message: "입력값이 올바르지 않습니다.",
+            details: error.errors.map((e) => ({
+              field: e.path.join("."),
+              message: e.message,
+            })),
+          },
+        });
+        return;
+      }
+      next(error);
+    }
+  };
+}
+```
+
+**규칙:**
+- `body`, `params`, `query`를 하나의 스키마 객체로 묶어서 검증한다
+- 에러 메시지는 한국어로 사용자 친화적으로 작성한다
+- `z.infer`로 타입을 추출하여 별도 인터페이스 중복을 방지한다
+
+---
+
+## STEP 4: Service 레이어
+
+비즈니스 로직을 담당한다. Service는 HTTP를 모른다 — `req`, `res` 객체를 받지 않는다. 순수한 데이터 입출력만 처리하기 때문에 테스트하기 쉽고, 같은 로직을 REST API든 GraphQL이든 CLI든 어디서든 재사용할 수 있다.
+
+```ts
+// services/orders.ts
+import * as ordersRepo from "@/repositories/orders";
+import { NotFoundError, BusinessError } from "@/errors";
+import type { CreateOrderInput, UpdateOrderInput } from "@/schemas/orders";
+
+export async function getOrders({ page, limit }: { page: number; limit: number }) {
+  const offset = (page - 1) * limit;
+  const [items, total] = await Promise.all([
+    ordersRepo.findMany({ offset, limit }),
+    ordersRepo.count(),
+  ]);
+
+  return {
+    items,
+    pagination: {
+      page,
+      limit,
+      total,
+      totalPages: Math.ceil(total / limit),
+    },
+  };
+}
+
+export async function getOrderById(id: string) {
+  const order = await ordersRepo.findById(id);
+  if (!order) {
+    throw new NotFoundError("주문을 찾을 수 없습니다.");
+  }
+  return order;
+}
+
+export async function createOrder(input: CreateOrderInput) {
+  // 비즈니스 규칙 검증
+  const product = await productsRepo.findById(input.productId);
+  if (!product) {
+    throw new NotFoundError("상품을 찾을 수 없습니다.");
+  }
+  if (product.stock < input.quantity) {
+    throw new BusinessError("INSUFFICIENT_STOCK", "재고가 부족합니다.");
+  }
+
+  // 트랜잭션이 필요한 경우
+  return await db.transaction(async (tx) => {
+    const order = await ordersRepo.create(input, tx);
+    await productsRepo.decrementStock(input.productId, input.quantity, tx);
+    return order;
+  });
+}
+
+export async function updateOrder(id: string, input: UpdateOrderInput) {
+  const existing = await ordersRepo.findById(id);
+  if (!existing) {
+    throw new NotFoundError("주문을 찾을 수 없습니다.");
+  }
+  return await ordersRepo.update(id, input);
+}
+
+export async function deleteOrder(id: string) {
+  const existing = await ordersRepo.findById(id);
+  if (!existing) {
+    throw new NotFoundError("주문을 찾을 수 없습니다.");
+  }
+  await ordersRepo.remove(id);
+}
+```
+
+**규칙:**
+- `req`, `res`를 받지 않는다 — 순수 데이터 입출력만 처리
+- 비즈니스 규칙 위반 시 커스텀 에러를 throw한다 (HTTP 상태 코드가 아니라 비즈니스 에러)
+- 여러 Repository를 조합하여 하나의 유스케이스를 완성한다
+- 트랜잭션이 필요하면 Service에서 관리한다
+
+---
+
+## STEP 5: Repository 레이어
+
+DB 쿼리만 담당한다. Repository는 비즈니스 로직을 모른다 — "이 조건으로 데이터를 찾아줘", "이 데이터를 저장해줘"를 처리할 뿐이다. ORM을 바꿔도 Repository만 수정하면 나머지 코드는 영향을 받지 않는다.
+
+```ts
+// repositories/orders.ts
+import { db } from "@/lib/db";  // Prisma, Drizzle, 또는 프로젝트의 ORM
+import type { CreateOrderInput, UpdateOrderInput } from "@/schemas/orders";
+
+export async function findMany({ offset, limit }: { offset: number; limit: number }) {
+  return db.order.findMany({
+    skip: offset,
+    take: limit,
+    orderBy: { createdAt: "desc" },
+  });
+}
+
+export async function count() {
+  return db.order.count();
+}
+
+export async function findById(id: string) {
+  return db.order.findUnique({ where: { id } });
+}
+
+export async function create(input: CreateOrderInput, tx?: any) {
+  const client = tx || db;
+  return client.order.create({
+    data: {
+      ...input,
+      status: "pending",
+    },
+  });
+}
+
+export async function update(id: string, input: UpdateOrderInput) {
+  return db.order.update({
+    where: { id },
+    data: input,
+  });
+}
+
+export async function remove(id: string) {
+  return db.order.delete({ where: { id } });
+}
+```
+
+**규칙:**
+- ORM 메서드만 사용한다 — raw SQL은 성능 최적화가 필요할 때만
+- 트랜잭션 클라이언트를 선택적으로 받을 수 있도록 `tx` 파라미터를 지원한다
+- 리턴 타입은 ORM이 추론하도록 두고, 명시적 타입이 필요하면 Service에서 처리한다
+
+---
+
+## 에러 처리
+
+### 커스텀 에러 클래스
+
+비즈니스 에러를 HTTP 상태 코드와 분리한다. Service는 "재고 부족"이라는 비즈니스 사실만 알리고, 이것을 HTTP 409로 변환하는 것은 에러 미들웨어의 역할이다.
+
+```ts
+// errors/index.ts
+export class AppError extends Error {
+  constructor(
+    public statusCode: number,
+    public code: string,
+    message: string,
+    public details?: any
+  ) {
+    super(message);
+    this.name = "AppError";
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message = "리소스를 찾을 수 없습니다.") {
+    super(404, "NOT_FOUND", message);
+  }
+}
+
+export class BusinessError extends AppError {
+  constructor(code: string, message: string, details?: any) {
+    super(409, code, message, details);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = "인증이 필요합니다.") {
+    super(401, "UNAUTHORIZED", message);
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = "접근 권한이 없습니다.") {
+    super(403, "FORBIDDEN", message);
+  }
+}
+```
+
+### 에러 핸들링 미들웨어
+
+모든 에러를 한 곳에서 통일된 형식으로 변환한다.
+
+```ts
+// middleware/errorHandler.ts
+import { Request, Response, NextFunction } from "express";
+import { AppError } from "@/errors";
+
+export function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
+  // 커스텀 에러 — 정의된 상태 코드와 코드 사용
+  if (err instanceof AppError) {
+    res.status(err.statusCode).json({
+      success: false,
+      error: {
+        code: err.code,
+        message: err.message,
+        ...(err.details && { details: err.details }),
+      },
+    });
+    return;
+  }
+
+  // 예상하지 못한 에러 — 내부 정보 노출 방지
+  console.error("Unhandled error:", err);
+  res.status(500).json({
+    success: false,
+    error: {
+      code: "INTERNAL_ERROR",
+      message: "서버 오류가 발생했습니다.",
+    },
+  });
+}
+```
+
+### 응답 형식 정리
+
+| 상황 | HTTP 상태 | 응답 형식 |
+|------|-----------|-----------|
+| 성공 (조회/수정) | 200 | `{ success: true, data: { ... } }` |
+| 성공 (생성) | 201 | `{ success: true, data: { ... } }` |
+| 성공 (삭제) | 204 | 빈 응답 |
+| 입력값 오류 | 422 | `{ success: false, error: { code: "VALIDATION_ERROR", message, details } }` |
+| 인증 실패 | 401 | `{ success: false, error: { code: "UNAUTHORIZED", message } }` |
+| 권한 없음 | 403 | `{ success: false, error: { code: "FORBIDDEN", message } }` |
+| 리소스 없음 | 404 | `{ success: false, error: { code: "NOT_FOUND", message } }` |
+| 비즈니스 에러 | 409 | `{ success: false, error: { code: "INSUFFICIENT_STOCK", message } }` |
+| 서버 에러 | 500 | `{ success: false, error: { code: "INTERNAL_ERROR", message } }` |
+
+---
+
+## 구현 순서 체크리스트
+
+API 엔드포인트를 구현할 때 아래 순서로 진행한다:
+
+1. [ ] `context/03_api_spec.md`에서 구현할 엔드포인트 확인
+2. [ ] `schemas/`에 Zod 검증 스키마 + 타입 추출
+3. [ ] `repositories/`에 DB 쿼리 함수 작성
+4. [ ] `services/`에 비즈니스 로직 작성
+5. [ ] `controllers/`에 요청/응답 처리 작성
+6. [ ] `routes/`에 경로 + 미들웨어 연결
+7. [ ] `errors/`에 필요한 커스텀 에러 추가 (기존에 없는 경우)
+8. [ ] 에러 핸들링 미들웨어 확인 (이미 있으면 스킵)
+9. [ ] 응답 형식 확인 (success/error 구조 준수)