create-claude-pipeline 0.1.0

package/template/.claude/skills/db-migration/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: db-migration
+description: "BE 개발자가 DB 스키마를 변경할 때 안전하게 마이그레이션하기 위한 절차와 주의사항을 제공하는 skill. 기존 데이터 영향 검토부터 롤백 계획까지 포함한다. BE Agent가 테이블/컬럼을 추가·변경·삭제하거나, 인덱스를 생성하거나, 관계(FK)를 수정할 때 반드시 사용한다. 'DB 마이그레이션', '스키마 변경', '테이블 추가', '컬럼 변경', '인덱스 추가', 'prisma migrate', 'ALTER TABLE', 'FK 추가', 'NOT NULL 컬럼 추가' 등의 상황에서 트리거된다."
+---
+
+# DB Migration
+
+BE 개발자가 DB 스키마를 변경할 때 따르는 절차다.
+
+프로덕션 DB에는 이미 데이터가 있다. 개발 환경에서 잘 돌아가는 마이그레이션이 프로덕션에서 데이터 유실이나 장시간 락을 일으킬 수 있다. 이 skill은 "변경 전 영향을 먼저 파악하고, 안전한 방식으로 변경하고, 문제 시 되돌릴 수 있는" 절차를 제공한다.
+
+---
+
+## STEP 1: 변경 전 영향 분석
+
+스키마를 바꾸기 전에 현재 상태를 파악한다. 기존 데이터가 없는 신규 테이블이면 이 단계를 가볍게 넘겨도 되지만, 기존 테이블을 수정하는 경우 반드시 확인한다.
+
+### 확인 항목
+
+```
+Glob: prisma/schema.prisma
+Glob: src/models/**/*
+Glob: src/entities/**/*
+Grep: @relation|references:|foreignKey|@ManyToOne|@OneToMany|@ManyToMany
+```
+
+| 확인 항목 | 왜 중요한가 |
+|---------|-----------|
+| 변경되는 테이블/컬럼 목록 | 영향 범위를 한정한다 |
+| 해당 테이블에 기존 데이터가 있는지 | 데이터 마이그레이션 필요 여부를 결정한다 |
+| 다른 테이블과의 관계(FK) | FK가 있으면 변경 순서가 중요하다 — 참조되는 쪽을 먼저 바꿔야 한다 |
+| 해당 컬럼을 사용하는 쿼리/서비스 | 스키마 변경이 애플리케이션 코드에 미치는 영향을 파악한다 |
+| 인덱스 현황 | 기존 인덱스가 새 스키마에서도 유효한지 확인한다 |
+
+### 출력 형식
+
+분석 결과를 아래 형식으로 정리한다:
+
+```markdown
+## 영향 분석
+
+| 테이블 | 변경 유형 | 기존 데이터 | FK 관계 | 영향받는 코드 |
+|--------|---------|-----------|---------|-------------|
+| orders | 컬럼 추가 | 있음 (약 10만 건) | users.id → orders.userId | services/orders.ts, repositories/orders.ts |
+| order_items | 신규 생성 | 없음 | orders.id → order_items.orderId | - |
+
+### 위험 요소
+- orders 테이블에 NOT NULL 컬럼 추가 시 기존 데이터에 default 값 필요
+- order_items FK 생성 시 orders 테이블에 락 발생 가능
+```
+
+---
+
+## STEP 2: 안전한 변경 원칙
+
+프로덕션 DB를 안전하게 변경하기 위한 원칙이다. 핵심은 "되돌릴 수 없는 변경을 피하고, 불가피하면 단계를 나눈다"이다.
+
+### 위험한 변경과 안전한 대안
+
+| 위험한 변경 | 왜 위험한가 | 안전한 대안 |
+|-----------|-----------|-----------|
+| 컬럼 삭제 | 데이터 유실, 롤백 불가 | nullable로 변경 → 앱에서 사용 안 함 확인 → 추후 별도 마이그레이션으로 삭제 |
+| 컬럼명 변경 | 앱 코드와 동시 배포 필요, 실패 시 양쪽 다 깨짐 | 새 컬럼 추가 → 데이터 복사 → 앱이 새 컬럼 사용 → 구 컬럼 제거 |
+| NOT NULL 컬럼 추가 (default 없음) | 기존 행에 값이 없어서 실패 | default 값 반드시 지정 |
+| 타입 변경 (예: varchar → int) | 기존 데이터 변환 실패 가능 | 새 컬럼 추가 → 데이터 변환 스크립트 → 컬럼 교체 |
+| 대형 테이블에 인덱스 추가 | 장시간 테이블 락 | 별도 마이그레이션으로 분리, `CREATE INDEX CONCURRENTLY` 사용 (PostgreSQL) |
+
+### NOT NULL 컬럼 추가 시
+
+기존 데이터가 있는 테이블에 NOT NULL 컬럼을 추가하려면:
+
+```
+-- 1단계: nullable + default로 추가
+ALTER TABLE orders ADD COLUMN priority VARCHAR(10) DEFAULT 'normal';
+
+-- 2단계: 기존 행에 값 채우기 (필요 시)
+UPDATE orders SET priority = 'normal' WHERE priority IS NULL;
+
+-- 3단계: NOT NULL 제약 추가
+ALTER TABLE orders ALTER COLUMN priority SET NOT NULL;
+```
+
+Prisma의 경우:
+
+```prisma
+// 1단계 마이그레이션: optional + default로 추가
+model Order {
+  priority String? @default("normal")
+}
+
+// 2단계 마이그레이션: required로 변경
+model Order {
+  priority String @default("normal")
+}
+```
+
+---
+
+## STEP 3: 마이그레이션 파일 작성
+
+### 파일명 규칙
+
+```
+YYYYMMDD_HHMMSS_description
+```
+
+설명은 변경 내용을 명확하게 나타내야 한다. "뭘 했는지" 한눈에 알 수 있어야 나중에 마이그레이션 히스토리를 추적할 수 있다.
+
+**좋은 예:**
+- `20260323_143000_add_priority_to_orders`
+- `20260323_150000_create_order_items_table`
+- `20260323_160000_add_index_orders_userId`
+
+**나쁜 예:**
+- `20260323_143000_update_schema`
+- `20260323_150000_fix`
+- `migration_1`
+
+### up/down 구조
+
+모든 마이그레이션은 반드시 up(적용)과 down(롤백)을 모두 작성한다. 롤백을 작성하지 않으면 문제 발생 시 수동으로 되돌려야 하는데, 장애 상황에서 수동 작업은 실수가 나기 쉽다.
+
+```ts
+// Knex 예시
+export async function up(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("orders", (table) => {
+    table.string("priority", 10).defaultTo("normal").notNullable();
+  });
+}
+
+export async function down(knex: Knex): Promise<void> {
+  await knex.schema.alterTable("orders", (table) => {
+    table.dropColumn("priority");
+  });
+}
+```
+
+```sql
+-- Raw SQL 예시
+-- up
+ALTER TABLE orders ADD COLUMN priority VARCHAR(10) NOT NULL DEFAULT 'normal';
+
+-- down
+ALTER TABLE orders DROP COLUMN priority;
+```
+
+Prisma의 경우 `prisma migrate dev`가 자동으로 마이그레이션 파일을 생성하지만, 생성된 SQL을 반드시 확인한다. Prisma는 down 마이그레이션을 자동 생성하지 않으므로, 위험한 변경에는 롤백 SQL을 별도로 문서화한다.
+
+### 하나의 마이그레이션 = 하나의 변경
+
+마이그레이션 하나에 여러 변경을 넣지 않는다. 테이블 생성과 인덱스 추가는 별도 마이그레이션으로 분리한다. 이유:
+- 인덱스 생성이 실패해도 테이블 생성은 유지된다
+- 롤백 범위를 세밀하게 제어할 수 있다
+- 대형 테이블의 인덱스 생성은 시간이 오래 걸릴 수 있다
+
+```
+# 좋은 예: 분리된 마이그레이션
+20260323_143000_create_order_items_table
+20260323_143100_add_index_order_items_orderId
+
+# 나쁜 예: 하나에 다 넣음
+20260323_143000_create_order_items_with_indexes
+```
+
+---
+
+## STEP 4: 인덱스 설계
+
+인덱스는 쿼리 성능에 직접적인 영향을 미치지만, 불필요한 인덱스는 쓰기 성능을 떨어뜨리고 저장 공간을 낭비한다. "이 쿼리가 느릴 것 같으니 인덱스를 걸자"가 아니라 "실제 쿼리 패턴에 맞는 인덱스를 설계하자"가 맞다.
+
+### 인덱스가 필요한 경우
+
+| 상황 | 예시 | 인덱스 대상 |
+|------|------|-----------|
+| WHERE 절에 자주 쓰이는 컬럼 | `WHERE status = 'active'` | `status` |
+| JOIN 조건의 FK 컬럼 | `JOIN orders ON users.id = orders.userId` | `orders.userId` |
+| 정렬에 자주 쓰이는 컬럼 | `ORDER BY createdAt DESC` | `createdAt` |
+| 유니크 제약이 필요한 컬럼 | `email`, `slug` | UNIQUE 인덱스 |
+
+### 복합 인덱스 순서
+
+복합 인덱스는 컬럼 순서가 중요하다. 카디널리티(고유값 수)가 높은 컬럼을 앞에 놓는다.
+
+```sql
+-- 좋은 예: userId(카디널리티 높음) → status(카디널리티 낮음)
+CREATE INDEX idx_orders_userId_status ON orders(userId, status);
+
+-- 쿼리에서 활용:
+-- SELECT * FROM orders WHERE userId = ? AND status = ?   ← 인덱스 사용
+-- SELECT * FROM orders WHERE userId = ?                   ← 인덱스 사용 (선두 컬럼)
+-- SELECT * FROM orders WHERE status = ?                   ← 인덱스 미사용 (선두 컬럼 없음)
+```
+
+### 인덱스를 걸지 말아야 할 경우
+
+- 행 수가 적은 테이블 (수천 건 이하) — 풀스캔이 더 빠를 수 있다
+- INSERT/UPDATE가 매우 빈번한 컬럼 — 인덱스 유지 비용이 조회 이점을 초과
+- 카디널리티가 매우 낮은 컬럼 단독 (예: boolean) — 인덱스 효과가 미미
+
+### Prisma에서 인덱스 정의
+
+```prisma
+model Order {
+  id        String   @id @default(uuid())
+  userId    String
+  status    String
+  createdAt DateTime @default(now())
+
+  user User @relation(fields: [userId], references: [id])
+
+  @@index([userId, status])    // 복합 인덱스
+  @@index([createdAt])          // 정렬용 인덱스
+}
+```
+
+---
+
+## 마이그레이션 실행 체크리스트
+
+마이그레이션을 실행하기 전에 아래를 확인한다:
+
+1. [ ] **영향 분석 완료** — 변경 대상 테이블, 기존 데이터 유무, FK 관계 파악
+2. [ ] **안전한 변경 원칙 준수** — 컬럼 삭제/변경 대신 안전한 대안 적용
+3. [ ] **마이그레이션 파일 작성** — 명확한 파일명, up/down 모두 작성
+4. [ ] **인덱스 분리** — 테이블 변경과 인덱스 생성은 별도 마이그레이션
+5. [ ] **롤백 테스트** — down 마이그레이션이 정상 동작하는지 확인
+6. [ ] **앱 코드 호환성** — 스키마 변경 후에도 기존 앱 코드가 동작하는지 확인
+7. [ ] **데이터 마이그레이션** — 기존 데이터에 대한 변환/채우기 스크립트 준비 (필요 시)

package/template/.claude/skills/explore-be-codebase/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: explore-be-codebase
+description: "BE 개발자가 구현 전 기존 백엔드 코드 구조를 파악할 때 사용하는 skill. 폴더 구조, ORM 패턴, 인증 방식, 에러 핸들링 패턴을 탐색해서 일관된 구현이 가능하게 한다. BE Agent가 04_task_BE.md를 받고 구현에 착수하기 전, 코드베이스를 처음 접하는 상황, 또는 기존 BE 코드에 새 API를 추가할 때 반드시 사용한다."
+context: fork
+agent: Explore
+---
+
+# Explore BE Codebase
+
+BE Agent가 구현을 시작하기 전에 기존 백엔드 코드의 구조와 패턴을 파악하는 skill이다.
+
+기존 프로젝트에 API를 추가할 때, 기존 패턴과 다른 방식으로 구현하면 코드베이스가 일관성을 잃는다. 이 skill은 기존 코드를 탐색해서 "이 프로젝트에서는 이렇게 한다"를 파악하고, BE Agent가 동일한 패턴으로 구현할 수 있도록 현황을 정리한다.
+
+신규 프로젝트(기존 코드 없음)의 경우에도 실행하되, "기존 BE 코드 없음 — 처음부터 구현"으로 보고한다.
+
+---
+
+## 탐색 절차
+
+Explore agent를 사용하여 아래 항목들을 순서대로 탐색한다.
+
+### 1. 의존성 파악
+
+`package.json`을 읽어서 프레임워크와 주요 라이브러리를 파악한다.
+
+```
+Glob: **/package.json
+```
+
+확인할 항목:
+
+| 카테고리 | 찾을 패키지 |
+|---------|-----------|
+| 프레임워크 | `express`, `fastify`, `@nestjs/core`, `hono`, `koa`, `@hapi/hapi` |
+| ORM/DB | `prisma`, `@prisma/client`, `typeorm`, `drizzle-orm`, `sequelize`, `mongoose`, `knex`, `pg`, `mysql2`, `better-sqlite3` |
+| 인증 | `jsonwebtoken`, `passport`, `@nestjs/jwt`, `bcrypt`, `bcryptjs`, `express-session`, `cookie-session` |
+| 유효성 검사 | `zod`, `joi`, `class-validator`, `yup`, `ajv` |
+| API 문서 | `@nestjs/swagger`, `swagger-jsdoc`, `swagger-ui-express` |
+| 테스트 | `jest`, `vitest`, `supertest`, `mocha`, `chai` |
+| 로깅 | `winston`, `pino`, `morgan`, `@nestjs/common` (Logger) |
+| 기타 | `dotenv`, `cors`, `helmet`, `express-rate-limit`, `multer`, `nodemailer`, `bull`, `ioredis` |
+
+버전도 함께 기록한다 — 메이저 버전에 따라 API가 다를 수 있다.
+
+Python 프로젝트인 경우 `requirements.txt`, `pyproject.toml`, `Pipfile`을 확인한다:
+
+| 카테고리 | 찾을 패키지 |
+|---------|-----------|
+| 프레임워크 | `fastapi`, `django`, `flask`, `starlette` |
+| ORM/DB | `sqlalchemy`, `tortoise-orm`, `django-orm`, `prisma`, `peewee`, `sqlmodel` |
+| 인증 | `python-jose`, `pyjwt`, `passlib`, `python-multipart` |
+| 유효성 검사 | `pydantic` |
+
+### 2. 폴더 구조 파악
+
+프로젝트의 디렉토리 레이아웃을 파악한다.
+
+```
+Glob: src/**/*
+Glob: server/**/*
+Glob: api/**/*
+Glob: routes/**/*
+Glob: controllers/**/*
+Glob: services/**/*
+Glob: models/**/*
+Glob: middlewares/**/*
+```
+
+확인할 패턴:
+
+| 패턴 | 의미 |
+|------|------|
+| `src/routes/` | 라우트 정의 |
+| `src/controllers/` | 컨트롤러 레이어 |
+| `src/services/` | 비즈니스 로직 레이어 |
+| `src/models/` 또는 `src/entities/` | DB 모델/엔티티 |
+| `src/middlewares/` 또는 `src/middleware/` | 미들웨어 |
+| `src/utils/` 또는 `src/lib/` | 유틸리티/헬퍼 |
+| `src/config/` | 설정 파일 |
+| `src/types/` | 타입 정의 |
+| `prisma/` | Prisma 스키마/마이그레이션 |
+| `src/modules/` (NestJS) | 모듈 단위 구성 |
+| `src/dto/` (NestJS) | DTO 정의 |
+
+### 3. 기존 API 엔드포인트 목록
+
+```
+Grep: router\.(get|post|put|patch|delete)\(|app\.(get|post|put|patch|delete)\(|@(Get|Post|Put|Patch|Delete)\(|@api_view|@app\.(get|post|put|patch|delete)
+Glob: src/routes/**/*.{ts,js}
+Glob: src/controllers/**/*.{ts,js}
+```
+
+기존에 구현된 API 엔드포인트 목록을 정리한다:
+- HTTP 메서드
+- 경로 (path)
+- 담당 컨트롤러/핸들러
+- 인증 필요 여부
+
+### 4. 인증 미들웨어 구현 방식
+
+```
+Grep: jwt|passport|auth|token|Bearer|session
+Glob: src/middlewares/auth*
+Glob: src/middleware/auth*
+Glob: src/guards/**/*
+Glob: src/auth/**/*
+```
+
+확인할 것:
+- 인증 방식 (JWT / Session / OAuth / API Key)
+- 토큰 저장 위치 (header / cookie)
+- 토큰 검증 로직 (미들웨어/가드 위치와 구현)
+- 역할 기반 접근 제어 (RBAC) 유무
+- 리프레시 토큰 처리 방식
+
+### 5. ORM 스키마 / 모델 파일
+
+```
+Glob: prisma/schema.prisma
+Glob: src/models/**/*.{ts,js}
+Glob: src/entities/**/*.{ts,js}
+Glob: src/schemas/**/*.{ts,js}
+Grep: @Entity|@Table|@Column|model\s+\w+\s*\{|Schema\(|defineTable
+```
+
+확인할 것:
+- 사용하는 ORM과 스키마 정의 방식
+- 기존 모델/테이블 목록
+- 관계 설정 패턴 (1:N, N:M 등)
+- 마이그레이션 관리 방식
+- soft delete, timestamp 등 공통 필드 패턴
+
+### 6. 에러 핸들링 패턴
+
+```
+Grep: class\s+\w*Error|class\s+\w*Exception|ErrorHandler|errorHandler|@Catch|HttpException|createError
+Glob: src/errors/**/*
+Glob: src/exceptions/**/*
+Glob: src/utils/error*
+```
+
+확인할 것:
+- 커스텀 에러 클래스 정의 여부
+- 에러 응답 형식 (JSON 구조)
+- 글로벌 에러 핸들러 위치와 구현
+- HTTP 상태 코드 사용 패턴
+- 유효성 검사 에러 처리 방식
+
+### 7. 환경변수 구성
+
+```
+Glob: .env.example
+Glob: .env.sample
+Glob: src/config/**/*
+Grep: process\.env\.|config\.(get|has)|@ConfigService|os\.environ|settings\.
+```
+
+확인할 것:
+- 환경변수 목록과 용도
+- 설정 로딩 방식 (dotenv / @nestjs/config / config 모듈)
+- 환경별 분기 (dev / staging / prod)
+
+---
+
+## 출력 형식
+
+탐색 결과를 아래 형식으로 정리하여 반환한다:
+
+```markdown
+# 기존 BE 코드 현황
+
+## 기술 스택
+
+| 카테고리 | 사용 기술 | 버전 |
+|---------|---------|------|
+| 프레임워크 | Express | 4.x |
+| ORM | Prisma | 5.x |
+| 인증 | jsonwebtoken + bcrypt | 9.x / 5.x |
+| 유효성 검사 | zod | 3.x |
+| 테스트 | Jest + supertest | 29.x / 6.x |
+| 로깅 | winston | 3.x |
+
+## 폴더 구조
+
+(실제 디렉토리 트리)
+
+## 기존 API 목록
+
+| 메서드 | 경로 | 설명 | 인증 |
+|--------|------|------|------|
+| POST | /api/auth/login | 로그인 | X |
+| GET | /api/users/me | 내 정보 조회 | O |
+| POST | /api/posts | 게시글 생성 | O |
+
+## 인증 방식
+
+- 방식: JWT (Access + Refresh)
+- 토큰 위치: Authorization header (Bearer)
+- 미들웨어: src/middlewares/auth.ts
+- RBAC: 없음 / 있음 (역할: admin, user)
+
+## ORM / DB 스키마
+
+- ORM: Prisma
+- 스키마: prisma/schema.prisma
+- 기존 모델: User, Post, Comment, ...
+- 관계: User 1:N Post, Post 1:N Comment
+- 공통 패턴: createdAt/updatedAt 자동 생성, soft delete 미사용
+
+## 에러 핸들링 패턴
+
+- 커스텀 에러: AppError (statusCode, message, isOperational)
+- 응답 형식: { success: false, error: { code, message } }
+- 글로벌 핸들러: src/middlewares/errorHandler.ts
+- 유효성 검사: zod → 400 Bad Request
+
+## 재사용 가능한 미들웨어
+
+| 미들웨어 | 경로 | 용도 |
+|---------|------|------|
+| auth | middlewares/auth.ts | JWT 검증 |
+| validate | middlewares/validate.ts | 요청 유효성 검사 |
+| upload | middlewares/upload.ts | 파일 업로드 (multer) |
+
+## 환경변수
+
+| 변수 | 용도 |
+|------|------|
+| DATABASE_URL | DB 연결 |
+| JWT_SECRET | 토큰 서명 |
+| PORT | 서버 포트 |
+
+## 주의사항
+
+- (기존 패턴과 충돌 가능성, 따라야 할 컨벤션, 주의할 점)
+- 예: "모든 라우트는 /api 접두사를 사용 — 직접 / 에 매핑하지 말 것"
+- 예: "비즈니스 로직은 반드시 services/ 레이어에 — controller에서 직접 DB 호출하지 말 것"
+- 예: "에러는 반드시 AppError 클래스를 사용 — new Error() 직접 사용 금지"
+```
+
+---
+
+## 신규 프로젝트인 경우
+
+BE 관련 파일이 전혀 없으면:
+
+```markdown
+# 기존 BE 코드 현황
+
+기존 BE 코드 없음 — 처음부터 구현.
+
+## 프로젝트 설정 감지
+
+- package.json: (있음/없음)
+- 감지된 기술: (있으면 나열)
+
+## 권장사항
+
+(04_task_BE.md의 기술 스택 지시에 따름)
+```

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

@@ -0,0 +1,190 @@
+---
+name: explore-codebase
+description: "기획자 Agent가 기획안 작성 전에 기존 코드베이스의 현황을 파악할 때 사용하는 skill. 현재 구현된 기능, 화면 구조, API 패턴, DB 모델을 탐색해서 기획안이 기존 서비스와 일관성을 유지하도록 한다. 기획자가 STEP 2(기존 서비스 파악)를 수행할 때, 코드베이스를 처음 접하는 상황에서, 또는 기존 기능을 수정/확장하는 기획을 할 때 반드시 사용한다."
+---
+
+# Explore Codebase
+
+기획자 Agent가 기획안을 작성하기 전에 기존 코드베이스를 체계적으로 탐색하는 skill이다.
+
+기획안이 기존 서비스와 충돌하지 않으려면, 현재 무엇이 구현되어 있는지를 정확히 알아야 한다. 이 skill은 코드베이스를 실제로 읽고 기존 패턴을 파악해서, 기획자가 현실에 맞는 기획을 할 수 있도록 돕는다.
+
+---
+
+## 탐색 절차
+
+### Step 1: 프로젝트 루트 구조 파악
+
+프로젝트의 전체적인 모습을 빠르게 스캔한다.
+
+```
+Glob: package.json, requirements.txt, go.mod, Cargo.toml, pom.xml, build.gradle
+Glob: docker-compose*, Dockerfile*
+Glob: .github/workflows/*, .gitlab-ci.yml
+```
+
+파악할 내용:
+- **기술 스택**: 언어, 프레임워크, 주요 라이브러리
+- **프로젝트 구조**: 모노레포 / FE·BE 분리 / 풀스택 일체형
+- **인프라**: Docker, CI/CD 파이프라인 유무
+
+package.json이나 requirements.txt의 dependencies를 읽어서 사용 중인 프레임워크와 라이브러리를 정확히 파악한다. 버전도 함께 기록한다 — 기획 시 해당 버전에서 지원하는 기능인지 확인하는 데 쓰인다.
+
+### Step 2: 화면/라우트 목록 파악
+
+사용자에게 노출되는 화면 구조를 파악한다. 프레임워크에 따라 탐색 방법이 다르다.
+
+**Next.js (Pages Router):**
+```
+Glob: src/pages/**/*.tsx, pages/**/*.tsx
+```
+→ 파일 경로가 곧 라우트다. `[id].tsx`는 동적 라우트.
+
+**Next.js (App Router):**
+```
+Glob: src/app/**/page.tsx, app/**/page.tsx
+```
+→ `page.tsx`가 있는 폴더 경로가 라우트.
+
+**React (React Router 등):**
+```
+Grep: Route, path=, createBrowserRouter
+Glob: src/pages/**/*.tsx, src/views/**/*.tsx
+```
+→ 라우터 설정 파일에서 경로 매핑을 추출.
+
+**Vue / Nuxt:**
+```
+Glob: pages/**/*.vue, src/views/**/*.vue
+```
+
+**백엔드 전용 (Express, FastAPI 등):**
+→ 화면 없음. Step 3으로 직접 이동.
+
+각 화면에 대해 파악할 것:
+- 라우트 경로 (예: `/login`, `/products/:id`)
+- 해당 화면의 주요 컴포넌트
+- 사용하는 데이터 (어떤 API를 호출하는지)
+
+### Step 3: API 엔드포인트 목록 파악
+
+서버 사이드 API를 탐색한다.
+
+```
+Glob: **/routes/**/*.ts, **/routes/**/*.js, **/api/**/*.ts
+Grep: router\.(get|post|put|delete|patch), app\.(get|post|put|delete|patch)
+Grep: @Get|@Post|@Put|@Delete|@Patch
+```
+
+각 엔드포인트에 대해 파악할 것:
+- HTTP Method + Path
+- 간단한 역할 설명
+- 인증 필요 여부 (미들웨어로 보호되고 있는지)
+
+Next.js API Routes(`pages/api/`, `app/api/`)도 별도로 탐색한다.
+
+### Step 4: DB 스키마/모델 파악
+
+데이터 모델 구조를 파악한다.
+
+```
+Glob: **/prisma/schema.prisma
+Glob: **/models/**/*.ts, **/models/**/*.py, **/entities/**/*.ts
+Grep: @Entity, @Table, @model, class.*Model
+```
+
+파악할 내용:
+- 모델 이름과 주요 필드
+- 모델 간 관계 (1:N, N:M 등)
+- 특이사항 (soft delete, timestamp, enum 등)
+
+ORM을 사용하지 않는 경우 migration 파일이나 SQL 스키마를 확인한다:
+```
+Glob: **/migrations/**/*.sql, **/schema.sql
+```
+
+### Step 5: 기존 패턴 분석
+
+코드베이스에서 반복되는 패턴을 파악한다. 기획안이 이 패턴을 따라야 구현 팀의 생산성이 높아진다.
+
+확인할 패턴:
+- **상태 관리**: Redux, Zustand, React Context, useState 등
+- **API 호출 방식**: axios, fetch, React Query, SWR 등
+- **인증 방식**: JWT, Session, NextAuth, Passport 등
+- **에러 처리**: 공통 에러 핸들러가 있는지, 에러 바운더리 사용 여부
+- **스타일링**: CSS Modules, Tailwind, styled-components, 바닐라 CSS 등
+
+```
+Grep: useQuery|useSWR|axios|fetch\(
+Grep: useAuth|getSession|getServerSession|passport
+Grep: import.*\.module\.|tailwind|styled
+```
+
+---
+
+## 출력 형식
+
+탐색이 완료되면 아래 형식으로 결과를 정리하여 반환한다. 이 결과는 기획자가 기획안 작성 시 참고하는 내부 문서이므로 파일로 저장하지 않는다.
+
+```markdown
+# 기존 서비스 현황
+
+## 기술 스택
+
+| 영역 | 기술 | 버전 |
+|------|------|------|
+| FE | (예: React 18, Next.js 14) | (예: 18.2.0, 14.1.0) |
+| BE | (예: Express 4) | (예: 4.18.2) |
+| DB | (예: PostgreSQL + Prisma) | (예: Prisma 5.9.1) |
+| Infra | (예: Docker, GitHub Actions) | - |
+| 스타일링 | (예: Tailwind CSS) | (예: 3.4.1) |
+| 상태관리 | (예: Zustand) | (예: 4.5.0) |
+
+## 기존 화면 목록
+
+| 라우트 | 화면명 | 주요 기능 |
+|--------|--------|-----------|
+| / | 홈 | 랜딩 페이지, 상품 목록 표시 |
+| /login | 로그인 | 이메일/비밀번호 인증 |
+| /products/:id | 상품 상세 | 상품 정보 표시, 장바구니 추가 |
+
+## 기존 API 목록
+
+| Method | Path | 설명 | 인증 |
+|--------|------|------|------|
+| GET | /api/products | 상품 목록 조회 | X |
+| POST | /api/orders | 주문 생성 | O |
+
+## 기존 DB 모델
+
+| 모델 | 주요 필드 | 관계 |
+|------|-----------|------|
+| User | id, email, name, role | Order(1:N) |
+| Product | id, name, price, stock | OrderItem(1:N) |
+
+## 기존 코드 패턴
+
+- **API 호출**: (예: axios 인스턴스 + 커스텀 훅 패턴)
+- **인증**: (예: NextAuth + JWT 전략)
+- **에러 처리**: (예: 공통 에러 핸들러 없음, 컴포넌트별 try-catch)
+- **스타일링**: (예: 바닐라 CSS, globals.css 단일 파일)
+
+## 기획 시 주의사항
+
+- (기존 기능과 충돌할 수 있는 부분)
+- (재사용 가능한 기존 컴포넌트/API)
+- (기존 패턴을 따라야 하는 이유와 구체적 사항)
+- (기존 코드에서 발견된 제약사항 — 예: 인증 미구현)
+```
+
+---
+
+## 탐색 품질 체크리스트
+
+결과를 반환하기 전에 점검한다:
+
+- [ ] 화면 목록에 누락된 페이지가 없는가?
+- [ ] API 목록에 누락된 엔드포인트가 없는가?
+- [ ] DB 모델 간 관계가 정확한가?
+- [ ] 코드 패턴 분석이 실제 코드에 근거하는가?
+- [ ] 주의사항이 기획에 실질적으로 도움이 되는 내용인가?