점진 리팩터 · 트레이드오프

큰 재작성 (big bang rewrite) 은 거의 실패합니다. 작은 단계 · 늘 배포 가능한 상태가 장기 승자.

1. 큰 재작성이 실패하는 이유

• 범위 인플레 — "이왕 고치는 김에" 가 끝없이 커짐
• 기능 정지 — 재작성 중 신기능 불가
• 검증 불가 — 수백 이전 기능이 그대로 작동하는지 확인 비용
• 동기 부여 손실 — 6 개월 후 완성 불확실

Netscape · Twitter · Basecamp · Joel Spolsky 모두 "rewrite 는 피하라" 에 동의.

2. 점진 리팩터의 원칙

• 매 커밋 동작 가능 (GREEN)
• 기존 코드 옆에 새 코드 배치 · 점차 전환
• feature flag · env 분기로 rollback 쉽게
• 측정 가능한 지표로 진행 추적

3. Strangler Fig 패턴

기존 시스템을 감싸면서 점차 대체 · 마지막엔 기존 제거.

Phase 1:  [Old App]  ←  traffic
Phase 2:  [Router] → [Old App] + [New App]   (일부 라우트만)
Phase 3:  [Router] → [New App] (전체)
Phase 4:  [Old App] 제거

pryzeet 의 /api/admin/* → admin 앱 이전 (2026-04-24) 이 이 패턴.

4. Branch by Abstraction

기존 구현과 새 구현을 추상화 레이어 뒤에 두고 런타임 스위치.

interface EmailSender {
  send(to: string, body: string): Promise<void>;
}

class SmtpSender implements EmailSender { ... }
class SesSender implements EmailSender { ... }      // 새 구현

const sender: EmailSender = process.env.EMAIL_PROVIDER === "ses"
  ? new SesSender() : new SmtpSender();

prod 에서는 smtp, staging 에서는 ses 로 먼저 검증. 이상 없으면 prod 도 전환.

5. 테스트로 안전망

리팩터 전 기존 동작 테스트 작성. 리팩터 후 동일하게 통과 = 안전.

describe("calculateShipping (pre-refactor baseline)", () => {
  it("...여러 시나리오 철저히", () => { ... });
});

그 다음 내부 리팩터. 테스트 초록 유지.

6. 하루짜리 리팩터 원칙

한 PR = 하루 안에 끝나는 크기. "2 주짜리 PR" 은 머지 안 됨.

- [ ] 500 lines 이하 변경
- [ ] 녹색 CI
- [ ] 독립적으로 rollback 가능

큰 변경은 단계로 쪼개 여러 PR.

7. 트레이드오프 의식적 선택

"최적" 은 환경 종속적. 의식적 선택이 중요.

축	A 선택	B 선택
성능 vs 가독성	최적화 · 주석 많음	단순 · 느림
타입 엄격 vs 빠른 iteration	TS strict · 완벽 타입	any · prototype
SSR vs CSR	초기 빠름 · 서버 부하	초기 느림 · 인터랙티브 좋음
ORM vs raw SQL	타입 안전 · 생산성	성능 · 투명

"왜 A 대신 B?" 를 코드 주석 · PR 설명에 기록.

8. 안티패턴 — "전부 다시 쓰고 싶다"

"이 코드 형편없어 다 다시 쓰자" 가 든다면:

1. 정말 다 다시 써야 하는가? 일부 리팩터로 가능?
2. 현재 코드가 동작한다는 가치
3. 다시 써도 같은 실수 반복할 가능성

대안:

• 테스트 추가로 안전망
• 가장 아픈 부분만 리팩터
• 새 코드는 옆에 · 점진 전환

9. 작은 일관성

코드 일관성은 "정답" 이 아니라 "팀 합의".

• "function vs const" 둘 중 하나 고르고 지키기
• "for vs .map" 일관
• Prettier · ESLint 로 자동화

어떤 스타일인지보다 한 스타일 이 중요.

10. 매몰비용 편향 주의

"이미 1 개월 투자했으니 더 가야 한다" 는 위험.

• 현재 시점에서 "새로 시작한다면?" 질문
• 드롭 결정도 가치
• 학습은 남음

11. 자주 걸리는 자리

• 5 단계 마이그 중 2 번째에서 멈춤 — 두 시스템 혼재 영구화
• 추상화 레이어가 과도 — "필요해질 수도" 로 미리 만들면 대개 안 씀 (YAGNI)
• 테스트 없이 리팩터 — 회귀 발견 늦음
• 리팩터 중 새 기능 같이 — 원인 분리 불가

하고픈 말

"이 시스템을 다 다시 쓰고 싶다" 는 감정이 자주 옵니다. 거의 항상 함정. 매일 조금씩 · 테스트 · 트레이드오프 의식이 장기적으로 편함.

Next

• 06-agent-friendly-docs