MODULIZATION PROTOCOL — 모듈화 작업 지시문

목적: 확장성·응집도 향상을 위한 점진적 모듈화 원칙: 가장 작은 단위부터 · 하나씩 · 완전히 독립된 작업으로 · 분할과 정복

⚡ MANDATORY CONSTRAINTS — 작업 전 반드시 숙지

┌──────────────────────────────────────────────────────────────┐
│  ❌ NEVER:  전체 시스템을 한 번에 모듈화 시도                   │
│  ❌ NEVER:  계획서 없이 모듈화 착수                            │
│  ❌ NEVER:  구 코드를 삭제하지 않고 새 구조와 공존              │
│  ❌ NEVER:  기존 동작을 변경하면서 모듈화 진행                  │
│  ❌ NEVER:  grep/패턴 매칭으로 "확인했다" 판단                 │
│  ❌ NEVER:  테스트 없이 이주 단계 완료 선언                    │
│                                                              │
│  ✅ ALWAYS: 전체 프로젝트 전수조사 후 시작                     │
│  ✅ ALWAYS: 가장 급해 보이는 딱 한 가지부터 (작아도 됨)         │
│  ✅ ALWAYS: 계획서 먼저 작성 → 체크하며 진행                   │
│  ✅ ALWAYS: Zero Backward Compatibility — 구 코드 반드시 삭제  │
│  ✅ ALWAYS: Zero Behavioral Change — 100% 동작 보존           │
│  ✅ ALWAYS: 각 이주 단계 후 테스트 100% pass 확인              │
│  ✅ ALWAYS: 완료 후 전체 싱크 + §POST 전수조사                 │
└──────────────────────────────────────────────────────────────┘

STEP 1. PRE-WORK — 작업 시작 전 전수조사

⛔ 아래가 완료되지 않으면 모듈화를 시작하지 마라.

□ 진입점 전부 열거 (API/Event/Cron/CLI/DI)
□ 데이터 흐름 추적 — 진입점에서 종료점까지 모든 분기 끝까지
□ 모듈 간 의존 관계 파악 — 가장 작은 것부터 구조적·마이크로 플로우까지
□ 동적 등록 파악 — Registry/Event Emitter/DI/문자열 디스패치
□ Barrel/Entry point 공개 API 목록 확인
□ 모든 흐름 상세 파악 완료 — thoroughly

STEP 2. 대상 선정

□ 확장성·응집도 관점에서 가장 급해 보이는 딱 한 가지 선정
□ 큰 작업이 아니어도 됨 — 작은 단위도 유효
□ 선정 이유 한 줄 명시 (왜 이것이 먼저인가)

STEP 3. 계획서 작성 (새 md 파일 → task/ 폴더 아래 생성)

□ As-Is 구조 명시 (기존 코드 위치, 의존성, 현재 문제점)
□ To-Be 구조 명시 (새 모듈 경계, 파일/폴더 레이아웃)
□ 시간순 단계별 실행 계획 — 빠짐없이 모두 기술 (thoroughly)
   └─ 각 단계: 무엇을 어디서 어떻게 이주/삭제하는지 상세 기술
□ 각 단계별 롤백 방법
□ 프로젝트 영향도 분석 포함 (상위·하위 의존성)
□ Zero Backward Compatibility 삭제 순서 시간순으로 명시

STEP 4. 실행 — 계획서대로 단계별 진행

4-1. 기존 코드에 특성화 테스트 작성 (현행 동작 캡처)
4-2. 새 모듈 구조 생성 (기존 코드 옆에 신규 구현)
4-3. 소비자를 신규 구조로 이주 (한 번에 하나씩)
     └─ 이주 시 관련 싱크 즉시 동기화:
        · 테스트 임포트·어설션·fixture 현행 경로/시그니처로 업데이트
        · 타입·인터페이스 변경 시 모든 참조 업데이트
        · 상수 이동 시 소비자 임포트 경로 업데이트
4-4. 각 이주 단계 후 테스트 100% pass 확인
4-5. 구 구현 완전 삭제 + 고아 테스트·타입·상수 즉시 삭제

⚠️ 진행 방향: 작은 단위 → 큰 단위 · 간단한 작업 → 복잡한 작업 (분할과 정복) ⚠️ 동작 변경 발견 시 즉시 중단 → 보고 → 지시 대기

STEP 5. POST-WORK — 완료 후 전체 전수조사

⛔ 생략 불가. 전수조사를 직접 수행하라. grep 금지.

▸ 안전성
  □ Dead reference 0 (삭제 코드 참조 없음)
  □ 빌드 0에러 · 정적 분석 0에러
  □ 전체 테스트 100% pass

▸ 연결성 — 실제 코드 1줄씩 추적
  □ 모든 import/export 경로 추적 완료
  □ 동적 연결(Registry/이벤트/DI) 추적 완료
  □ 고아 코드 0

▸ 일관성
  □ 명명 규칙 전체 통일
  □ 계층 구조 일관성 유지
  □ 상수·타입 참조 → 현행 정의
  □ 문서 현행 구조 반영

▸ 전체 싱크 (Full Sync)
  □ 테스트 코드 현행 소스 반영 · 고아 테스트 0 · 누락 테스트 0
  □ 타입·상수·설정 모든 참조 업데이트
  □ 문서(README·ARCHITECTURE·CHANGELOG) 현행 구조 완전 반영

▸ 프로젝트 영향도 분석
  □ 변경 모듈 상위·하위 의존성 전수조사
  □ 작은 의존관계부터 마이크로 플로우까지 끝까지 — thoroughly
  □ 문제 없음 확인. 문제 발견 시 즉시 보고 후 수정.