롤백 가능한 AI 리팩터링

AI 에이전트에게 리팩터링을 맡길 때 가장 위험한 것은 모델이 코드를 못 쓰는 상황이 아닙니다. 큰 diff를 한 번에 만들고, 그 diff가 왜 안전한지 증명하지 못하는 상황이 더 위험합니다. 코드가 그럴듯해 보여도 사용자 동작이 바뀌었는지, API 응답이 깨졌는지, 사이드 이펙트가 생겼는지 확인하지 않으면 리팩터링은 개선이 아니라 장애가 됩니다.

이 글의 결론은 간단합니다. AI 리팩터링은 작게 나누고, 테스트로 고정하고, 언제든 되돌릴 수 있게 끝내야 합니다. AI에게 "이 파일 정리해줘"라고 맡기는 대신, 어떤 동작은 보존해야 하는지, 어떤 파일은 건드리지 말아야 하는지, 어떤 검증을 통과해야 완료인지 먼저 적어야 합니다.

핵심 결론 먼저

롤백 가능한 AI 리팩터링은 다섯 단계로 굴립니다.

핵심은 리팩터링과 기능 변경을 섞지 않는 것입니다. 리팩터링은 겉으로 보이는 동작을 유지한 채 내부 구조를 바꾸는 작업입니다. 기능 요구사항까지 같이 넣으면 테스트가 실패했을 때 원인이 구조 변경인지 기능 변경인지 알 수 없습니다.

리팩터링과 기능 변경을 먼저 분리한다

AI에게 "코드를 깔끔하게 고쳐줘"라고 말하면 모델은 보통 더 많은 일을 하려 합니다. 변수명 변경, 함수 추출, 타입 정리, 중복 제거, 에러 처리 개선, UI 문구 수정까지 한 diff에 섞일 수 있습니다. 사람에게는 성실해 보이지만 운영 관점에서는 나쁜 결과입니다.

작업 지시서는 먼저 다음 질문에 답해야 합니다.

• 사용자에게 보이는 동작을 바꿀 것인가?
• API 응답 구조를 바꿀 것인가?
• DB 스키마나 저장 포맷을 바꿀 것인가?
• 테스트 기대값을 바꿀 것인가?
• 성능 최적화까지 포함할 것인가?

이 중 하나라도 예라면 그것은 순수 리팩터링이 아닙니다. 별도 작업으로 쪼개야 합니다. 순수 리팩터링의 목표는 더 나은 구조이지, 새로운 동작이 아닙니다.

전체 작업 흐름

작업 흐름은 단순해야 합니다.

1. 관련 파일과 테스트를 찾습니다.
2. 현재 동작을 테스트 또는 smoke로 고정합니다.
3. 변경 범위를 한 문장으로 제한합니다.
4. AI에게 작은 diff만 만들게 합니다.
5. targeted test를 실행합니다.
6. diff를 사람이 읽고 의도 밖 변경을 제거합니다.
7. 실패 기준과 되돌리기 기준을 보고서에 남깁니다.

이 흐름의 목적은 AI를 느리게 만드는 것이 아닙니다. AI가 빠르게 만든 결과를 사람이 판단 가능한 크기로 줄이는 것입니다.

작은 diff를 만든다

작은 diff란 줄 수가 적다는 뜻만은 아닙니다. 리뷰어가 의도를 한 번에 설명할 수 있는 diff가 작은 diff입니다.

리뷰 기준은 다음처럼 잡습니다.

• 파일 수가 1~3개를 넘지 않는다.
• 변경 이유가 하나다.
• 테스트 기대값이 바뀌지 않는다.
• public API, URL, DB 필드, 환경 변수는 건드리지 않는다.
• 포맷팅만 바뀐 줄과 실제 로직 변경 줄이 섞이지 않는다.

AI가 만든 diff가 이 기준을 넘으면 바로 되돌리고 다시 지시합니다. "이미 만들었으니 이어서 정리하자"는 방식이 가장 위험합니다. 큰 diff를 고치느라 더 큰 diff가 생깁니다.

targeted test로 확인한다

전체 테스트를 매번 돌리는 것은 느립니다. 그렇다고 테스트를 생략하면 리팩터링이 아니라 감으로 하는 코드 수정입니다.

테스트가 실패하면 AI에게 바로 "고쳐"라고 하지 않습니다. 먼저 실패가 리팩터링 때문인지, 기존 flaky인지, 테스트 기준이 잘못됐는지 나눕니다. 같은 파일을 3회 수정해도 같은 테스트가 실패하면 중단하고 사람 검토로 넘기는 편이 안전합니다.

롤백 기준을 먼저 적는다

롤백은 실패의 인정이 아닙니다. 사용자 영향을 줄이는 정상 운영 절차입니다.

리팩터링 전에는 다음 기준을 미리 적어 둡니다.

• 어떤 테스트가 실패하면 즉시 되돌릴 것인가?
• 어떤 파일이 예상 밖으로 바뀌면 중단할 것인가?
• 배포 후 어떤 오류가 늘면 롤백할 것인가?
• 되돌릴 커밋이나 이전 JSON 원본은 어디에 있는가?
• 롤백 후 확인할 live smoke 경로는 무엇인가?

이 기준이 없으면 문제가 생겼을 때 "조금만 더 고쳐보자"가 반복됩니다. AI 운영에서는 그 시간이 비용과 위험을 동시에 키웁니다.

상황별 운영 예시

중복 helper 제거

목표는 중복 제거입니다. 테스트 기대값은 바꾸지 않습니다. AI에게는 중복 함수 후보를 먼저 찾게 하고, 실제 수정은 한 helper만 대상으로 제한합니다. 완료 후 해당 helper를 쓰는 테스트만 먼저 돌리고, 마지막에 관련 페이지 smoke를 봅니다.

컴포넌트 props 정리

UI 결과가 바뀌면 안 됩니다. 먼저 대표 화면 screenshot 또는 DOM 텍스트 기준을 잡습니다. props 이름 변경은 내부 컴포넌트에만 제한하고, 외부 import 경로는 유지합니다. 화면 캡처가 바뀌면 의도한 변경인지 확인하기 전까지 배포하지 않습니다.

AI에게 줄 프롬프트 템플릿

이 작업은 순수 리팩터링입니다. 사용자에게 보이는 동작, API 응답, DB 스키마, URL, 환경 변수는 바꾸지 않습니다. 먼저 관련 파일과 테스트를 찾고, 현재 동작을 고정할 최소 검증 명령을 제안하세요. 수정은 한 가지 이유로만 진행하고, 파일 수는 최소화하세요. 변경 후 targeted test와 git diff 검토 결과를 보고하세요. 예상 밖 파일이 바뀌거나 같은 테스트가 3회 실패하면 중단하고 사람 검토를 요청하세요.

이 프롬프트의 핵심은 무엇을 하라보다 무엇을 하지 말라가 분명하다는 점입니다. AI 리팩터링은 금지 범위가 선명할수록 안전합니다.

최종 체크리스트

• 현재 동작을 고정하는 테스트나 smoke가 있는가?
• 변경 이유가 하나인가?
• 파일 수와 diff 크기가 리뷰 가능한가?
• API, DB, URL, 환경 변수 같은 공개 계약을 건드리지 않았는가?
• targeted test가 통과했는가?
• 롤백 기준과 되돌릴 지점이 기록됐는가?
• 완료 보고에 변경 파일, 검증 결과, 남은 위험이 포함됐는가?

마무리

AI 리팩터링은 사람보다 빠르게 구조를 바꿀 수 있습니다. 하지만 빠른 변경이 곧 안전한 변경은 아닙니다. 작은 diff, 테스트 기준선, 명확한 롤백 조건이 있어야 AI의 속도가 운영 품질로 바뀝니다.

좋은 리팩터링은 독자가 알아차리지 못합니다. 사용자는 같은 기능을 쓰지만, 운영자는 더 읽기 쉽고 고치기 쉬운 코드를 갖게 됩니다. 그 상태로 끝났다면 AI 리팩터링은 성공입니다.