# MD 기반 MES/ERP 기획서 자동화 파이프라인 검토서

> **작성일**: 2026-02-10
> **작성**: 류병철 / Claude Code
> **목적**: 회의록/인터뷰 → MD → PPTX → 프론트엔드 자동화 파이프라인의 실현 가능성 검증 및 팀 검토
> **PoC 대상**: 주일기업 MES (자동방화셔터 시공 관리 시스템)

---

## 1. 배경 및 목적

### 1.1 해결하려는 문제

MES/ERP 프로젝트에서 반복되는 비효율:

| 단계 | 현재 문제 |
|------|----------|
| 요구사항 수집 | 인터뷰/회의 내용이 구두로만 전달, 누락 빈번 |
| 기획서 작성 | 수작업 PPTX 제작에 1~2주 소요 |
| 고객 확인 | 기획서 수정 → PPTX 재작업의 반복 |
| 개발 착수 | 기획서와 실제 구현 간 해석 차이 발생 |
| 변경 관리 | 기획서-코드 간 동기화 안 됨 |

### 1.2 제안 개념

**MD 파일을 Single Source of Truth로** 사용하여, 하나의 문서에서 기획서(PPTX)와 코드(프론트엔드)를 모두 파생시키는 자동화 파이프라인.

```
인터뷰/녹음 → MD 명세서 → PPTX 기획서 (고객 확인용)
                       → 프론트엔드 코드 (개발용)
                       → API 구조 설계 (백엔드용)
```

---

## 2. 파이프라인 설계

### 2.1 전체 흐름

```
┌─────────────────────────────────────────────────────────────────┐
│  1단계: 요구사항 수집                                             │
│  인터뷰 / 현장 방문 / 녹음 → 녹취록 + 원본 자료                    │
└──────────────────────────┬──────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  2단계: MD 명세서 작성                                            │
│  녹취록 + 업종 체크리스트 → 구조화된 MD 파일                        │
│  (화면 구성, 데이터 모델, 상태 머신, API 엔드포인트 포함)             │
└──────────────────────────┬──────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  3단계: PPTX 기획서 자동 생성                                      │
│  MD → Claude → python-pptx 스크립트 → 와이어프레임 PPTX             │
│  고객과 화면 단위로 검토 및 승인                                     │
└──────────────────────────┬──────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  4단계: 프론트엔드 + API 구조 설계                                  │
│  승인된 MD + 기존 컴포넌트 라이브러리 → 화면 코드 생성                │
│  Mock API로 즉시 동작 가능한 프로토타입 구성                         │
└──────────────────────────┬──────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  5단계: 프로토타입 테스트                                          │
│  Mock API 기반 프로토타입으로 고객/내부 테스트                       │
│  피드백 → MD 역반영 → 영향 범위 파악                                │
└──────────────────────────┬──────────────────────────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  6단계: 실 API 연동 + 최종 검수                                    │
│  Mock → 실제 API 교체 → 통합 테스트 → 고객 최종 검수                │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 각 단계 상세

#### 1단계: 요구사항 수집

| 항목 | 내용 |
|------|------|
| 입력 | 고객 인터뷰, 현장 녹음, 기존 시스템 스크린샷, 업무 매뉴얼 |
| 출력 | 녹취록 + 수집 자료 원본 |
| 담당 | 기획자 / PM |
| 도구 | 녹음 앱, 스크린샷 도구 |

#### 2단계: MD 명세서 작성

| 항목 | 내용 |
|------|------|
| 입력 | 녹취록 + 업종별 체크리스트 |
| 출력 | 구조화된 MD 파일 (단일 파일) |
| 담당 | 기획자 + Claude 보조 |
| 도구 | Claude Code, 텍스트 에디터 |

**MD에 포함되어야 할 섹션:**
- 시스템 개요 (목적, 모듈 구성)
- 역할/권한 시스템
- 화면별 상세 명세 (레이아웃, 컴포넌트, 데이터)
- 상태 머신 (비즈니스 흐름)
- 데이터 모델
- API 엔드포인트 목록
- PPTX 레이아웃 규격 (색상, 치수, 컴포넌트 정의)

#### 3단계: PPTX 자동 생성

| 항목 | 내용 |
|------|------|
| 입력 | 2단계 MD 파일 |
| 출력 | 와이어프레임 기반 PPTX (python-pptx) |
| 담당 | Claude Code (자동) |
| 도구 | Python + python-pptx |

#### 4단계: 프론트엔드 + API 설계

| 항목 | 내용 |
|------|------|
| 입력 | 승인된 MD + 기존 컴포넌트 라이브러리 |
| 출력 | 동작하는 프론트엔드 코드 + Mock API |
| 담당 | Claude Code + 개발자 검수 |
| 도구 | Next.js, 기존 organisms/molecules 컴포넌트 |

#### 5단계: 프로토타입 테스트

| 항목 | 내용 |
|------|------|
| 입력 | Mock API 기반 프로토타입 |
| 출력 | 피드백 목록 + MD 수정 사항 |
| 담당 | 고객 + QA + 기획자 |
| 도구 | 브라우저, 피드백 시트 |

#### 6단계: 실 API 연동 + 검수

| 항목 | 내용 |
|------|------|
| 입력 | 테스트 완료된 프론트 + 백엔드 API |
| 출력 | 운영 배포 가능한 시스템 |
| 담당 | 프론트엔드 + 백엔드 개발자 |
| 도구 | Laravel API, Next.js |

---

## 3. PoC 검증 결과 (주일기업 MES)

### 3.1 검증 범위

주일기업 MES(자동방화셔터 시공 관리 시스템)를 대상으로 **2단계 → 3단계** 구간을 검증.

```
실제 동작하는 화면 스크린샷 22장
    → 역기획서 MD 작성 (역기획서_주일기업MES.md)
    → python-pptx 스크립트 생성 (generate_pptx.py, 약 71KB)
    → PPTX 기획서 자동 생성 (22슬라이드, 102KB)
    → PPTX 내용을 독립 MD 명세서로 변환 (주일기업_MES_PPTX_명세서.md, 891줄)
    → 새 세션에서 MD만으로 PPTX 재생성 시도 (진행 중)
```

### 3.2 검증된 사항

| 검증 항목 | 결과 | 비고 |
|-----------|------|------|
| MD → Python 스크립트 생성 | 성공 | Claude가 MD를 읽고 python-pptx 코드 자동 생성 |
| 와이어프레임 PPTX 출력 | 성공 | 도형 기반 UI를 22슬라이드로 렌더링 |
| PPTX → MD 역변환 | 성공 | 891줄 명세서로 구조화 |
| MD만으로 PPTX 재생성 (새 세션) | 진행 중 | 이전 컨텍스트 없이 MD만으로 동일 품질 생성 가능한지 검증 |

### 3.3 생성된 산출물

```
~/Desktop/역기획서_스크린샷/
├── 01~22_*.png                          # 원본 스크린샷 22장
└── 역기획서_주일기업MES.md               # 역기획서 (439줄)

~/Desktop/주일기업_MES_기획서/
├── generate_pptx.py                      # PPTX 생성 스크립트 (71KB)
├── 주일기업_MES_Storyboard_D1.0_260210.pptx  # 생성된 PPTX (102KB)
├── preview/                              # 슬라이드 미리보기 PNG 17장
└── preview_markers.py                    # 마커 미리보기 스크립트

~/Desktop/주일 md to pptx test/
└── 주일기업_MES_PPTX_명세서.md           # 독립 MD 명세서 (891줄)
```

---

## 4. 비판적 분석

### 4.1 강점

| 강점 | 설명 |
|------|------|
| MD 중심 일관성 | 하나의 문서에서 기획서와 코드가 파생되므로 "기획서와 코드가 다른" 문제 원천 차단 |
| 기획서 작업 시간 단축 | 수작업 1~2주 → MD 작성 후 자동 생성으로 수 시간 내 완료 가능 |
| 기존 자산 재활용 | SAM 프로젝트의 organisms/molecules 컴포넌트를 그대로 활용 |
| 반복 가능한 프로세스 | 동일 파이프라인을 다른 고객사에도 적용 가능 |
| Mock-first 개발 | API 완성 전 프로토타입으로 빠른 피드백 가능 |

### 4.2 리스크 및 대응 방안

#### 리스크 1: 1→2단계 정보 손실 (심각도: 높음)

**문제**: 인터뷰/녹음에서 MD로 변환할 때 정보 손실이 가장 큼. MES/ERP 현장에는 "당연히 그렇게 하는" 암묵적 프로세스가 많아 인터뷰에서 언급되지 않는 경우가 빈번함.

**예시**: "납기일 변경 시 관련 공정 전체 재계산", "특정 조건에서만 나타나는 승인 단계" 등

**대응 방안**:
- 업종별 필수 프로세스 체크리스트 사전 준비
- 인터뷰 후 체크리스트 대조 → 누락 항목 2차 확인
- MD 초안을 고객에게 텍스트 레벨로 먼저 검토받는 단계 추가 (2.5단계)

#### 리스크 2: 고객의 와이어프레임 이해도 (심각도: 중간)

**문제**: MES/ERP 사용자는 대부분 비개발자. 정적 와이어프레임만으로는 동적 흐름(상태 전환, 조건부 UI)을 파악하지 못하고, "확인했습니다" 후 프로토타입을 보고 "이게 아닌데요"가 발생.

**대응 방안**:
- PPTX에 상태 머신, 시나리오 흐름을 명시 (PoC에서 이미 적용)
- 3단계와 5단계를 가까이 배치하여 클릭 가능한 프로토타입으로 보완
- 주요 흐름은 슬라이드 여러 장으로 상태 변화를 시각적으로 나열

#### 리스크 3: API 설계 시점 (심각도: 중간)

**문제**: API 구조 설계가 4단계에서 시작되면, 백엔드 제약사항(기존 DB 스키마, 외부 연동)이 프론트 설계를 뒤집을 수 있음.

**대응 방안**:
- 2단계 MD에 데이터 모델 + API 엔드포인트 목록을 포함 (PoC에서 이미 적용)
- 백엔드 개발자가 2단계 MD 리뷰에 참여
- API 제약사항을 3단계 이전에 확인

#### 리스크 4: 변경의 역전파 (심각도: 중간)

**문제**: 5단계 테스트에서 변경 요청 발생 시, MD → PPTX → 코드 전체가 연쇄 수정되어야 함. 현재 파이프라인은 단방향이라 역방향 반영 체계가 없음.

**대응 방안**:
- MD 버전 관리 (Git)
- 변경 요청 시 MD 먼저 수정 → PPTX/코드 재생성 순서 준수
- 변경 영향 범위를 MD 섹션 단위로 추적

#### 리스크 5: 동시 다중 프로젝트 (심각도: 낮음, 현재)

**문제**: 1~2단계(인터뷰 → MD)는 자동화가 어려워, 동시에 3~5개 고객 프로젝트를 진행하면 병목 발생.

**대응 방안**:
- 업종별 MD 템플릿 사전 구축으로 2단계 작업량 감소
- 3단계 이후는 자동화 비율이 높으므로 병목은 1~2단계에 집중 → 기획 인력 확보

---

## 5. 개선된 파이프라인 (제안)

기존 6단계에 검증 게이트를 추가한 버전:

```
1단계  인터뷰/녹음 → 녹취록 + 원본 자료
          │
2단계  녹취록 + 업종 체크리스트 → MD 명세서 (데이터 모델 + API 포함)
          │
  ┌───── 2.5단계  고객 + 백엔드 개발자 MD 텍스트 리뷰 ──────┐
  │       (화면 만들기 전에 내용의 정확성 먼저 확인)            │
  │       승인 ✓                    수정 요청 → 2단계로 복귀   │
  └───────┬───────────────────────────────────────────────────┘
          │
3단계  MD → PPTX 와이어프레임 자동 생성
          │
  ┌───── 3.5단계  고객 화면 검토 (서명) ──────────────────────┐
  │       승인 ✓                    수정 요청 → MD 수정 → 재생성│
  └───────┬───────────────────────────────────────────────────┘
          │
4단계  MD + 기존 컴포넌트 → 프론트엔드 + Mock API 프로토타입
          │
5단계  프로토타입 테스트 (고객 + 내부)
          │
  ┌───── 5.5단계  피드백 반영 ────────────────────────────────┐
  │       피드백 → MD 수정 → 영향 범위 확인 → 코드 반영         │
  │       완료 ✓                                              │
  └───────┬───────────────────────────────────────────────────┘
          │
6단계  Mock → 실 API 교체 → 통합 테스트 → 최종 검수
```

---

## 6. 필요 사전 작업

파이프라인을 실전에 적용하기 위해 준비해야 할 것:

| 항목 | 설명 | 우선순위 |
|------|------|----------|
| MD 템플릿 표준화 | PPTX 레이아웃 규격, 색상, 컴포넌트 정의를 포함한 MD 작성 가이드 | 높음 |
| 업종별 체크리스트 | MES/ERP 업종별 필수 프로세스 목록 (제조, 시공, 물류 등) | 높음 |
| 컴포넌트 라이브러리 정리 | 4단계에서 활용할 organisms/molecules 카탈로그 | 중간 |
| Mock API 규격 | 프론트 프로토타입에서 사용할 Mock 데이터 구조 표준 | 중간 |
| 변경 관리 프로세스 | MD 수정 → 영향 범위 파악 → 재생성 절차 문서화 | 낮음 (초기) |

---

## 7. 검토 요청 사항

팀원들에게 확인받고 싶은 사항:

1. **기획자**: 1→2단계에서 인터뷰 내용을 MD로 구조화하는 과정이 현실적인가? 어떤 보조 도구가 필요한가?
2. **프론트엔드 개발자**: 4단계에서 MD 명세서만으로 화면 구현이 가능한 수준인가? 기존 컴포넌트 재활용 범위는?
3. **백엔드 개발자**: 2단계 MD에 포함된 데이터 모델/API 명세가 백엔드 설계에 충분한가? 추가로 필요한 정보는?
4. **PM**: 이 파이프라인의 단계별 소요 시간 예측이 가능한가? 고객 커뮤니케이션 포인트는 적절한가?

---

## 8. 다음 단계

- [ ] MD만으로 PPTX 재생성 PoC 완료 (현재 진행 중)
- [ ] 팀 검토 미팅 일정 확정
- [ ] 검토 결과 반영하여 파이프라인 확정
- [ ] MD 템플릿 표준 초안 작성
- [ ] 실 고객 프로젝트 파일럿 적용 대상 선정
