refactoring

name	refactoring
description	기존 코드의 안전한 리팩토링. Characterization Test로 동작을 보존하며 구조 개선. Use when 리팩토링, 레거시 코드 개선, 동작 보존, 구조 개선, 기존 코드 정리, characterization test 작성 시. Do NOT use for 새 기능 개발이나 버그 수정 (일반 편집 사용).
user-invocable	true

Refactoring

기존 코드를 안전하게 리팩토링하는 ANALYZE-PRESERVE-IMPROVE 워크플로우.

tidy와의 구분

	tidy	refactoring
규모	분 단위 소규모 정리	시간~일 단위 구조 변경
테스트	기존 테스트 의존	Characterization Test 새로 작성
범위	단일 패턴 (guard clause, dead code 등)	모듈 추출, 클래스 분리, API 마이그레이션
커밋	1 tidying = 1 commit	단계별 incremental commit

tdd와의 구분

	tdd	refactoring
대상	새 기능 (코드 없음)	기존 코드 (동작 있음)
테스트	Specification Test (기대 동작 정의)	Characterization Test (현재 동작 캡처)
사이클	RED-GREEN-REFACTOR	ANALYZE-PRESERVE-IMPROVE

ANALYZE-PRESERVE-IMPROVE Cycle

Phase 1: ANALYZE

현재 코드 구조를 파악하고 리팩토링 대상을 식별한다.

구조 분석:

• 모듈 의존성, import 패턴 (/vis-graph 활용)
• 결합도 측정 (ast-grep + Grep으로 참조 지점 집계)
• 데이터 흐름, 공유 상태, 결합 지점

문제 패턴 식별 (ast-grep 활용):

• God class: 너무 많은 메서드/책임
• Feature envy: 다른 클래스 데이터를 과도하게 사용
• Long parameter list: 누락된 추상화
• Duplicate code: 모듈 간 중복 패턴

산출물: 현재 구조 + 문제 영역 + 리팩토링 대상 + 리스크 평가

Phase 2: PRESERVE

변경 전 안전망을 구축한다. 이 단계를 건너뛰지 않는다.

Characterization Test 작성:

1. 핵심 코드 경로를 식별
2. 경로를 실행하는 테스트 작성
3. 테스트를 먼저 실패시켜 실제 출력을 확인
4. 실제 출력을 기대값으로 업데이트
5. 놀라운 동작이 있으면 문서화

Characterization Test는 "정답"을 검증하는 게 아니라 **"현재 동작"**을 기록한다. 리팩토링 후 이 테스트가 깨지면 동작이 바뀐 것이다.

네이밍: test_characterize_{component}_{scenario}

Characterization Test의 품질은 /principles check TEST-BEHAVIOR (외부 행위 기반 검증) 및 /principles check TEST-SMELLS (Sensitive Equality — 부동소수점·직렬화 포맷 주의) 참조.

Behavior Snapshot (복잡한 출력일 때):

• API 응답, 직렬화 출력, 상태 변환, 에러 메시지

Safety Net 검증:

• 기존 테스트 100% 통과
• 새 characterization test가 리팩토링 대상을 커버
• Flaky 테스트 없음 확인

Phase 3: IMPROVE

한 번에 큰 변경을 하지 않는다. 패턴:

가장 작은 구조 변경 → 전체 테스트 → 실패 시 즉시 revert → 성공 시 commit → 반복

안전한 리팩토링 패턴:

• Extract Method: 반복 코드 블록 또는 긴 메서드 → 명명된 함수로 분리
• Extract Class: 다중 책임 클래스 → 관련 메서드/필드를 새 클래스로 이동 (원본 API는 위임으로 유지)
• Move Method: Feature envy → 데이터가 있는 클래스로 이동
• Inline: 불필요한 간접 참조 제거
• Rename: ast-grep rewrite로 모든 참조를 원자적으로 변경

각 변환 후 검증:

1. Unit test (빠른 피드백)
2. Characterization test (동작 보존 확인)
3. 새 warning/error 없음 확인

실행 순서

1. 리팩토링 범위 확인 (SPEC 또는 사용자 요청)
2. ANALYZE: 대상 코드 구조 분석
3. PRESERVE: Characterization Test 작성 + 기존 테스트 통과 확인
4. IMPROVE: 점진적 변환 (각 단계마다 테스트 + 커밋)
5. 검증: 전후 메트릭 비교 + 모든 테스트 통과

Behavior Preservation 원칙

리팩토링의 황금률: 관찰 가능한 동작이 전후 동일해야 한다.

• 기존 테스트 전부 통과
• API 계약 동일
• 부작용(side effects) 동일
• 성능 특성이 허용 범위 내

Troubleshooting

테스트 실패 시: 즉시 revert → 어떤 테스트가 왜 실패했는지 분석 → 더 작은 단위로 재시도

Characterization Test가 flaky: 비결정적 요소 식별 → 외부 의존성 mock → 시간/순서 의존 제거

성능 저하: 전후 프로파일링 → 핫 패스 확인 → 최적화 또는 트레이드오프 문서화

See Also

• /tidy — 분 단위 소규모 코드 정리
• /plan-review tdd — 새 기능의 테스트 주도 개발
• /vis-graph — 파일 간 의존성 시각화
• /strategic-thinking — 리팩토링 범위 결정 시 체계적 판단

Origin: moai-adk workflow-ddd (ANALYZE-PRESERVE-IMPROVE cycle) 기반, dots 스타일로 재구성