UNIVERSAL REFACTORING MASTER DOCUMENT

Scope: All programming languages · All project sizes · Autonomous Agent Compatible Purpose: Stabilization → Modulization → Refactoring → Readability → Structure → Quality → Safety

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

┌─────────────────────────────────────────────────────────────────┐
│  이 문서의 모든 지시는 MANDATORY(필수)입니다. 선택 사항 없음.      │
│                                                                 │
│  ❌ NEVER:  grep/패턴 매칭으로 "확인했다" 판단                    │
│  ❌ NEVER:  가정(assumption) 기반 코드 수정                      │
│  ❌ NEVER:  할루시네이션 — 소스코드를 직접 열어 1줄씩 확인만 인정  │
│  ❌ NEVER:  리팩토링+기능추가 동일 커밋                           │
│  ❌ NEVER:  범위 선언 없이 수정                                  │
│  ❌ NEVER:  과거 코드 구조를 사용 안 하면서 삭제 안 함             │
│  ❌ NEVER:  소스 변경 후 관련 싱크(테스트/문서/타입/상수 등) 누락  │
│                                                                 │
│  ✅ ALWAYS: 작업 전 전체 프로젝트 전수조사 (§0-0)                 │
│  ✅ ALWAYS: 실제 코드 파일 열어 마이크로 추적                     │
│  ✅ ALWAYS: 작업 후 전체 시스템 안전성·연결성·일관성 검증 (§POST)  │
│  ✅ ALWAYS: Zero Backward Compatibility — 구코드 반드시 삭제      │
│  ✅ ALWAYS: Zero Behavioral Change — 100% 동작 보존              │
│  ✅ ALWAYS: 작업 완료 후 전체 싱크 — 아래 항목 빠짐없이 동기화    │
│            · 테스트 코드 (시그니처·임포트·어설션·fixture)         │
│            · 타입 정의 (인터페이스·enum·branded type)            │
│            · 상수/설정 (이동·이름 변경 시 모든 참조 업데이트)      │
│            · 문서 (README·ARCHITECTURE·CHANGELOG·ADR)           │
│            · 임포트/익스포트 경로 (barrel 포함)                   │
│            · 환경 변수·설정 파일 참조                            │
└─────────────────────────────────────────────────────────────────┘

섹션 미리보기

🔴 매 섹션 실행 시 반드시 (MANDATORY EXECUTION RULES):

# 0. thoroughly check! — 피상적 확인 절대 금지
# 1. [PRE]  작업 전 전체 프로젝트 완벽하게 전수조사 (§0-0)
#           작은 의존관계부터 구조적·마이크로 플로우까지 끝까지 확인
#           모든 흐름 상세 파악: 진입점 · 데이터 흐름 · 의존 관계 · 동적 등록/이벤트/DI
# 2. [EXEC] 해당 번호의 체크리스트 문서 생성 후 체크하며 진행
# 3. [EXEC] 매 체크항목마다 실제 코드 파일을 열어 마이크로 추적(Micro-Tracing) 실시
# 4. [EXEC] grep/패턴 매칭으로 "확인했다" 판단 ❌ 금지 — 실제 코드 1줄씩 읽고 추적만 인정
# 5. [EXEC] 할루시네이션 방지: 가정 금지, 소스코드 직접 확인만 인정
# 6. [EXEC] Zero Backward Compatibility:
#           리팩토링/모듈화 후 사용하지 않는 구 코드·구 구조는 반드시 삭제.
#           삭제 순서를 계획서에 시간순으로 상세하게 빠짐없이 기재. (thoroughly)
# 7. [EXEC] Zero Behavioral Change:
#           기존 흐름을 해치지 않고 오직 리팩토링/모듈화만 진행. 100% 동작 보존.
# 8. [POST] 작업 완료 후 반드시 §POST(전체 시스템 안전성 검증) 실행

0. Prerequisites — 리팩토링 시작 전 필수 조건

⚠️ 아래 조건이 충족되지 않으면 작업을 시작하지 마라.

0-0. 전체 전수조사 (★ 절대 최우선 — 생략 불가)

• 작업 전 전체 프로젝트를 완벽하게 전수조사
• 작은 의존관계부터 구조적·마이크로 플로우까지 끝까지 확인
• 파악 대상: 진입점 · 데이터 흐름 · 모듈 간 의존 관계 · 동적 등록(Tool Registry, Event Emitter, DI) · Barrel/Entry point · 세대별 흐름(v1/v2)
• 할루시네이션 금지: grep으로 "확인했다" 판단 ❌ — 파일을 열어 직접 읽고 추적만 인정
• 연결성 · 무결성 · 안전성 모두 확인. thoroughly.

0-1. 상태 스냅샷: VCS clean · 빌드 0 warnings · 전체 테스트 100% pass · 롤백 경로 확보 · 취약 의존성 없음 0-2. 범위 선언: Target Module · Change Type · Expected Impact · Regression Risk · Rollback Strategy 0-3. 금지 사항: 범위 선언 없이 수정 금지 · 테스트 없이 구조 변경 금지 · 리팩토링+기능추가 동시 커밋 금지 · 발견 버그 별도 추적 없이 수정 금지 0-4. 완료 기준: Master Checklist(§12) 전항목 ✅ · 빌드 0에러 · 테스트 100% · 0 regression · 문서 업데이트 · 성능 저하 없음 0-5. 도달성 분석: 동적 등록 매핑 완료 · Barrel/Entry point 외부 용도 파악 · 세대별 흐름 파악 · 진입점 기준 도달성 분석 완료

§POST. Post-Execution Audit — 작업 완료 후 필수 전수조사

⚠️ 모든 작업(리팩토링·모듈화·기능추가·삭제 등) 완료 후 반드시 실행. 생략 불가. 변경사항이 많을수록 이 단계가 더 중요하다. 할루시네이션 체크 금지 — 전수조사 직접 수행. ⚠️ 전체 싱크 필수: 소스 변경으로 영향받는 모든 것(테스트·타입·상수·문서·임포트 등)을 빠짐없이 동기화.

【전체 시스템 안전성·연결성·일관성 전수조사 체크리스트】

▸ 안전성 (Safety)
  □ 삭제된 코드를 참조하는 지점 0 (Dead reference 0)
  □ 새 구조로의 이주가 누락된 소비자 0
  □ 빌드 0에러 · 정적 분석 0에러
  □ 전체 테스트 100% pass (regression 0)

▸ 연결성 (Connectivity) — 실제 코드 열어 1줄씩 추적. grep 금지.
  □ 모든 import/export 경로 추적 완료
  □ 동적 연결(Registry/이벤트/DI/문자열 디스패치) 추적 완료
  □ Barrel/Entry point 공개 API 일관성 확인
  □ Producer→Consumer 필드 1:1 매칭 재검증
  □ 고아 코드(와이어업 누락) 0

▸ 일관성 (Consistency)
  □ 새 모듈·파일 명명 규칙 전체 통일
  □ 계층 구조 일관성 유지 (Presentation/Business/Infrastructure)
  □ 상수·타입 참조가 모두 현행 정의를 가리킴
  □ 문서(README/ARCHITECTURE/CHANGELOG) 현행 구조 반영

▸ 전체 싱크 (Full Sync) — 소스 변경으로 영향받는 모든 항목 동기화
  □ 테스트 코드: 시그니처·임포트·어설션·fixture 현행 소스 반영
  □ 고아 테스트 0 (삭제된 소스에 대응하는 테스트 즉시 삭제)
  □ 누락 테스트 0 (새로 추가된 공개 함수에 테스트 존재)
  □ 타입 정의: 인터페이스·enum·branded type 변경 시 모든 참조 업데이트
  □ 상수/설정: 이동·이름 변경 시 모든 소비자 임포트 경로 업데이트
  □ 환경 변수·설정 파일: 변경 시 테스트 설정·문서 동기화
  □ Mock/Stub: 현행 계약(시그니처·반환값) 반영
  □ 문서(README·ARCHITECTURE·CHANGELOG·ADR): 현행 구조 완전 반영

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

1. Stabilization — 안정화

1-1. 결함 우선순위: P0(크래시/보안) 즉시 · P1(비즈니스 로직) 당일 · P2(비효율) 사이클 내 · P3(네이밍/스타일) 별도 커밋

1-2. 리소스 라이프사이클: acquire→use→release 보장

• 획득 실패 → 명시적 에러 반환 · 사용 중 예외 → release 경로 보장 · 해제 후 재사용 차단
• Background Asset: 역할(server/worker/watcher/daemon 등) 명명 · 부모-자식 트리 추적 · 좀비/고아 자동 감지 · 작업 완료 시 즉시 정리
• 프로세스/스레드: 자식 상태 확인 후 부모 종료 · 스레드풀 drain · SIGTERM/SIGINT 핸들러 · graceful shutdown
• 정리 순서: 역의존성 순서 · 외부→내부 순서 · 공유 리소스 최후 · 정리 실패 격리(try-catch)

1-3. 에러 전파: 가장 가까운 "처리 가능 계층"으로 전파 · 에러 삼키기 금지 · 메시지에 what+why+context 포함

1-4. 동시성 안정화: 데이터 레이스 → 불변성/동기화 · 데드락 → 락 순서 강제 · 기아 → 공정 스케줄링

1-5. 에러 분류: 복구가능/치명적 × 비즈니스/기술/외부 × 일시적/영구적

• Business+Permanent → 도메인 에러 반환 · Technical+Transient → 재시도+백오프 · External+Transient → 회로차단기
• 모든 에러에 WHAT, WHY, WHERE, WITH WHAT, WHEN 포함

2. Flow Integrity — 흐름 무결성

⚠️ 모든 흐름 검증은 실제 코드를 한 줄씩 읽고 추적. grep/패턴 매칭으로 "확인했다"고 판단 절대 금지.

마이크로 추적(Micro-Tracing):

□ 생산자 함수 열어 출력 필드 목록 작성
□ 소비자 함수 열어 입력 필드 목록 작성
□ 두 목록 1:1 대조 — 누락/불일치/미사용 식별
□ 중간 변환 단계마다 동일 검증
□ 직렬화↔역직렬화 경계에서 스키마 일치 확인
□ 분기문(if/switch) 모든 경로에서 필드 접근 검증

2-1. 호출 체인 추적: 진입점 열거(API/Event/Cron/CLI) → 분기 끝까지 추적 → 도달 불가 코드 식별 2-2. 상태 전이 완전성: 모든 상태/전이 명시 · 미정의 전이 에러 처리 · 터미널 상태에서 추가 전이 차단 2-3. 경계 교차 검증: 입력 검증(수신측) · 출력 계약(송신측) · 세션/인증 재검증 · 직렬화 스키마 호환 · 외부 호출 타임아웃 · 멱등성 보장 시만 재시도

2-4. Dead Code 분류 & 액션:

• Type A(완전 미참조) → 즉시 삭제
• Type B(항상 false 분기) → 조건 제거, 살아있는 분기만 유지
• Type C(고아 코드=누락된 연결) → 삭제 금지, 연결점 분석 후 와이어업
• Type D(세대 잔여물) → v2 완전 가동 시 v1 완전 삭제
• Type E(Barrel/호환 shim) → 유지, 이유 문서화

2-5. 연결성 감사: 정적 임포트 체크 · 동적 연결(Registry/문자열 디스패치/이벤트 리스너/DI) · Barrel/Entry point 체크 · 세대 감사

2-6. Implicit Contract 검증:

• 문자열 기반 매칭 → 상수화(sender/receiver 같은 상수 참조)
• 함수 시그니처 관례 → 인터페이스 명시
• 데이터 스키마 관례 → 스키마 명시 정의, 양측 참조
• 도구/AI 등록 → 도구명 상수화, 파라미터명 코드에서 자동 추출, 등록 시 구현 존재 검증
• 설정 기반 연결 → 로드 시 참조 대상 존재 검증

3. Structural Refactoring — 구조 리팩토링

4대 원칙: ① 관심사 분리 ② 도메인 격리 ③ 구조적 명확성 ④ 확장성

3-1. 모듈 분해: 변경 이유 2개 이상 → 분리 · 다른 사용자가 다른 부분 사용 → 분리 · 테스트에 무관한 의존성 필요 → 추출

• 분리 금지: 같은 인스턴스 상태의 메서드 분리 금지 · 소비자 1개인 함수 추출 금지 · 순환 의존성 유발 분리 금지

3-2. 의존성 방향: 안정←휘발 방향만 · 순환 의존성=구조 결함 즉시 해소 · 계층 위반 금지 · 외부 의존성 어댑터 격리

3-3. 디렉토리 구조: 도메인 우선(기술 타입 우선 금지) · 깊이 최대 4단계 · 관련 파일 인접 배치 · Barrel은 공개 API만 re-export

3-4. 계층 일관성: Presentation(파싱/검증만) · Business(순수 도메인 규칙) · Infrastructure(교체 가능 구현) · Cross-cutting(미들웨어로 분리)

3-5. 파일 명명: 의미 없는 이름(utils/helpers/misc) 금지 · 1파일=1클래스/1모듈 · 빈 폴더 삭제 · 폴더당 20+ 파일 금지

3-6. 모듈 경계: 수직 슬라이싱(기능별 그룹) · 2+ 모듈 참조 리소스 → shared 이동 · 계층 참조 방향 강제 · 외부 라이브러리 3+ 파일 참조 → 어댑터 격리

4. Code-Level Refactoring — 코드 수준 리팩토링

4-1. 함수 품질: 순환 복잡도 ≤10 · 파라미터 ≤4 · 함수 길이 ≤40줄 · 중첩 ≤3단계 · 부작용 최소화

4-2. 명명 규칙:

• "무엇을 하는가/무엇인가"를 설명 · "어떻게"는 이름에 넣지 않기
• 불필요한 약어 금지(도메인 표준만 허용) · Boolean은 is/has/can/should 접두사 필수
• 의미 없는 접미사 금지: Manager/Handler/Processor/Helper/Utils/Data/Base → 구체적 이름으로 교체

4-3. Magic Value 제거: 전체 코드베이스 리터럴 수집 → 8가지 분류(이벤트/역할/명령/한계값/경로/UI텍스트/프로토콜/테스트) → 상수화 → 검증

• 허용 예외: 0, 1, -1(인덱스), 빈 문자열, true/false — 단, 맥락에서 의미 불명확하면 상수화

4-4. 타입 안전: 암시적 형변환 금지 · any/void*/untyped 금지 · Union/enum 완전 매칭 · Nullable 명시 표기 · 외부 입력 경계에서 타입 검증

4-5. 조건문 품질: Guard Clause(실패 먼저 반환) · Table Dispatch(5+ 분기) · 다형성 · 이중 부정 금지 · 복잡 조건 함수 추출

4-6. 중복 제거: 완전 동일 → 함수 추출 · 구조 동일/세부 다름 → 파라미터화 · 표면만 유사/다른 도메인 → 유지(의도적 중복 주석)

5. Constants/Config Architecture — 상수/설정 아키텍처

5-1. 분류: Layer1(환경설정=런타임) · Layer2(도메인 상수=비즈니스 규칙) · Layer3(시스템 상수) · Layer4(언어/프레임워크 기본 상수=재정의 금지) 5-2. 파일 명명: {domain}.const.{ext} · 공유: _shared/common.const.{ext} 5-3. 중복 제거: 같은 값 2+ 도메인 존재 → _shared/ 이동 · Barrel로 통합 임포트 경로 제공 5-4. 타입 안전 상수: 불변성 보장 · 리터럴 타입 보존 · 상수에서 타입 도출 · 관련 상수 그룹 객체화 · 읽기전용 배열/셋 5-5. 그룹핑: 의미 단위별 그룹 · SCREAMING_SNAKE_CASE · Barrel로 단일 진입점

6. Comment & Documentation — 주석 & 문서

6-1. 주석 품질: 코드가 이미 말하는 것 반복=노이즈 → 삭제 · WHY/CONTEXT/WARNING/INVARIANT/PERF/HACK만 유지 6-2. 형식: // WHY: // INVARIANT: // WARNING: // HACK(#이슈): · 함수 문서: 요약+의도+파라미터+반환+예외 6-3. TODO/FIXME: 이슈 번호+기한 필수 · 기한 없는 TODO 금지 · 분기별 감사 6-4. 문서 계층: README(설치→실행→검증 100줄 이하) · ARCHITECTURE(토폴로지/데이터 흐름) · CHANGELOG · ADR 6-5. ADR: 2+ 기술 선택지 · 새 의존성 · 데이터/API 전략 변경 → ADR 작성 6-6. 로깅: FATAL/ERROR/WARN/INFO/DEBUG/TRACE · 구조화 로그(JSON: ts, level, module, msg, context) · 비밀/PII 로깅 금지

7. Readability — 가독성

• 줄당 1개 의미 단위 · 체이닝 3단계까지 · 4+ 중간 변수로 분리
• 함수 내 추상화 수준 통일 (고수준/저수준 혼합 금지)
• 위→아래 읽기 순서 · Happy path 들여쓰기 없이 · 관련 코드 인접 배치 · 최소 놀라움 원칙

8. Test & Verification — 테스트 & 검증

8-1. 피라미드: Unit 70% · Integration 20% · E2E 10% 8-2. 단위 테스트: 공개 함수당 최소 1개 · 경계값 필수(min/max/0/empty/null) · 실패 경로 필수 · AAA 패턴 · 테스트 간 상태 독립

8-3. 스트레스 검증: 리소스 고갈 → graceful 거부 · 동시성 충돌 → 데이터 무결성 · 네트워크 열화 → 재시도/폴백 · 악성 입력 → 검증 실패+안전 거부

8-4. 테스트 파일: 소스 경로와 1:1 대응 · 프로젝트 전체 하나의 방식

8-5. 복잡도 예산: 순환복잡도 ≤10 · 중첩 ≤3 · 파라미터 ≤4

• 파일 분해 신호: ① 변경 이유 복수 ② 도메인 혼합 ③ 이름 짓기 어려움(utils 등) ④ 데이터 테이블이 로직 지배 ⑤ 스크롤 필요
• 가이드 범위: ≤200 이상적 · 200~400 수용 · 400~500 검토(사유 문서화) · 500+ 거의 분리 필요

8-6. 테스트-소스 동기화(Test Sync):

□ 소스 변경 시: 영향 분석 → 시그니처 동기화 → 행동 동기화 → 커버리지 동기화 → 실행 검증
□ 리팩토링 시: 이름 변경 시 모든 테스트 임포트/어설션 업데이트
              · 환경 변수 변경 시 테스트 설정 업데이트
              · 타입 변경 시 모든 fixture 업데이트
              · 소스 삭제 시 해당 테스트 즉시 삭제
□ 금지: 통과하지만 오래된 어설션 · 테스트에 소스 상수 복사(임포트 사용) · 리팩토링 중 테스트 skip

9. Security & Operational Safety — 보안 & 운영 안전

• 운영 보안: 임시 파일/리소스 즉시 정리 · 민감 정보 로그 금지 · 리소스 격리
• Safety Guardrails: 스코프 가드(승인된 범위 자동 검증) · 승인 게이트(고위험 작업) · 리소스 쿼터 · 입력 검증
• 민감 데이터 관리: 데이터 무결성 · 암호화 저장 · 접근 제어 · 기밀 유지

10. Performance — 성능

• 원칙: 측정 먼저 · 병목 식별(상위 20%) · 알고리즘 개선 우선 · 가독성 해치는 최적화는 측정 근거 필요
• 일반 병목: 불필요 할당 → 풀링 · N+1 → 배치 · 불필요 복사 → 참조 전달 · 블로킹 IO → 비동기 · 락 경합 → 세밀한 락
• 캐싱: 읽기>>쓰기 AND 오래된 데이터 허용 AND 비싼 계산일 때만 캐시 · TTL 필수 · 캐시=일시적 저장소

11. Refactoring Execution Protocol — 실행 프로토콜

8단계: SURVEY(전수조사) → AUDIT → PLAN → EXECUTE(§4/§5 준수) → TEST(§8) → HARDEN(§9) → DOCUMENT(§6) → VERIFY(§POST + E2E, 0 regression)

• 이상 발견 시 즉시 중단 → 보고 → 지시 대기

증분 vs 일괄: 기본=증분(기존 옆에 신규 구현 → 소비자 이주 → 구 구현 제거) · 일괄은 500줄 미만+전체 소비자 동시 업데이트 가능할 때만

11-3. 실행 흐름 검증 (Anti-Hallucination):

EXECUTE(실제 데이터) → OBSERVE(실제 출력 vs 기대) → CORRECT(근거 기반 수정) → RE-EXECUTE(100% pass)

할루시네이션 4대 범주:
1. API Shape    : 함수 시그니처 — 소스 코드에서 직접 확인 필수
2. Export Boundary: 모듈 공개 API(entry point/barrel file) — 직접 확인 필수
3. Data Flow   : 상수/설정 파일의 실제 매핑 — 직접 확인 필수
4. State Shape : 상태 인터페이스/클래스 정의 — 직접 확인 필수

교차 모듈 검증: 임포트 해소 · 데이터 흐름 · 상태 변이 · 이벤트/메시지 · 스트레스 하 안정성

12. Master Checklist — 마스터 체크리스트

A. 안정화

□ 에셋 역할 할당 · □ acquire-use-release 증명 · □ 좀비/고아 자동감지 · □ 에러 전파 갭 0 · □ 데이터 레이스 0 · □ 외부 호출 타임아웃/하트비트

B. 흐름 무결성

□ 진입점→종료 호출체인 추적 완료 · □ 모든 분기 처리 · □ 고아 코드 0(와이어업 완료) · □ 세대 잔여물 0(v1 완전 퍼지) · □ Dead code 0
□ 미정의 상태 전이 0 · □ 경계 교차 검증 누락 0 · □ Implicit contract 일관성 검증 · □ Micro-Tracing으로 검증(grep 아님) · □ Producer→Consumer 필드 1:1 매칭

C. 구조

□ 순환 의존성 0 · □ 단일 책임 위반 0 · □ 계층 위반 0 · □ 디렉토리 깊이 ≤4 · □ 외부 의존성 어댑터 격리

D. 코드 품질

□ Magic value 0 · □ 순환복잡도 ≤10 · □ 파일 길이 원칙 기반 분해(§8-5) · □ 중첩 ≤3 · □ 파라미터 ≤4 · □ 암시적 형변환 0 · □ any/untyped 0

E. 명명 & 가독성

□ 모든 이름이 의미 설명 · □ 약어는 도메인 표준만 · □ 함수 내 추상화 수준 일관 · □ Happy path 들여쓰기 없음 · □ 관련 코드 인접

F. 주석 & 문서

□ 노이즈 주석 0 · □ WHY 주석 존재 · □ TODO/FIXME에 이슈번호+기한 · □ README/ARCHITECTURE/CHANGELOG 최신 · □ ADR 완료

G. 테스트 & 동기화

□ 공개 함수별 테스트 존재 · □ 경계값+실패 경로 커버리지 · □ 테스트 간 상태 독립 · □ 스트레스 시나리오 검증
□ 전체 100% pass · □ 테스트 임포트 → 현행 소스 모듈 · □ 함수 호출 → 현행 시그니처 · □ 어설션 → 현행 동작
□ Mock/Stub → 현행 계약 · □ 환경변수 → 현행 설정 · □ 상수/타입 참조 → 현행 정의 · □ 고아 테스트 0 · □ 누락 테스트 0

H. 보안 & 안전

□ 외부 진입점 입력 검증 · □ 인젝션/리소스 고갈 벡터 체크 · □ 승인 게이트/접근 제어 정책 · □ 민감 데이터 암호화/격리 · □ 임시 데이터/프로세스 자동 회수

I. 성능

□ 프로파일링 기반 병목 식별 · □ N+1 문제 0 · □ 불필요 할당/복사 최소화 · □ 벤치마크 전/후 기록 · □ 가독성 훼손 최적화에 측정 근거

J. 운영

□ 버전 태그 업데이트(SemVer) · □ CHANGELOG 커밋 해시 링크 · □ 빌드 경고 0 · □ CI/CD 통과 · □ 롤백 경로 검증

K. 상수화

□ Magic string 0 · □ Magic number 0 · □ 상수 파일 도메인별 분리 · □ 공유 상수 shared 디렉토리 · □ 불변 선언 · □ 상수에서 타입 도출 · □ Barrel로 통합 경로

L. 도메인 구조

□ 도메인 폴더 분리 · □ 동일 표준 구조 · □ 도메인 진입점으로 중앙 등록/발견 · □ 도메인 간 직접 참조 0 · □ 도메인 전용 리소스 격리

M. ADR & 로깅

□ 비자명 아키텍처 결정에 ADR 존재 · □ 로그 레벨 표준 준수 · □ 구조화 로깅(JSON) · □ 비밀/PII 로깅 없음 · □ 외부 시스템 호출 로깅

N. 코드 리뷰 & 캐싱

□ 코드 리뷰 체크리스트 준수 · □ 캐싱 결정 프레임워크 준수 · □ 모든 캐시 TTL 설정 · □ N+1 쿼리 패턴 없음

O. 마이그레이션 & API 계약

□ 스키마 마이그레이션 역호환 또는 롤백 계획 · □ API SemVer · □ Deprecated API에 sunset 타임라인 · □ Breaking change CHANGELOG 기록

P. 의존성 & 프로덕션 안전

□ 취약 의존성 0 · □ 외부 의존성 어댑터 격리 · □ 위험 변경에 피처 플래그 · □ 롤백 절차 테스트/문서화 · □ 증분 리팩토링 적용

Q. 모니터링 & 관측

□ 리팩토링 전 기준선 기록 · □ 리팩토링 후 저하 없음 · □ 크리티컬 경로 알림 설정 · □ 에러율/지연/처리량 모니터 · □ 관측 기간 완료 무이상

R. 기술 부채 & 레거시

□ 기술 부채 인벤토리 최신 · □ 부채 항목에 심각도/비용/우선순위 · □ 레거시 코드에 특성화 테스트 · □ 테스트 없는 레거시 수정 금지

S. Git & 우선순위

□ 커밋 메시지 표준(type(scope): subject) · □ 원자적 커밋(1 논리 변경/커밋) · □ PR ≤400줄 · □ 우선순위=Pain/Effort · □ 고위험-고보상 먼저

T. 타입 시스템, 에러 처리, 동시성, 설정

□ 판별 공용체 사용 · □ stringly-typed API 0(enum/branded type) · □ 재시도/회로차단기 패턴 · □ 공유 가변 상태 보호 · □ 런타임 설정 vs 빌드타임 상수 분리 · □ 비밀은 vault/env만

U. 실행 흐름 검증 (Anti-Hallucination)

□ 수정된 실행 경로 실제 데이터로 실행 · □ API shape 할루시네이션 0 · □ Export boundary 할루시네이션 0
□ Data flow 할루시네이션 0 · □ State shape 할루시네이션 0 · □ 교차 모듈 E2E 테스트 · □ Execute→Observe→Correct 근거 문서화
□ 모든 에러 경로 actionable 메시지 · □ 전체 테스트 pass · □ 정적 분석 0에러 · □ 빌드 0에러

V. Post-Execution 전수조사 (★ 작업 완료 후 필수)

□ 전체 시스템 安전성·연결성·일관성 전수조사 완료 (§POST)
□ 삭제 코드 참조 0 (Dead reference 0)
□ 모든 import/export 경로 추적 완료 (grep 아님 — 직접 추적)
□ 동적 연결(Registry/이벤트/DI) 추적 완료
□ 프로젝트 영향도 분석 완료 · 문제 없음 확인
□ 문서(README/ARCHITECTURE/CHANGELOG) 현행 반영
□ 빌드 0에러 · 테스트 100% pass (최종)

13. Domain-Driven Structure — 도메인 주도 구조

• 분해: 1개 비즈니스 개념=1개 도메인 후보 · 독립 변경 가능 → 별도 폴더 · 전용 타입/상수/로직 있으면 자체 구조
• 폴더 구성: 필수(구현+타입) · 선택(상수/데이터접근/테스트/진입점) · 도메인 폴더당 파일 ≤7 · 도메인 간 직접 참조 금지
• 진입점: 중앙 등록 · 내부 구현 은닉 · 필요시 레지스트리 패턴
• 격리: 수평 격리(도메인↔도메인 직접 의존 금지) · 수직 격리(도메인→상위 계층 의존 금지)

15. Migration & Data Schema — 마이그레이션

• 모든 마이그레이션 역방향(DOWN) 필수 · 역호환 기간 · 컬럼 추가→사용→삭제 순서 · DROP 전 백업 검증 · 대용량은 배치 처리

16. API Contract & Versioning — API 계약

• SemVer(MAJOR.MINOR.PATCH) · Breaking change 정의: 제거/타입변경/필수↔선택변경/의미변경
• Deprecation: 경고+sunset 날짜 · 최소 2 minor 후 제거 · 마이그레이션 가이드 제공

17. Dependency Management — 의존성 관리

• 추가 전: 50줄 이내 구현 가능? · 전이 의존성 10+ 끌어오는가? · 활발히 유지보수? · 취약점 있는가?
• 버전 잠금(lockfile) · "latest"/"*" 프로덕션 금지 · 3+ 파일 참조 → 어댑터 래핑
• 업그레이드: 보안 감사 → 변경로그 읽기 → 1개씩 격리 업그레이드 → 전체 테스트 → 스테이징 검증 → 배포 후 모니터

18. Production Refactoring — 프로덕션 안전 배포

• 피처 플래그: 위험 리팩토링은 릴리즈 플래그 뒤에 · 기본값=OFF · 완전 롤아웃 2스프린트 내 플래그 제거
• 롤아웃: 카나리(1%→5%→25%→50%→100%) · 롤백 5분 이내 완료 · 배포 전 롤백 테스트

19. Monitoring & Observability — 모니터링

• 기준선 기록: 에러율, 지연(p50/p95/p99), 처리량, 리소스, 비즈니스 메트릭, 빌드/테스트 시간
• 검증: 동일 워크로드로 비교 · 에러율↓ · 지연↓(5% 허용) · 처리량↑ · 프로덕션 최소 24시간 관측

20. Technical Debt — 기술 부채

• 인벤토리: ID, 위치, 설명, 원인, 심각도, 수정비용, 미수정 위험, 담당자
• 상환: 스프린트 15~20% 예약 · 기회적 상환(파일 작업 시 함께) · 분기별 감사 · 부채 천장 → 초과 시 기능 중단

21. Legacy Code Strategy — 레거시 코드

• 특성화 테스트: 변경 전 현행 동작 캡처 · 버그 포함 실제 출력 assert · 리팩토링 후 올바른 동작으로 업데이트
• Seam: 객체/전처리기/링크/인터페이스 seam 식별 → 의존성 분리 → 테스트 → 안전 리팩토링

22. Git/VCS Hygiene — Git 위생

• 커밋: <type>(<scope>): <subject> · 제목 ≤72자 · 명령형 · 본문에 WHY · 푸터에 이슈 번호
• 원자적 커밋: 1논리변경/커밋 · 모든 커밋 빌드+테스트 통과 · 리팩토링+동작변경 혼합 금지
• 브랜치: ≤3일 · PR ≤400줄 · 스택 PR 사용

23. Refactoring Prioritization — 우선순위

• Priority = Pain / Effort: >2.0 즉시 · 1.0~2.0 다음 스프린트 · 0.5~1.0 백로그 · <0.5 수용
• Hotspot: 변경 빈도 높음 + 복잡도 높음 = 1순위 리팩토링 대상

24. Type System Maximization — 타입 시스템 극대화

• 원시 타입 집착 → enum → branded type → 판별 공용체 → phantom type 순으로 강화
• boolean 플래그 → union type · optional 필드 → 별도 타입 · 완전 매칭 · Parse, don't validate

25. Error Handling Patterns — 에러 처리 패턴

• 재시도: 일시적 에러만 · 최대 3~5회 · 지수 백오프+지터 · 멱등성 필수 · 401/403/400/404 재시도 금지
• 회로차단기: CLOSED→OPEN→HALF-OPEN · 의존성별 설정 · OPEN 시 폴백 반환 · 상태 전이 로깅+알림
• 폴백 계층: 재시도 → 대안 소스 → 열화 응답 → 큐잉 → 정중 거부

26. Concurrency Patterns — 동시성 패턴

• 공유 상태 회피 가능? → 최선 · 읽기 위주 → RW Lock · 분할 가능 → Actor · 파이프라인 → Channel · 최후 → Mutex(순서 규칙)
• 안티패턴: 락 순서 위반 · 락 내 IO · await 누락 · 루프 내 await · check-then-act 레이스

27. Configuration Management — 설정 관리

• 우선순위: CLI args > 환경변수 > 로컬 설정 > 공유 설정 > 앱 기본값
• 비밀: 코드/설정파일/CI로그에 비밀 금지 · vault/암호화 env만 · 재배포 없이 교체 가능
• 환경 분리: 모든 환경 동일 바이너리 · 설정만 다름 · dev/staging≈production · 시작 시 필수 설정 검증+실패 시 즉시 종료

28. 불필요 복잡도 제거

동작에 필요 없는 과도한 레이어/처리/패턴이 있다면 단순화. "굳이 이렇게까지 복잡해야 하나?"라는 코드는 제거 또는 단순화 대상.

§M. Modulization Protocol — 모듈화 전용 프로토콜

핵심 원칙: 큰 덩어리를 한 번에 분리하려 하지 말고, 가장 작은 단위부터 하나씩 완전히 독립된 작업으로 차근차근 진행

M-1. 전제 조건

• 전체 프로젝트 전수조사 완료 (§0-0) 후에만 시작
• 확장성/응집도 관점에서 가장 급해 보이는 딱 한 가지부터 시작 (큰 작업이 아니어도 됨)
• 분할과 정복: 작은 단위 → 큰 단위, 간단한 작업 → 복잡한 작업 방향으로 진행

M-2. 계획서 작성 (TaskCreate 도구로 태스크 생성)

□ 현재 As-Is 구조 명시 (기존 코드 위치, 의존성)
□ 목표 To-Be 구조 명시 (새로운 모듈 경계, 파일/폴더)
□ 시간순 단계별 실행 계획 — 빠짐없이 모두 기술 (thoroughly)
□ 각 단계별 롤백 방법
□ 프로젝트 영향도 분석 포함

M-3. Zero Backward Compatibility (구코드 완전 삭제)

• 모듈화 완료 후 구 코드/구 구조는 반드시 삭제 (남기면 복잡도 증가)
• 삭제 순서는 계획서에 시간순으로 상세하게 기재
• 삭제 전 의존성 체인 전수조사 필수

M-4. Zero Behavioral Change (100% 동작 보존)

• 기존 흐름을 해치지 않고 오직 모듈화(구조 변경)만 수행
• 각 이주 단계 후 전체 테스트 100% pass 확인
• 동작 변경 발견 시 즉시 중단 → 보고 → 지시 대기

M-5. 이주(Migration) 순서

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

╔═══════════════════════════════════════════════════════════════╗

║ END OF DOCUMENT v5.0 ║

║ Merged: refactoring.md + modulizeation.md + after-update.md║

╚═══════════════════════════════════════════════════════════════╝