# DB Seed Data Plan

> 테스트·검증용 시드 데이터 설계 계획을 수립한다

- Skill: `gaebalai-claude-code-kit-ko/db-seed-data-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/db-seed-data-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/db-seed-data-plan/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gaebalai (https://skillmd.com/u/gaebalai-claude-code-kit-ko)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/gaebalai-claude-code-kit-ko/db-seed-data-plan

---


당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

## 실행 모드

- **간단 모드(기본값)**: 절차 1(스키마 분석), 3(데이터 패턴 설계), 5(스크립트 사양)만 수행하고, 간결한 시드 데이터 계획을 반환한다.
- **상세 모드**: 인자에 `--detailed`가 포함되면 6개 절차 전체를 수행하고, 검증 기준 및 환경별 설계를 포함한 종합 결과를 반환한다.

$ARGUMENTS에 `--detailed`가 포함되지 않은 경우 간단 모드로 실행한다.  
간단 모드에서는 출력 포맷 중 해당 섹션만 출력한다.

## 목적

테스트, 개발, 스테이징 환경에서 사용할 시드 데이터 설계 계획을 수립한다.  
외래키 제약 및 비즈니스 규칙을 만족하면서도, 엣지 케이스를 충분히 포함하는 현실적인 테스트 데이터 세트를 설계한다.  
데이터 입력 순서와 의존 관계를 명확히 하고, 재현 가능한 시드 스크립트 사양을 정의한다.

## 입력

- 스키마 정의 파일 (테이블 구조 및 제약 정보)
- ORM 모델 정의 파일
- 비즈니스 로직 명세 (선택)
- 기존 시드 스크립트 (선택)
- 테스트 요구사항 및 시나리오 (선택)

## 절차

### 1. 스키마 구조 분석

1-1. 전체 테이블의 컬럼 정의, 제약 조건, 데이터 타입 파악  
1-2. 테이블 간 외래키 의존 관계를 의존 그래프로 정리  
1-3. NOT NULL / UNIQUE / CHECK 제약 목록화  
1-4. ENUM 타입 또는 상태 컬럼의 허용 값 나열  
1-5. 자동 생성 컬럼(AUTO_INCREMENT, SERIAL, UUID, 타임스탬프 등) 식별  

### 2. 데이터 입력 순서 결정

2-1. 외래키 의존 관계 기반 위상 정렬 순서 결정  
2-2. 순환 참조 발생 시 해결 전략 수립 (일시적 FK 비활성화 또는 NULL 후 업데이트)  
2-3. 마스터 데이터(참조 테이블)와 트랜잭션 데이터 구분  
2-4. 입력 단계를 정의 (Phase 1: 마스터 → Phase 2: 주요 엔티티 → Phase 3: 트랜잭션 → Phase 4: 연관 데이터)  

### 3. 데이터 패턴 설계

3-1. 정상 케이스 데이터 세트 설계 (기본 CRUD 검증용)  
3-2. 경계값 데이터 설계 (최소값, 최대값, 빈 문자열, 최대 길이 문자열 등)  
3-3. 엣지 케이스 설계:
  - NULL 허용 컬럼의 NULL 케이스
  - 논리 삭제된 레코드
  - 상태 전이 전체 패턴
  - 날짜 경계 (연말/연초, 윤년, 타임존 경계)
3-4. 관계 검증 데이터 설계:
  - 1:1 / 1:N / N:M 패턴
  - 자식 레코드 없는 부모 레코드
  - 고아 레코드 케이스
3-5. 성능 테스트용 데이터 규모 정의  
3-6. 국제화 테스트 데이터 설계 (다국어, 멀티바이트, 이모지 등)  

### 4. 데이터 값 설계 방침

4-1. 실제 개인정보와 유사하지 않은 안전한 더미 데이터 방침 수립  
4-2. UNIQUE 제약을 만족하기 위한 네이밍 규칙 정의 (`test_user_001` 등)  
4-3. 날짜 데이터 기준일과 오프셋 전략 결정  
4-4. 금액·수량 데이터의 현실적 범위 설정  
4-5. Factory 패턴 활용 방침 정의  
4-6. 랜덤 데이터와 고정 데이터의 사용 구분 정의  

### 5. 시드 스크립트 사양 수립

5-1. 멱등성(여러 번 실행해도 동일 결과) 보장 설계  
5-2. 환경별 데이터 세트 분리 설계 (dev / test / staging)  
5-3. 데이터 초기화 절차 정의 (TRUNCATE 후 재입력 등)  
5-4. 시드 데이터 버전 관리 방침 수립  
5-5. 대량 데이터 입력 시 배치 처리 전략 설계  
5-6. 실행 로그 및 검증 절차 정의  

### 6. 검증 기준 수립

6-1. 시드 입력 후 정합성 체크 쿼리 설계  
6-2. 외래키 제약 위반 탐지 쿼리 준비  
6-3. 필수 데이터 존재 여부 확인 쿼리 준비  
6-4. 기대 레코드 수 정의  

## 출력 포맷

```markdown
# 시드 데이터 설계 계획: [대상 스키마 / 프로젝트명]

## 설계 요약
| 항목 | 내용 |
|------|------|
| 대상 테이블 수 | N 개 |
| 총 레코드 수 (개발 환경) | 약 N 건 |
| 총 레코드 수 (성능 테스트) | 약 N 건 |
| 입력 단계 수 | N 단계 |
| 멱등성 | 보장 / 미보장 |

## 테이블 의존 관계 그래프
```
Phase 1 (마스터 데이터):
  categories (의존 없음)
  roles (의존 없음)

Phase 2 (주요 엔티티):
  users → roles
  products → categories

Phase 3 (트랜잭션 데이터):
  orders → users
  order_items → orders, products

Phase 4 (연관 데이터):
  reviews → users, products
```

## 테이블별 데이터 설계

### `users` 테이블
| # | 목적 | name | email | role_id | status | deleted_at |
|---|------|------|-------|---------|--------|------------|
| 1 | 정상: 관리자 | 테스트관리자 | admin@test.local | 1 | active | NULL |
| 2 | 정상: 일반 | 테스트사용자 | user01@test.local | 2 | active | NULL |
| 3 | 엣지: 정지 | 정지사용자 | suspended@test.local | 2 | suspended | NULL |
| 4 | 엣지: 논리삭제 | 삭제사용자 | deleted@test.local | 2 | active | 2024-01-01 |
| 5 | 경계값: 최대길이 | 가...(255자) | long@test.local | 2 | active | NULL |
| 6 | 국제화: 이모지 | 😊사용자 | intl@test.local | 2 | active | NULL |

### `orders` 테이블
| # | 목적 | user_id | total | status | created_at |
|---|------|---------|-------|--------|------------|
| 1 | 정상 | 2 | 1500 | completed | 기준일 |
| 2 | 엣지: 0원 | 2 | 0 | completed | 기준일-1일 |
| 3 | 엣지: 미완료 | 2 | 3000 | pending | 기준일 |
| 4 | 엣지: 취소 | 3 | 500 | cancelled | 기준일-7일 |

## 데이터 패턴 커버리지 표
| 패턴 | 대상 테이블 | 레코드 | 목적 |
|------|--------------|--------|------|
| NULL 값 | users | #6 | NULL 허용 동작 확인 |
| 논리 삭제 | users | #4 | 삭제 필터 검증 |
| 상태 전이 | orders | #1-#4 | 전체 상태 패턴 검증 |
| 경계값 | users | #5 | VARCHAR 최대 길이 확인 |
| 고아 데이터 | - | - | FK 제약으로 방지 |

## 데이터 값 설계 방침
| 항목 | 방침 |
|------|------|
| 이메일 | `*@test.local` 도메인 사용 |
| 전화번호 | 테스트 전용 번호 형식 사용 |
| 주소 | 명확한 더미 주소 사용 |
| 날짜 | 기준일 `2024-06-01` 기준 상대값 |
| 금액 | 100~100000 범위 |

## 입력 스크립트 사양

### 멱등성 구현 방식
```sql
-- UPSERT 패턴(PostgreSQL)
INSERT INTO users (id, name, email) VALUES (1, '테스트관리자', 'admin@test.local')
ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, email = EXCLUDED.email;

-- REPLACE 패턴(MySQL)
REPLACE INTO users (id, name, email) VALUES (1, '테스트관리자', 'admin@test.local');
```

### 환경별 데이터 세트
| 환경      | 데이터 규모          | 특징        |
| ------- | --------------- | --------- |
| dev     | 최소 (5~10건/테이블)  | 기본 동작 검증  |
| test    | 중간 (10~20건/테이블) | 엣지 케이스 포함 |
| staging | 대규모 (1000건 이상)  | 성능 검증 포함  |

## 입력 후 검증 쿼리
```sql
-- 테이블별 건수 확인
SELECT 'users' AS table_name, COUNT(*) FROM users
UNION ALL
SELECT 'orders', COUNT(*) FROM orders;

-- FK 무결성 확인
SELECT o.id
FROM orders o
LEFT JOIN users u ON o.user_id = u.id
WHERE u.id IS NULL;

-- 필수 마스터 데이터 존재 확인
SELECT * FROM roles
WHERE id NOT IN (SELECT DISTINCT role_id FROM users);
```
```

## 안전 수칙

- **실제 SQL을 실행하지 말 것** — 본 작업은 설계 계획 수립만 수행  
- **운영 데이터베이스에 접속하지 말 것**  
- **실존 개인정보를 사용하지 말 것** — 모든 데이터는 명확한 더미 데이터여야 함  
- **실존 이메일·도메인 사용 금지** — `@test.local` 등 사용  
- **실존 전화번호 사용 금지** — 테스트 전용 형식 사용  
- **운영 데이터 복제 금지** — 개인정보 유출 위험  
- **비밀번호 하드코딩 금지** — 해시값 사용  
- **신용카드 등 민감정보 포함 금지**

---

## 종료 조건

- 전체 테이블 의존 관계가 정리되었을 것  
- 입력 순서가 위상 정렬로 정의되었을 것  
- 정상·경계·엣지 케이스 데이터가 설계되었을 것  
- 데이터 값 설계 방침이 명확히 정의되었을 것  
- 멱등성을 보장하는 스크립트 사양이 수립되었을 것  
- 환경별 데이터 세트가 분리 설계되었을 것  
- 입력 후 검증 쿼리가 준비되었을 것  
- 개인정보와 유사하지 않은 더미 데이터 정책이 확인되었을 것