전환은 감이 아니라 리허설이다 — 큰 변경을 안전하게 겪는 시스템
AI는 마이그레이션 초안을 하루 안에 만들지만, 배포해도 되는지는 여전히 사람의 운영 설계다. 마이그레이션 리허설 4단계, 디자인 시스템 3레인, 변경 실패율(CFR) 태깅을 실제 전환 이력과 함께 한 편으로 묶었다.
전환은 감이 아니라 리허설이다 — 큰 변경을 안전하게 겪는 시스템
4월 초에 프론트엔드 AI 실무 시리즈에서 레거시 마이그레이션 리허설 플레이북을 썼다. 이어서 변경 실패율(CFR) 운영법, 디자인 시스템 안전한 배포까지 4월 안에 세 편을 더 썼다. 주제는 저마다 달라 보였는데, 돌아보면 같은 문장을 세 번 쓴 것이었다.
변경이 커질수록 결정하는 건 생성 속도가 아니라, 배포해도 된다는 증명이다.
첫 편의 게이트가 “배포 가능함을 증명하는 장치”, 두 번째 편의 계약이 “품질을 사전에 고정하는 장치”, 세 번째 편의 런북이 “터진 뒤의 장치”라면, 이번 글은 그 사이에서 가장 큰 덩어리를 다룬다. 한 번에 갈아엎어야 하는 변경이다. 지난 편 끝에 “장애만큼 큰 나머지 리스크는 큰 변경”이라고 썼다. 이 글은 4월의 세 편을 한 편으로 합쳐 다시 쓴 것이다. 프레임은 남기고, 그 사이에 내가 실제로 겪은 전환 이력을 이식했다.
1. 속도의 착시 — PR은 늘었는데 롤백도 늘었다
AI 에이전트를 붙이고 나서 자주 겪는 착시가 두 가지 있다. PR 처리량은 늘었는데 장애 티켓도 같이 늘어난 경우. 코드 작성 속도는 빨라졌는데 롤백과 핫픽스 빈도는 그대로인 경우. 속도 지표만 보면 성공이고, 안정성 지표를 보면 실패인 상태다.
마이그레이션은 이 착시가 가장 크게 터지는 자리다. 한 번에 갈아엎는 방식이 실패하는 패턴도 정해져 있다.
- 코드량은 줄었는데 장애가 늘어난다
- 테스트는 통과했는데 사용자 행동 지표가 나빠진다
- 롤백 시나리오가 없어서 배포 결정 자체를 미루게 된다
AI는 초안을 하루 안에 만들어 준다. 그래서 위험의 무게중심은 “초안을 어떻게 빨리 뽑나”에서 “이걸 배포해도 되는지를 무엇으로 아나”로 옮겨 간다. 그래서 나는 이 작업을 마이그레이션이 아니라 마이그레이션 리허설이라고 부르기로 했다. 실제 배포 전에 동일 조건에서 가짜 배포를 반복하고, 실패 패턴을 먼저 수집하고, 배포와 보류의 기준을 숫자로 고정하는 것. “시도했다”가 아니라 “통제했다”로 설명되는 상태를 만드는 일이다.
2. 리허설 4단계 — 범위, 제약, 검증 표, 결정 규칙
1) 범위 고정 — 페이지가 아니라 기능 단위로 자른다
“검색 페이지 전체 전환” 같은 목표는 리허설이 성립하지 않는다. 검색 필터 영역, 카드 렌더러 한 종, API 응답 파서처럼 잘게 잘라야 가짜 배포를 반복할 수 있다.
- 사용자 영향: 검색 결과 정확도/속도
- 기술 범위: state 관리 + 렌더 분기
- 제외 범위: 디자인 변경, API 스키마 변경
두 번째 편의 Task Contract(Goal/Scope/Non-goals/Verification)과 같은 모양이다. 계약이 변경 단위에 붙은 것일 뿐이다. 제외 범위가 없으면 리허설이 전면 전환으로 불어난다.
2) 제약 프롬프트 — “잘 만들어줘”보다 금지 조건
마이그레이션 초안을 에이전트에게 맡길 때 품질 편차를 줄이는 건 칭찬이 아니라 금지다.
- 기존 URL 쿼리 포맷 유지
- 접근성 속성(aria-*) 제거 금지
- 에러 로깅 경로 변경 금지
역시 앞 편의 Do Not 프롬프트와 같은 원리다. 이행(移行)은 “새로 잘 짓기”가 아니라 “지켜야 할 것을 그대로 옮기기”라서, 금지 조건이 요구사항의 대부분을 차지한다.
3) 리허설 검증 표 — 성공과 실패를 미리 숫자로 고정한다
리허설에서 최소한 세 가지는 배포 전에 고정해 둔다. 기능 회귀(핵심 E2E 시나리오 통과율), 사용자 체감(LCP/INP/CLS 전후 비교), 운영 안정성(에러율·경고 로그 변화). 그리고 판정은 문장이 아니라 표로 남긴다.
| 항목 | 기준 | 결과 | 판정 |
|---|---|---|---|
| 핵심 E2E 시나리오 | |||
| INP p75 | |||
| JS Error rate |
원문의 이 표에는 숫자가 들어 있었다. 전부 측정한 적 없는 가상 예시였기에 이 글에서는 값을 비웠다. 표를 채우는 건 글을 읽는 사람의 리허션이고, 게이트가 실제로 다음 단계를 차단하는 모습은 첫 편에서 이미 보았다. 지금 진행 중인 프로젝트의 작업 로그 기준으로 유닛 테스트 218/218, E2E 131를 통과해야 다음 단계로 넘어가는 구조다.
4) 결정 규칙 — 배포/보류/부분 배포를 미리 정한다
리허설의 결과를 놓고 회의하지 않는다. 규칙을 미리 정해 둔다.
- 배포: 핵심 기능 회귀 0건 + 지표 악화 없음
- 부분 배포: 기능은 통과, 성능이 경계값 근접
- 보류: 회귀 1건 이상 또는 모니터링 이상치
감이 아니라 규칙으로 내리는 이유는 하나다. 결정 근거가 남아야 다음 반복이 이번 반복의 실패에서 시작된다.
3. 두 번의 전환 — 이 프레임을 실제로 쓴 이력
프레임만 있으면 여전히 처방이다. 이 글을 다시 쓰면서 이식한 내 기록이 두 건 있다.
블로그: Nextra에서 Astro 5로. 이 블로그는 원래 Nextra로 굴렀고, Astro 5 + MDX로 이관할 때 에이전트와 함께 작업했다. 눈여겨볼 건 이 관점이 이후에도 반복된다는 것이다. 지금 이 시리즈를 24편에서 5편으로 통합하는 작업도 같은 질서로 진행 중이다. 초안이 다 쓰이고 검증되기 전까지 원문 24편은 그대로 두고, 내리는 시점에는 URL이 죽지 않도록 리다이렉트와 같은 배치에서 처리한다. “새 것을 먼저 만들고, 증명된 뒤에 낡은 것을 내린다” — 리허설의 논리를 콘텐츠 변경에 그대로 적용한 것이다.
데스크톱 앱: Python GUI에서 Tauri 2 + Rust + React 19로. Confluence 문서 내보내기 도구를 confluence-export-desktop(Python GUI)에서 confluence-studio로 갈아탔다. 스택 전환은 마이그레이션 중에서도 가장 큰 부류라 리허설 비용이 가장 크다. 이때 검증 표의 ‘근거’ 칸을 채우는 건 숫자만이 아니다. 왜 그 스택인지에 대한 기록도 근거다. Rust를 고른 이유 세 가지 — 상주 스케줄러의 안정성, OS 키체인 1급 지원, Electron 없이 배포되는 점 — 는 2년 회고에 결정 로그로 남아 있다. 저장소 열세 개를 혼자 굴리는 입장에서, 전환은 이벤트가 아니라 언제나 진행 중인 상태다. 그래서 결정 근거가 남아 있는 팀과 없는 팀의 차이가 시간이 갈수록 벌어진다.
두 이력 모두 원문 검증 표의 숫자를 대신할 실측은 아니다. 솔직하게 말하면 나는 전환마다 저 표를 값까지 채워 본 적이 없다. 그래서 표는 형식으로 남기고, 대신 근거가 되는 이력을 옆에 두는 방식으로 이 글을 썼다.
4. 전면 전환을 하지 않을 근거 — CSR→RSC 하이브리드 판단
프레임이 실제 판단을 어떻게 바꾸는지 범위 하나로 보자. 클라이언트 컴포넌트 중심 페이지를 서버 컴포넌트 혼합 구조로 옮기는 경우다.
- 상황: 데이터 로딩을 서버 컴포넌트로 일부 이동하고 싶다
- 제약: 검색 필터 UX와 공유 URL은 유지해야 한다
에이전트 초안은 데이터 페칭 경로 단순화, 번들 크기 감소 가능성, 중복 로딩 제거를 가져온다. 동시에 클라이언트 상호작용 지점 분리 실패, hydration mismatch, error boundary 범위 누락의 위험을 함께 가져온다.
리허설을 거치면 결정이 이렇게 바뀐다. 데이터 읽기는 RSC로 옮기고, 필터 상호작용은 클라이언트에 남기고, URL 동기화 계층은 기존 훅을 재사용한다. 즉 “전면 전환”이 아니라 하이브리드 전환. 제약을 먼저 고정했기 때문에 나올 수 있는 결정이고, 이 판단 자체가 리허설의 산출물이다. 전환의 성공 기준이 “다 옮겼다”가 아니라 “지켜야 할 것은 그대로다”로 바뀌는 순간, 이동 비율은 결정 요소가 아니게 된다.
5. 디자인 시스템 변경 — 3레인과 회귀 3분류
변경 안전성의 특수 케이스 하나를 더 남긴다. 디자인 시스템은 컴포넌트 API, 토큰 재매핑, 테마 분기, 접근성 속성이 한 변경에 섞여 들어오는 영역이라, 일반적인 마이그레이션보다 회귀의 종류가 많다.
먼저 두 번째 편의 계약을 변경 설명에 맞게 구체화한다.
## Design System Change Contract
- Scope:
- Non-goals:
- Backward compatibility:
- Accessibility acceptance criteria:
- Rollback condition:
그리고 AI 적용을 세 레인으로 분리한다.
- A 레인(기계적 치환) — 토큰명 변경, import 경로 통일
- B 레인(의미 변경) — 컴포넌트 prop 구조 개편
- C 레인(검증 자동화) — 스냅샷·시각회귀·E2E 보강
실무에서 가장 자주 나는 실패는 B 레인을 A 레인처럼 처리하는 것이다. prop 구조 개편은 기계적 치환이 아니라 의미 변경이므로, B 레인은 반드시 사람 리뷰 우선으로 운영한다.
회귀 탐지는 화면 단위와 상호작용 단위를 함께 본다. 화면별 시각 회귀, 키보드 탐색 흐름, 상태 변화(hover/focus/disabled/loading), 다국어와 긴 문자열 깨짐. 이때 실패 결과를 세 분류로 자동 태깅하게 하면 운영이 단순해진다 — token-mismatch(스타일 매핑 누락), interaction-regression(상호작용 퇴행), a11y-regression(접근성 퇴행). 시각 회귀를 결정적 diff와 AI 의미 비교로 이중화하는 구조는 첫 편에서 다뤘고, 접근성 항목의 정밀 체크는 회귀 체크리스트 글에 따로 정리해 두었다.
배포 게이트도 심각도 기반이다. 결제·인증·핵심 전환 퍼널의 interaction-regression는 차단, 비핵심 화면의 token-mismatch는 조건부 진행, 브랜드 가이드 허용 범위 내의 미세 불일치는 이슈로 기록한 뒤 진행한다. 모든 실패를 차단하면 팀 속도가 무너지고, 전부 허용하면 품질 시스템이 무너진다.
측정할 것이 있다면 이 세 개다. 변경 리드타임(첫 PR부터 배포 승인까지), 회귀 재오픈율(배포 후 7일 내 재발), 검증 자동화 커버리지(핵심 컴포넌트 중 자동 검증 연결 비율). 값은 직접 재야 하는 숫자고, 정의를 먼저 합의해 두는 게 할 일이다.
6. CFR — 변경 안전성의 결과 지표
마지막으로 이 모든 장치의 결과를 재는 지표. **변경 실패율(Change Failure Rate)**은 배포된 변경 중 실패로 이어진 비율이다. “빨리 만들었다”가 아니라 “안전하게 전달했다”를 증명하는 지표라고, 4월의 원문은 설명했다.
프론트엔드에서 쓰려면 DORA 정의를 팀 언어로 먼저 바꿔야 한다. 실패로 집계할 이벤트를 정의하는 것이다.
- 배포 후 24시간 내 핫픽스 PR 생성
- 문제 PR 롤백 또는 feature flag 강제 OFF
- Sentry/PagerDuty 기준 Sev2 이상 사용자 영향 이슈
- Core Web Vitals 급락으로 인한 긴급 재배포
반대로 실패로 보지 않는 것도 정해 둔다. 카피·문구의 경미 수정, 실험 플래그의 의도된 종료, 사용자 영향이 없는 내부 로그 보강. 핵심은 숫자가 아니라 합의다. 합의가 없으면 CFR은 숫자 싸움이 된다.
그리고 AI 변경을 분리 추적한다. 전체 CFR만 보면 AI의 영향이 묻히기 때문이다.
## 변경 작성 방식
- [ ] human-only
- [ ] ai-assisted
## AI 기여 범위
- [ ] 코드 생성
- [ ] 테스트 생성
- [ ] 리팩터링 제안
- [ ] 문서/릴리즈노트 보강
주간 리뷰는 네 칸짜리 표로 충분하다.
| 구분 | human-only | ai-assisted |
|---|---|---|
| 배포 건수 | ||
| 실패 건수 | ||
| CFR | ||
| 대표 실패 원인 |
원문의 이 표에도 숫자가 들어 있었다. 배포 건수와 실패 건수, CFR의 두 축 비교, 넉 달에 걸친 개선 서사까지 — 전부 가상 예시라 이 글에서는 값을 전부 뺐다. 측정한 적 없는 숫자를 지표로 인용하는 순간 기록이 아니라 소설이 되기 때문이다. 그래서 다시 쓰는 글만큼은 비워 두고 시작하는 게 맞다. 표의 값은 주간 리뷰를 돌리는 사람이 채우는 칸이다.
흥미로운 건 원문이 제안한 “CFR을 낮추는 가드레일 5단계”를 펼쳐 보면, 앞의 세 편이 그대로 나온다는 것이다. 생성 전 범위 상한은 두 번째 편의 Task Contract와 Do Not이고, 생성 중 증거 기반 리뷰는 같은 글의 리뷰 가드레일(근거 3요소)이고, 생성 후 릴리즈 게이트 이중화는 첫 편의 게이트 체계고, 배포 직후 관측은 세 번째 편의 48시간 루프다. 마지막 단계만 새로운데, 회고의 결론을 “프롬프트를 더 잘 쓰자”로 닫지 말고 입력 계약·PR 템플릿·게이트 기준의 수정으로 내리는 것이다. CFR은 결국 앞 세 편을 얼마나 돌리는지로 결정되는 수치다.
나 혼자 일할 때의 실천은 더 작다. 두 번째 편의 PR 템플릿에 이미 ‘AI 사용 범위’ 블록이 있다 — 초안 생성, 사람이 직접 수정, 반려한 제안. 이것이 태깅의 절반이다. 여기에 배포 결과(정상 배포인가, 핫픽스·롤백이었는가)만 붙이면 주간 표는 저절로 채워진다.
시작 체크리스트
다음 큰 변경을 만나면, 이 순서다.
- 페이지가 아니라 기능 단위로 범위를 자르고 제외 범위를 명시한다
- 에이전트에게 주는 건 요청이 아니라 금지 조건부터 쓴다
- 검증 표를 값 없이 먼저 만들고, 리허설에서 직접 측정해 채운다
- 배포/보류/부분 배포 기준을 숫자로 정한 뒤에 리허설을 돌린다
- PR마다 human-only/ai-assisted를 태깅해 다음 주간 리뷰의 재료로 쌓는다
남는 것
게이트가 배포 가능함을 증명하고, 계약이 품질을 고정하고, 런북이 장애를 감당한다면, 리허설은 그 셋을 큰 변경에 순서대로 배치하는 방법이었다. 두 번의 전환에서 확인한 것도 결국 같다. 새 것을 먼저 만들고, 증명되기 전에는 낡은 것을 내리지 않는다.
이 시리즈를 다시 쓰면서 네 편이 남긴 것은 기록이다. 게이트의 리포트, 계약의 위반 이력, 런북의 회고, 리허설의 결정 로그. 남은 질문은 하나 — 이 기록을 어떻게 나의 증거로 바꾸는가. 그게 이어지는 글의 주제다.