Claude code로 콘텐츠 정제 및 등록 자동화: 파일명 변환부터 웹 등록까지

# 발음연습 프로그램 — 파일명 영문 변환 에이전트

## 프로젝트 개요

한글 발음연습 프로그램의 이미지/오디오 파일을 영문 파일명으로 변환하고,
메타데이터와 함께 최종 매핑 테이블을 생성한다.

## 프로젝트 구조

```
RESEARCH_AGENT/
├── audio/                ← 한글 오디오 원본 ({단어}_s.mp3, _m.mp3, _f.mp3)
├── images/               ← 한글 이미지 원본 ({단어}.jpeg, {단어}_01.jpeg)
├── words_lists/
├── practice-words.txt    ← 전체 단어 목록
├── ㄱ-words-info.txt     ← 음소별 메타데이터 (탭 구분 TSV, 8개 파일)
├── ㄲ-words-info.txt
├── ㅅ-words-info.txt
├── ㅆ-words-info.txt
├── ㅈ-words-info.txt
├── ㅉ-words-info.txt
├── ㅊ-words-info.txt
├── ㅋ-words-info.txt
├── utils.py              ← 공통 유틸리티 모듈
└── upload.xlsx
```

## 작업 순서

반드시 아래 순서대로 진행한다. 각 단계 완료 후 사용자 확인을 받는다.

### 1단계: 서브 에이전트 A — 매핑 테이블 생성
- 스킬: `skills/romanize/SKILL.md`
- practice-words.txt에서 단어 목록 읽기
- 각 한글 단어를 로마자 영문명으로 변환
- mapping_table.md 생성
- **사용자 확인**: 로마자 변환 결과가 자연스러운지, 충돌 없는지

### 2단계: 서브 에이전트 B — 이미지 파일 처리
- 스킬: `skills/image-process/SKILL.md`
- mapping_table.md 기준으로 images/ 폴더에서 파일 검색
- 960x960 리사이즈 후 images_en/ 에 영문명으로 저장
- mapping_table.md 상태 열 업데이트
- **사용자 확인**: IMG 상태 확인, 누락 파일 보완

### 3단계: 서브 에이전트 C — 오디오 파일 처리
- 스킬: `skills/audio-process/SKILL.md`
- mapping_table.md 기준으로 audio/ 폴더에서 파일 검색
- audio_en/ 에 영문명으로 복사 저장
- mapping_table.md 상태 열 업데이트
- **사용자 확인**: AUD 상태 확인, 누락 파일 보완

### 4단계: 서브 에이전트 D — 최종 엑셀 정리
- 스킬: `skills/export/SKILL.md`
- 음소별 메타데이터 8개 파일 읽기 (TSV)
- mapping_table.md + 메타데이터 합쳐서 mapping_table.xlsx 생성
- **주의**: 같은 단어가 음소 위치별로 여러 행 존재 가능 (고유키: WORD_TEXT + POSITION1 + POSITION2)
- 여러 행이 같은 파일명을 공유함

### 5단계: 서브 에이전트 E — 웹 관리자 등록
- 스킬: `skills/web-register/SKILL.md`
- test-word-regi 폴더의 파일을 관리자 웹사이트에 등록
- mapping_table.xlsx에서 메타데이터 조회
- Playwright로 브라우저 자동화
- **주의**: 로그인 정보는 환경변수로 관리 (ADMIN_ID, ADMIN_PW)

## 핵심 규칙

### 원본 보존
- 원본 파일(images/, audio/, *.txt)은 절대 수정/삭제하지 않는다
- 영문 파일은 별도 폴더(images_en/, audio_en/)에 저장한다

### 파일명 규칙
- 이미지 1장: `{영문명}.jpeg`
- 이미지 2장: `{영문명}.jpeg` (기본) + `{영문명}_01.jpeg` (추가)
- 오디오: `{영문명}_s.mp3`, `{영문명}_m.mp3`, `{영문명}_f.mp3`

### 에러 처리
- 파일 없음 → 상태에 ❌ 표시, 빈칸으로 둠
- 변환 에러 → 상태에 ⚠️ 표시, error_log.txt에 기록
- 영문명 충돌 → romanize_log.txt에 기록, 숫자 접미사 추가

### 하나씩 처리
- 단어를 하나씩 순서대로 처리한다
- 매 단어 처리 후 mapping_table.md를 즉시 업데이트한다
- 중간 중단 시 이어서 작업할 수 있도록 한다

## 독립 실행 스킬

아래 스킬은 파이프라인(1-5단계)과 별개로 단독 실행된다.

### 단어 분류 (word-classify)
- 스킬: `skills/word-classify/SKILL.md`
- words-all.txt에서 단어 목록 읽기 (목표단어 + 목표발음)
- 목표발음을 음절 분해하여 목표음소(8개) 위치 판별
- words_db_upload.xlsx 생성
- **핵심**: 목표발음 기준 분석, 고유키는 PHONEME + POSITION1 + POSITION2