"AI가 삽질하지 않게 만드는 법" - 이모카님의 5단계 문서화 워크플로우를 명리학 DB 구축에 적용한 후기

단계문서소요시간역할1단계기획 문서반나절~1일"왜" 만드는가2단계콘텐츠 문서반나절~1일데이터 구조 정의3단계PRD수시간"무엇을" 만들지4단계프로젝트 플랜수시간"어떻게" 만들지5단계디자인 가이드수시간시각적 일관성

이모카님의 5단계 문서화 워크플로우를 한바둑 프로젝트에 적용하려고 합니다.

현재 상황:
- 310건의 상담 데이터 (5테이블 구조: profiles, wonkuk, daeun, daeun_groups, sewun)
- 60일주 교육 컨텐츠 720,000자
- 24절기 데이터 2,568건 (1920-2026, KASI 출처)

목표:
- Rails + PostgreSQL 기반 관리 시스템
- 100만건 자동 생성
- Avo 관리자 페이지

5단계 문서 템플릿을 한바둑 맞춤으로 작성해주세요.

# 한바둑 기획 문서

## 왜 만드는가?
- 30년간 축적된 명리학 지식의 디지털 영구 보존
- 4관법 기반 정통 해석 방식의 체계적 문서화
- 상업화된 간편 사주풀이와 차별화된 전문 시스템

## 누가 사용하는가?
| 사용자 | 역할 |
|--------|------|
| 1차: 관리자 | 하민님 - 데이터 입력, 검증, 관리 |
| 2차: 연구자 | 명리학 연구자 - 조회, 분석 |
| 3차: 일반 사용자 | 상담 서비스 (Phase 2 이후) |

## 어떤 가치를 제공하는가?
- 1,123,200개 사주 조합의 완전한 해석 DB
- 4관법(음양관, 간지관, 육신관, 신살관) 기반 전통 방식 보존
- AI 기반 자동 통변 시스템의 기초 데이터

# 한바둑 PRD v1.0

## 제품 비전 한 줄
명리학 전문가가 30년 연구 데이터를 체계적으로 관리하고,
100만건 사주 조합을 AI로 분석할 수 있는 통합 플랫폼

## 핵심 기능 (MVP)
### 필수 기능
- 310건 기존 데이터 PostgreSQL 마이그레이션
- 60일주 교육 컨텐츠 조회/검색
- 24절기 데이터 조회/검색
- Avo 기반 관리자 CRUD
- 100만건 배치 생성

### 제외 기능 (v2 이후) ← 이게 핵심!
- 일반 사용자 회원가입/인증
- 실시간 사주 상담 서비스
- 모바일 앱 (iOS/Android)
- Dify AI 플랫폼 연동

## 사용자 스토리
스토리 1: 관리자가 생년월일과 시간을 입력하면,
시스템이 자동으로 사주팔자, 일주, 오행을 계산한다.

스토리 2: '갑자 일주' 검색 시 해당하는 모든 상담 기록이
페이지네이션되어 표시된다.

## 성공 지표
- 310건 → 1,123,200건 확장 완료
- 검색 응답 시간 < 1초
- 데이터 무결성 100%
- 일일 백업 자동화

# 프로젝트 플랜

## 기술 스택
- 프레임워크: Ruby on Rails 8.0
- 데이터베이스: PostgreSQL 16
- 관리자: Avo (자동 생성 Admin)
- 인증: Devise
- 페이지네이션: Pagy
- 백그라운드 잡: Sidekiq
- 개발 환경: GitHub Codespaces

## Phase별 개발 계획

### Phase 1: 환경 구축 (Day 1-2)
- GitHub Codespaces 시작
- Rails new (PostgreSQL)
- 기본 모델 5개 생성 (profiles, wonkuk, daeun, daeun_groups, sewun)
- 마이그레이션 실행

### Phase 2: 관리자 시스템 (Day 3-4)
- Devise 설치 (관리자 인증)
- Avo 설치 (관리자 페이지)
- Profile 리소스 정의
- CRUD 동작 확인

### Phase 3: 데이터 마이그레이션 (Day 5-6)
- JSON → PostgreSQL 변환 스크립트
- 310건 업로드
- 데이터 무결성 검증
- 60일주 컨텐츠 업로드

### Phase 4: 검색/페이지네이션 (Day 7)
- Pagy 설치
- Ransack 설치 (검색)
- 일주별, 날짜별 검색 구현

### Phase 5: 100만건 생성 (Day 8-9)
- Sidekiq 설치, Redis 설정
- 배치 생성 Job 작성
- 10,000건/배치 실행
- 진행률 모니터링

### Phase 6: 마무리 (Day 10)
- 전체 테스트
- 백업 자동화 설정
- 문서화
```

#### Step 5: AI에게 단계별 지시

**Before (삽질 유발 프롬프트):**
```
명리학 관리 시스템 만들어줘
```
→ 결과: 2.5시간 삽질, 방향 상실, 엉뚱한 기능 추가

**After (이모카 방식 프롬프트):**
```
Ruby on Rails로 명리학 데이터 관리 시스템을 만들려고 합니다.
아래 문서들을 모두 읽고 이해한 후 단계별로 진행하겠습니다.

[첨부 파일]
1. PRD.md - 제품 요구사항
2. 프로젝트플랜.md - 구체적 구현 계획
3. 데이터구조.json - 테이블 스키마

먼저 프로젝트플랜.md의 Phase 1만 진행해주세요:
- Rails 프로젝트 생성 (PostgreSQL 사용)
- 필요한 gem 설치
- 기본 모델 생성

완료되면 다음 Phase로 진행하겠습니다.
```

**Phase 완료 후 이어가는 프롬프트:**
```
Phase 1 완료 확인했습니다.
이제 프로젝트플랜.md의 Phase 2를 진행해주세요.
Devise와 Avo 설치, Profile 리소스 정의까지요.
```

---

### 생성된 결과물

Claude Projects에 저장한 5단계 문서:

| 문서 | 용도 | 분량 |
|------|------|------|
| 기획문서.md | 프로젝트 목적, 나침반 역할 | 1페이지 |
| 콘텐츠문서.md | 데이터 스키마, 4관법 정의 | 3페이지 |
| PRD.md | 기능 요구사항, 범위 한정 | 2페이지 |
| 프로젝트플랜.md | Phase별 계획, AI의 GPS | 4페이지 |
| 디자인가이드.md | 컬러/UI 규칙 | 1페이지 |

---

## 4. 결과와 배운 점

### 배운 점

**1. "AI는 '신'이 아니라 '똑똑한 신입사원'"**

이모카님의 이 비유가 모든 것을 설명합니다. 신입사원에게 "알아서 해봐"라고 하면 안 되듯이, AI에게도 명확한 지시서(문서)가 필요합니다.

**2. PRD에 "제외 기능"을 명시하라**

이게 진짜 핵심입니다. AI가 "이 기능도 추가하면 좋을 것 같아요"라고 제안할 때, "PRD에 없으니까 v2에서"라고 선을 그을 수 있습니다.

**3. Phase별로 쪼개서 진행하라**

이모카님: "Phase 1 완료 후 → Phase 2 진행해줘" 방식으로 단계별 확인이 가능합니다. 한 번에 다 시키면 중간에 꼬입니다.

### 나만의 꿀팁
```
💡 Tip 1: 기획 문서 = 나침반
→ 개발 중 방향 잃을 때 돌아오는 기준점

💡 Tip 2: PRD의 "제외 기능"이 범위를 지킨다
→ AI가 스코프 크립(scope creep) 하는 걸 방지

💡 Tip 3: 프로젝트 플랜 = AI의 GPS
→ "Phase X만 해줘"로 명확한 단계별 진행

💡 Tip 4: 막혔을 때는 문서 참조 요청
→ "프로젝트플랜.md의 Phase 3 다시 확인해줘"
```

### 시행착오

| 실패 | 원인 | 해결 |
|------|------|------|
| Rails 환경 충돌 | Windows + WSL 복잡성 | GitHub Codespaces로 전환 |
| AI가 엉뚱한 기능 추가 | PRD에 범위 미정의 | "제외 기능" 명시 |
| 개발 순서 혼란 | 플랜 없이 한 번에 요청 | Phase별 프로젝트 플랜 |
| 디자인 불일치 | 스타일 규칙 없음 | 디자인 가이드 작성 |

### 도움이 필요한 부분

- 100만건 데이터 생성 시 **Sidekiq + Redis 최적화** 방법
- PostgreSQL **파티셔닝** 전략 (일주별? 연도별?)
- Avo 관리자 페이지 **한글화** 커스터마이징

---

## 5. 앞으로의 계획

이모카님 방식대로 **문서화 1일 + 개발 9일** 일정:
```
Day 1: 문서화 완료 ✅
  - 기획 문서, 콘텐츠 문서, PRD, 프로젝트 플랜, 디자인 가이드

Day 2-3: Phase 1-2
  - 환경 구축 + 관리자 시스템

Day 4-5: Phase 3
  - 310건 데이터 마이그레이션

Day 6: Phase 4
  - 검색 & 페이지네이션

Day 7-8: Phase 5
  - 100만건 배치 생성

Day 9-10: Phase 6
  - 테스트, 백업 자동화, 문서화 마무리

꿀팁효과PRD에 "제외 기능" 명시AI가 범위를 벗어나지 않음Phase는 1-2일 단위로 쪼개기"Phase 1만 해줘"로 명확한 진행사용자 스토리 구체적으로 작성AI가 실제 사용 맥락을 이해함막히면 "문서 다시 확인해줘" 요청AI가 컨텍스트를 재정립함

Week 1
├─ Day 1: 문서화 완료 ✅ (완료)
├─ Day 2-3: Phase 1-2 (환경 구축 + 관리자 시스템)
├─ Day 4-5: Phase 3 (310건 데이터 마이그레이션)
└─ Day 6: Phase 4 (검색 & 페이지네이션)

Week 2
├─ Day 7-8: Phase 5 (100만건 배치 생성)
├─ Day 9: Phase 6 (테스트, 백업 자동화)
└─ Day 10: 문서화 마무리, 배포