db-schema-review

name	db-schema-review
description	명명 규칙, 정규화, 제약, 삭제 정책 관점에서 스키마를 리뷰한다
argument-hint	스키마 정의 파일 경로 또는 마이그레이션 디렉터리
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

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

실행 모드

• 간단 모드(기본값): 절차 1(명명 규칙), 3(제약 설계), 6(종합 평가)만 수행하고, 주요 문제점과 개선안을 반환한다.
• 상세 모드: 인자에 --detailed가 포함되면 6개 절차 전체를 수행하고, 성능 고려 및 삭제 정책까지 포함한 종합 리뷰를 반환한다.

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

목적

데이터베이스 스키마를 명명 규칙, 정규화 수준, 제약 설계, 삭제 정책의 4개 축으로 종합 리뷰한다.
데이터 정합성, 유지보수성, 확장성을 확보하기 위한 개선 사항을 체계적으로 정리한다.

입력

• 스키마 정의 파일 (schema.sql, schema.rb, models.py, schema.prisma 등)
• 마이그레이션 파일 집합
• ORM 모델 정의 파일
• ER 다이어그램 정의 파일 (선택)

절차

1. 명명 규칙 검사

1-1. 테이블명 명명 규칙 확인 (단수/복수형 통일, snake_case 사용 여부)
1-2. 컬럼명 명명 규칙 확인 (접두어·접미어 일관성)
1-3. 기본키·외래키 명명 패턴 확인 (id, table_id 통일 여부)
1-4. 인덱스명 명명 규칙 확인 (idx_table_column 패턴 등)
1-5. 예약어 충돌 탐지 (order, user, group, key 등)
1-6. 약어 사용 일관성 확인 (num vs number, qty vs quantity 등)
1-7. Boolean 컬럼 명명 확인 (is_, has_, can_ 접두어 사용 여부)

2. 정규화 수준 평가

2-1. 제1정규형 위반 탐지 (콤마 구분 값, JSON 배열에 다중 값 저장 등)
2-2. 제2정규형 위반 탐지 (부분 함수 종속)
2-3. 제3정규형 위반 탐지 (이행적 함수 종속)
2-4. 의도적 비정규화 영역 식별 및 타당성 평가
2-5. 비정규화 시 데이터 동기화 메커니즘 확인
2-6. 다대다 관계의 중간 테이블 설계 평가

3. 제약 설계 검사

3-1. 전체 테이블의 기본키 설계 확인 (자연키 vs 대리키)
3-2. NOT NULL 제약 적절성 평가 (필수 컬럼에 적용되었는지)
3-3. UNIQUE 제약 필요 지점 확인 (비즈니스 키의 유일성 보장 여부)
3-4. 외래키 제약 설정 여부 확인 (관계 컬럼에 제약이 존재하는지)
3-5. CHECK 제약 활용 여부 확인 (값 범위 제한, ENUM 대체 등)
3-6. DEFAULT 값 설정 확인 (타임스탬프, 상태 초기값 등)
3-7. 컬럼 데이터 타입 적절성 평가 (VARCHAR 길이, 숫자형 정밀도 등)
3-8. NULL 허용 컬럼의 타당성 검토 (실제로 NULL이 필요한지)

4. 삭제 정책 평가

4-1. 물리 삭제와 논리 삭제 구분 사용 여부 확인
4-2. 논리 삭제 컬럼 (deleted_at, is_deleted) 설계 평가
4-3. 논리 삭제 시 UNIQUE 제약과의 충돌 여부 확인
4-4. CASCADE DELETE 설정 및 영향 범위 분석
4-5. 고아 레코드(부모 없는 자식 데이터) 발생 가능성 평가
4-6. 데이터 보존 기간 정책 및 아카이빙 전략 확인
4-7. 개인정보 삭제 요구(GDPR 등) 대응 여부 확인

5. 확장성과 성능 고려

5-1. 테이블 분할 필요성 평가 (수평 분할, 수직 분할)
5-2. 향후 요구사항 변경에 대한 유연성 평가
5-3. 타임스탬프 컬럼 (created_at, updated_at) 설계 확인
5-4. 폴리모픽 관계 설계의 적절성 평가
5-5. ENUM 타입 vs 참조 테이블 사용 구분 검토

6. 종합 평가 작성

6-1. 각 검사 축별 점수 산정 (A / B / C / D)
6-2. 우선순위 기반 개선 제안 작성
6-3. 전체 스키마의 건전성 종합 판정

출력 포맷

# 스키마 리뷰: [프로젝트 / 데이터베이스명]

## 종합 평가
| 검사 축 | 평가 | 주요 지적 사항 |
|----------|------|----------------|
| 명명 규칙 | A / B / C / D | [요약] |
| 정규화 | A / B / C / D | [요약] |
| 제약 설계 | A / B / C / D | [요약] |
| 삭제 정책 | A / B / C / D | [요약] |
| 확장성 | A / B / C / D | [요약] |

**평가 기준**:  
A = 우수 / B = 양호(경미한 개선 권장) / C = 개선 필요 / D = 심각한 문제

## 명명 규칙

### 불일치 사례
| 위치 | 현재 | 권장 | 사유 |
|------|------|------|------|
| `table_name.columnName` | camelCase | `column_name` (snake_case) | 프로젝트 규칙과 불일치 |
| `tbl_users` | 접두어 사용 | `users` | 불필요한 접두어는 가독성 저하 |

### 예약어 충돌
| 테이블/컬럼 | 예약어 | 권장 대체명 |
|-------------|--------|------------|
| `order` | SQL 예약어 | `orders` / `purchase_order` |

## 정규화

### 정규화 위반
| 테이블 | 컬럼 | 위반 유형 | 설명 | 개선안 |
|----------|--------|-----------|------|--------|
| `users` | `tags` | 제1정규형 | 콤마 구분 다중 값 저장 | `user_tags` 중간 테이블로 분리 |

### 의도적 비정규화
| 테이블 | 컬럼 | 목적 | 동기화 방식 | 평가 |
|----------|--------|------|------------|------|
| `orders` | `user_name` | 조인 비용 절감 | 트리거 | 타당 / 재검토 필요 |

## 제약 설계

### 부족한 제약
| 테이블 | 컬럼 | 권장 제약 | 사유 |
|----------|--------|------------|------|
| `users` | `email` | UNIQUE | 비즈니스 키 유일성 필요 |
| `orders` | `status` | CHECK | 허용 값 범위 제한 필요 |
| `items` | `category_id` | FOREIGN KEY | 참조 무결성 보장 필요 |

### 부적절한 데이터 타입
| 테이블 | 컬럼 | 현재 | 권장 | 사유 |
|----------|--------|--------|--------|------|
| `products` | `price` | FLOAT | DECIMAL(10,2) | 금액 컬럼에 부동소수점은 부적절 |

## 삭제 정책

### 현재 삭제 방식
| 테이블 | 방식 | 구현 | 문제점 |
|----------|--------|--------|----------|
| `users` | 논리 삭제 | `deleted_at` | UNIQUE 제약과 충돌 가능 |
| `logs` | 물리 삭제 | 없음 | 삭제 정책 미정의 |

### CASCADE 영향 맵

users (DELETE) ├── orders (CASCADE) -- 주문 데이터 연쇄 삭제 │ └── order_items (CASCADE) -- 주문 상세도 연쇄 삭제 └── reviews (SET NULL) -- 리뷰는 남고 user_id는 NULL 처리

## 개선 제안 (우선순위순)

### 우선순위: 높음
1. **[테이블명]**: [구체적 개선 내용 및 이유]

### 우선순위: 중간
2. **[테이블명]**: [구체적 개선 내용 및 이유]

### 우선순위: 낮음
3. **[테이블명]**: [구체적 개선 내용 및 이유]

## 권장 액션
- [ ] [즉시 추가해야 할 제약]
- [ ] [명명 규칙 통일 작업]
- [ ] [삭제 정책 수립 및 문서화]

안전 수칙

• 실제 SQL을 실행하지 말 것 — 본 작업은 정적 스키마 리뷰만 수행한다
• 운영 데이터베이스에 접속하지 말 것
• 스키마 파일 및 모델 정의를 수정하지 말 것 — 리뷰 결과 보고만 수행
• 정규화 개선 제안 시 성능 영향도 함께 기술할 것
• 삭제 정책 변경 제안 시 기존 데이터 영향 반드시 경고할 것
• 개인정보 관련 컬럼은 특별히 주의해 보고할 것
• 평가는 객관적 기준 기반으로 수행하고, 추정은 ‘추정’이라고 명시할 것

종료 조건

• 모든 테이블의 명명 규칙이 검사되었을 것
• 정규화 위반 지점이 식별되었을 것
• 제약 설계 부족 사항이 보고되었을 것
• 삭제 정책이 테이블별로 평가되었을 것
• CASCADE 영향 범위가 분석되었을 것
• 우선순위 기반 개선 제안이 작성되었을 것
• 각 검사 축에 평가 점수가 부여되었을 것