AI 에이전트에게 리팩터링을 맡기면 가장 먼저 좋아 보이는 것은 속도입니다. 파일 이름을 바꾸고, 중복 함수를 합치고, 컴포넌트를 나누고, 타입을 정리하는 작업이 몇 분 안에 진행됩니다. 하지만 실무에서 리팩터링의 성공 기준은 빨리 바꿨느냐가 아니라, 문제가 생겼을 때 안전하게 되돌릴 수 있느냐입니다.

초보자에게 리팩터링은 '코드를 더 깔끔하게 만드는 일'처럼 보입니다. 맞는 말이지만 충분하지 않습니다. 운영 중인 서비스에서는 깔끔함보다 더 중요한 조건이 있습니다. 사용자가 보던 기능이 그대로 동작해야 하고, 변경 범위가 리뷰 가능한 크기여야 하며, 배포 후 이상 신호가 보이면 빠르게 원래 상태로 돌아갈 수 있어야 합니다. AI 리팩터링은 이 조건을 의식하지 않으면 깔끔하지만 위험한 대량 변경이 되기 쉽습니다.

핵심 결론

AI 리팩터링은 '크게 고치고 나중에 확인'하는 방식이 아니라 '작은 변경 단위마다 롤백 기준과 검증 증거를 남기는 방식'으로 운영해야 합니다. 핵심은 세 가지입니다.

1. 변경 단위를 작게 자릅니다. 한 번에 구조, 이름, 동작, 스타일을 모두 바꾸지 않습니다.
2. 테스트 고정을 먼저 합니다. 현재 동작을 보존해야 하는 지점을 테스트나 스모크 절차로 잠급니다.
3. 롤백 기준을 미리 씁니다. 어떤 신호가 보이면 되돌릴지, 무엇을 되돌릴지, 되돌린 뒤 무엇을 확인할지 정합니다.

핵심 포인트: AI가 리팩터링을 잘하는지 묻기 전에, 그 리팩터링을 사람이 리뷰하고 롤백할 수 있는 작업 단위로 만들었는지 먼저 확인해야 합니다.

왜 중요한가

리팩터링은 동작을 바꾸지 않는 척하지만 실제로는 위험하다

리팩터링의 정의는 외부 동작을 유지하면서 내부 구조를 개선하는 것입니다. 그러나 AI 에이전트는 '구조 개선' 요청을 받으면 주변 코드를 넓게 읽고 더 좋아 보이는 방향으로 함께 고치려는 경향이 있습니다. 변수 이름 변경이 데이터 매핑 변경으로 이어지고, 컴포넌트 분리가 렌더 조건 변경으로 이어지고, 공통 함수 추출이 예외 처리 변경으로 이어질 수 있습니다.

사람이 직접 작업할 때도 이런 실수는 생기지만, AI는 속도가 빠르기 때문에 변경량이 순식간에 커집니다. 변경량이 커질수록 리뷰어는 어느 줄이 안전한 정리이고 어느 줄이 실제 동작 변경인지 구분하기 어려워집니다. 그래서 AI 리팩터링의 첫 번째 목표는 멋진 구조가 아니라 검토 가능한 크기를 유지하는 것입니다.

롤백 가능성은 배포 후 신뢰를 만든다

운영 환경에서는 '테스트가 통과했으니 절대 문제없다'고 말할 수 없습니다. 테스트는 중요한 증거지만 모든 사용자 경로와 데이터를 대신하지는 못합니다. 따라서 배포 전부터 롤백 기준을 정해야 합니다. 예를 들어 결제 시작률, 회원가입 완료율, 주요 페이지 오류율, 응답 시간, 브라우저 콘솔 오류 같은 관찰 지표가 일정 수준 이상 흔들리면 되돌린다고 정해 둡니다.

이 기준이 있으면 배포 후 판단이 빨라집니다. 문제가 생긴 뒤 회의로 해석을 시작하는 것이 아니라, 미리 합의한 조건에 따라 즉시 되돌릴 수 있습니다. AI가 만든 변경일수록 이런 운영 기준이 더 중요합니다. 사람이 모든 세부 의도를 기억하지 못하기 때문입니다.

실제 작업 순서

1단계: 목표를 '구조 개선'이 아니라 보존할 동작으로 쓴다

나쁜 요청은 '이 파일 리팩터링해줘'입니다. 너무 넓고, 보존해야 할 동작이 없습니다. 좋은 요청은 이렇게 씁니다.

• 결제 버튼의 사용자 동작은 바꾸지 않는다.
• 중복된 가격 표시 로직만 공통 함수로 옮긴다.
• 기존 테스트가 없다면 가격 포맷과 비로그인 안내 동작을 먼저 테스트로 고정한다.
• 변경 후 git diff를 보고 동작 변경이 섞였는지 설명한다.

이렇게 쓰면 AI는 리팩터링의 성공 기준을 구조가 아니라 보존된 동작으로 이해합니다. 초보자라면 '무엇을 절대 바꾸면 안 되는지'를 먼저 적는 습관부터 들이면 됩니다.

2단계: 테스트 고정으로 현재 동작을 잠근다

기존 테스트가 충분하면 그 테스트를 먼저 실행합니다. 부족하면 리팩터링 전에 작은 회귀 테스트를 추가합니다. 테스트 이름은 구현 방식이 아니라 사용자에게 보이는 결과를 설명해야 합니다. 예를 들어 'formatPrice가 호출된다'보다 '원화 가격은 천 단위 쉼표와 원 단위로 보인다'가 낫습니다.

테스트 고정의 목표는 완벽한 테스트 스위트를 만드는 것이 아닙니다. 이번 리팩터링이 건드릴 수 있는 핵심 동작을 최소한으로 잠그는 것입니다. AI에게는 다음 순서로 지시합니다.

1. 바꾸려는 코드가 영향을 줄 사용자 동작을 2~3개만 고른다.
2. 그 동작을 테스트로 먼저 표현한다.
3. 테스트가 통과하는 현재 기준선을 확인한다.
4. 그다음 구조 변경을 시작한다.

3단계: 변경 단위를 리뷰 가능한 크기로 제한한다

한 커밋에 이름 변경, 파일 이동, 로직 변경, 스타일 변경이 섞이면 리뷰 난이도가 급격히 올라갑니다. AI 리팩터링에서는 특히 변경 단위를 제한해야 합니다. 한 번의 작업은 다음 중 하나만 목표로 잡는 것이 안전합니다.

작업 후에는 git diff를 반드시 읽습니다. AI에게 '의도한 변경'과 '부수 변경'을 나눠 설명하게 하면 리뷰가 쉬워집니다. 부수 변경이 많으면 통과시키지 말고 더 작은 단위로 다시 나눕니다.

4단계: 배포 전 롤백 기준을 기록한다

롤백 기준은 긴 문서가 아니어도 됩니다. 작업 설명이나 커밋 메시지에 다음 세 가지가 있으면 충분합니다.

• 되돌릴 신호: 오류율 증가, 핵심 전환율 하락, 특정 페이지 렌더 실패, 고객 문의 증가 등
• 되돌릴 범위: 이번 커밋만 되돌릴지, 기능 플래그를 끌지, 이전 배포로 돌릴지
• 되돌린 뒤 확인: 같은 테스트, 주요 페이지 스모크, 관찰 지표 회복 여부

기능 플래그가 있는 기능이라면 구조 변경과 노출 변경을 분리하는 것이 좋습니다. 먼저 내부 구조를 바꾸되 기존 경로를 유지하고, 새 경로는 기능 플래그 뒤에 둡니다. 그러면 문제가 생겼을 때 전체 코드를 되돌리지 않고 플래그를 끄는 선택지가 생깁니다.

상황별 예시

예시 1: 중복된 가격 표시 함수를 합치기

초보자가 보기에는 같은 코드가 여러 곳에 있으니 하나로 합치면 좋아 보입니다. 하지만 가격 표시는 통화, 소수점, 할인, 무료 표시 같은 예외가 많습니다. AI에게 바로 '공통화해줘'라고 하면 일부 화면에서 문구가 달라질 수 있습니다.

안전한 순서는 이렇습니다. 먼저 상품 카드, 결제 요약, 영수증 화면에서 가격이 어떻게 보여야 하는지 테스트 고정을 합니다. 그다음 한 종류의 포맷만 공통 함수로 옮깁니다. 마지막으로 git diff에서 텍스트 변경과 계산 변경이 섞였는지 확인합니다. 계산 변경이 보이면 리팩터링 범위를 넘어선 것이므로 별도 작업으로 분리합니다.

예시 2: 거대한 페이지 컴포넌트 나누기

큰 페이지 컴포넌트를 작은 컴포넌트로 나누는 작업은 AI가 잘하는 편입니다. 그러나 상태와 조건부 렌더링까지 함께 옮기면 사용자가 보는 화면이 바뀔 수 있습니다. 처음에는 표시 전용 영역부터 분리합니다. 예를 들어 헤더 카드, 빈 상태 안내, 하단 도움말처럼 입력과 출력이 단순한 부분부터 시작합니다.

이때 변경 단위는 '컴포넌트 하나 추출'입니다. 추출 후 npm run lint, npm run build, npm test를 실행하고, 대표 페이지를 열어 시각적으로 확인합니다. 이상이 없으면 다음 컴포넌트로 넘어갑니다. 여러 컴포넌트를 한 번에 추출하면 어떤 추출이 문제를 만들었는지 찾기 어렵습니다.

예시 3: 데이터 호출 경로 정리하기

데이터 호출 코드를 정리할 때는 더 조심해야 합니다. 함수 이름만 바꾸는 것처럼 보여도 캐시, 재시도, 에러 처리, 빈 데이터 처리 방식이 달라질 수 있습니다. 이 경우에는 관찰 지표를 더 명확히 둡니다. 배포 후 주요 페이지의 응답 시간, 오류 응답, 빈 목록 비율을 봅니다.

가능하다면 새 호출 경로를 기능 플래그 뒤에 두고 일부 경로에서만 검증합니다. 플래그를 끄면 기존 경로로 돌아가게 만들면 롤백 비용이 낮아집니다. 이런 구조는 초기에 조금 번거롭지만, 운영 중인 서비스에서는 대량 되돌림보다 훨씬 안전합니다.

실수와 주의점

'정리하면서 개선'을 허용하지 않는다

리팩터링 중 가장 흔한 실수는 '이왕 하는 김에'입니다. 이름을 바꾸는 김에 조건을 단순화하고, 컴포넌트를 나누는 김에 문구를 바꾸고, 타입을 정리하는 김에 에러 처리를 바꾸는 식입니다. 이런 변경은 각각은 좋아 보이지만 한 작업에 섞이면 롤백이 어려워집니다. 문제가 생겼을 때 무엇을 되돌려야 하는지 불명확해지기 때문입니다.

AI에게는 명시적으로 말해야 합니다. '이번 작업은 동작 변경을 하지 않는다. 동작 변경이 필요해 보이면 코드에 반영하지 말고 별도 제안으로만 남긴다.' 이 한 문장이 변경 범위를 크게 줄입니다.

테스트 통과를 롤백 불필요와 혼동하지 않는다

npm run lint, npm run build, npm test가 모두 통과해도 롤백 계획은 필요합니다. 테스트는 배포 전 검증이고, 롤백은 배포 후 대응입니다. 둘은 서로 대체하지 않습니다. 특히 리팩터링은 테스트가 놓친 실제 데이터 조합에서 문제가 생길 수 있습니다.

따라서 배포 전에는 반드시 관찰 지표와 스모크 경로를 정합니다. 예를 들어 홈, 목록, 상세, 핵심 전환 버튼처럼 사용자가 자주 지나는 길을 확인합니다. 배포 후 그 경로에서 오류가 보이면 즉시 되돌릴 준비가 되어 있어야 합니다.

큰 diff를 AI 설명만 믿고 넘기지 않는다

AI가 '동작 변경은 없습니다'라고 말해도 git diff는 사람이 읽어야 합니다. 특히 조건문, 기본값, 정렬, 필터, 날짜 계산, 권한 체크가 바뀐 줄은 리팩터링이 아니라 동작 변경일 가능성이 높습니다. 리뷰어는 이런 줄에 표시를 남기고, 정말 필요한 변경이면 별도 테스트와 별도 커밋으로 분리해야 합니다.

검증 체크리스트

배포 전에는 다음 순서로 확인합니다.

• 변경 단위: 한 작업이 하나의 목적만 갖고 있는가?
• 테스트 고정: 보존해야 할 사용자 동작이 테스트나 스모크 절차로 잡혀 있는가?
• diff 점검: git diff에서 조건문, 데이터 매핑, 기본값 변경이 의도 없이 섞이지 않았는가?
• 정적 검증: npm run lint가 통과했는가?
• 빌드 검증: npm run build가 통과했는가?
• 회귀 검증: npm test가 통과했는가?
• 롤백 기준: 어떤 관찰 지표가 흔들리면 되돌릴지 적었는가?
• 배포 전 스모크: 사용자가 자주 지나는 페이지와 핵심 버튼을 직접 확인했는가?
• 배포 후 관찰: 오류율, 응답 시간, 핵심 전환 흐름을 일정 시간 확인했는가?

이 체크리스트는 길어 보이지만 실제로는 작업을 작게 나누면 빠르게 끝납니다. 반대로 작업을 크게 만들면 체크리스트가 부담스러워지고, 그 부담 때문에 검증을 생략하게 됩니다. 그래서 가장 중요한 검증 전략은 처음부터 변경 단위를 작게 만드는 것입니다.

다음 단계

처음부터 완벽한 리팩터링 시스템을 만들 필요는 없습니다. 다음 작업에서 바로 적용할 수 있는 시작점은 세 가지입니다.

1. AI에게 리팩터링을 맡기기 전에 '바꾸면 안 되는 동작'을 세 줄로 적습니다.
2. 변경 후에는 git diff를 기준으로 의도한 변경과 부수 변경을 나눠 설명하게 합니다.
3. 배포 전에 롤백 기준과 배포 후 관찰 지표를 한 문단으로 남깁니다.

팀에서 반복한다면 리팩터링 템플릿을 만들어 두면 좋습니다. 템플릿에는 목표, 변경 단위, 테스트 고정, 검증 명령, 롤백 기준, 관찰 지표가 들어갑니다. 이렇게 하면 AI 에이전트는 단순히 코드를 고치는 도구가 아니라, 안전한 변경 절차를 따르는 실행자로 바뀝니다.

AI 리팩터링의 성패는 모델이 얼마나 똑똑한지보다 운영자가 얼마나 작은 단위로 일을 나누고, 어떤 증거로 안전하다고 판단하며, 언제 되돌릴지 정해 두었는지에 달려 있습니다. 속도는 AI가 줍니다. 신뢰는 운영 절차가 만듭니다.