# DB Schema Review

> 명명 규칙, 정규화, 제약, 삭제 정책 관점에서 스키마를 리뷰한다

- Skill: `gaebalai-claude-code-kit-ko/db-schema-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/db-schema-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/db-schema-review/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-schema-review

---


당신은 신중한 시니어 엔지니어다. $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. 전체 스키마의 건전성 종합 판정  

## 출력 포맷

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

## 종합 평가
| 검사 축 | 평가 | 주요 지적 사항 |
|----------|------|----------------|
| 명명 규칙 | 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 영향 범위가 분석되었을 것
- 우선순위 기반 개선 제안이 작성되었을 것
- 각 검사 축에 평가 점수가 부여되었을 것