[Claude Code 실전 정복 #6] 레거시 코드 리팩토링을 AI한테 맡겨봤더니 — 2,000줄짜리 파일이 이렇게 됐어요

cherryplan 프로젝트 초기 코드를 다시 열었을 때 솔직히 눈을 감고 싶었어요.

2024년 초에 급하게 짠 utils.js 하나에 함수가 47개였어요. 인증 로직이랑 날짜 포맷팅이랑 API 호출 헬퍼가 전부 한 파일에 섞여 있었고, 주석은 "나중에 정리하자"라고 써놓은 채로 6개월이 지나 있었어요. 새 기능 붙일 때마다 "어디 있더라?" 검색하는 시간만 5~10분씩 나갔어요. 파일 하나 건드리면 연결된 다른 곳에서 터지는 것도 반복됐고요.

리팩토링 해야 한다는 건 알았는데 타이밍을 못 잡고 있었어요. 이걸 어디서부터 건드려야 하는지 감이 안 잡히는 것도 있었고, 혼자 2,000줄 분석하고 재구성할 엄두가 안 났던 것도 솔직히 있어요.

Claude Code한테 맡겨봤어요. 그냥 파일 던지고 "분석해줘"라고 했는데 결과가 예상을 넘었어요.

---

Claude Code한테 리팩토링 어떻게 시켰냐면

막연하게 "리팩토링해줘"라고 하면 Claude Code도 방향을 못 잡아요. 제가 실제로 쓴 프롬프트는 이랬어요.

이 파일 전체 분석해줘.
- 함수 목록이랑 각 함수가 하는 역할 정리해줘
- 관심사 기준으로 어떻게 분리할 수 있는지 제안해줘
- 실제로 어떤 파일로 나눌지 구조 잡아줘
- 리팩토링하면서 기존 import 경로 깨지지 않게 해줘

Claude Code가 먼저 파일 전체를 읽고 함수 47개를 이렇게 분류해줬어요.

분류 결과:
- auth/ → 인증 관련 함수 11개 (토큰 처리, 권한 체크)
- date/ → 날짜/시간 포맷 함수 8개
- api/ → API 호출 헬퍼 함수 14개
- validation/ → 유효성 검사 함수 9개
- format/ → UI 표시용 포맷 함수 5개
- 분류 애매한 것 → 별도 검토 필요 5개 (같이 결정하자고 물어봄)

실제로 써보니 이 분류 단계가 핵심이었어요. 저 혼자였으면 함수 목록 정리하는 데만 30분은 썼을 텐데, Claude Code가 5초 만에 읽고 바로 뱉어줬어요. "분류 애매한 것"은 같이 결정하자고 역으로 물어봐서 오히려 더 신뢰가 갔어요.

---

실제 리팩토링 진행 과정

분류 확인 후 이렇게 지시했어요.

auth 폴더부터 시작해줘.
- 기존 utils.js에서 인증 함수 11개 추출해서 auth/index.js로 만들어줘
- utils.js에 남겨둔 export도 유지해줘 (기존 import 안 깨지게)
- 테스트 있는 함수는 테스트 경로도 업데이트해줘

Claude Code가 실제로 진행한 순서예요.

# Claude Code 실행 로그 (실제)
Reading utils.js... (2,847 tokens)
Extracting auth functions: 11 found
Creating auth/index.js
Creating auth/tokenHelper.js
Updating utils.js (re-exporting from auth/)
Checking for test files... found utils.test.js
Updating import paths in utils.test.js
Done. 0 breaking changes detected.

실제로 써보니 "0 breaking changes detected" 이게 제일 안심됐어요. 기존 코드 어디서도 import 경로 안 바꾸고 리팩토링이 완료된 거예요. 한 폴더씩 확인하면서 진행하니까 중간에 뭔가 이상하다 싶으면 바로 잡을 수 있었고요.

---

실전 활용 — 이런 프롬프트가 잘 먹혔어요

리팩토링 과정에서 효과적이었던 프롬프트 패턴 몇 가지예요.

함수 중복 찾기

이 파일에서 비슷한 역할을 하는 함수들 찾아줘.
중복 로직 있으면 통합할 수 있는 것들 알려줘.

네이밍 개선

이 함수들 이름이 역할을 잘 설명하는지 검토해줘.
더 명확한 이름 있으면 제안해줘. 기존 이름이랑 새 이름 같이 보여줘.

의존성 파악

이 함수가 어디서 호출되는지 프로젝트 전체에서 찾아줘.
영향 받는 파일 목록 뽑아줘.

마지막 프롬프트가 특히 유용했어요. 리팩토링할 때 제일 무서운 게 "이거 어디서 쓰는지 몰라서 건드리기 무섭다"인데, Claude Code가 프로젝트 전체 grep해서 호출 위치 다 뽑아줬어요.

---

솔직한 한계

다 좋은 건 아니에요.

비즈니스 로직은 직접 판단해야 해요. Claude Code가 함수를 분류할 때 "이게 auth 쪽인지 validation 쪽인지 애매하다"고 물어보는 경우가 있어요. 이건 코드 문맥이 아니라 서비스 구조를 알아야 판단할 수 있는 거라서, 결국 사람이 결정해야 해요. Claude Code는 선택지를 주고 기다리지, 멋대로 결정하지 않아요.

복잡한 의존성 체인은 한 번에 안 돼요. A가 B를 쓰고 B가 C를 쓰고 C가 다시 A를 참조하는 순환 의존성 있는 코드는 Claude Code도 "이 구조 먼저 정리해야 한다"고 플래그만 달아줘요. 해결은 같이 단계 나눠서 해야 해요.

컨텍스트 창 한계. 파일이 너무 크면 (5,000줄 이상) 한 번에 못 읽어요. 이럴 땐 섹션 나눠서 넘겨줘야 해요.

---

마무리

utils.js 한 파일 리팩토링하는 데 혼자 했으면 이틀은 잡았을 거예요. Claude Code랑 같이 하니까 반나절이었어요. 그것도 중간에 밥 먹고 커피 마시면서요.

더 중요한 건 시간보다 심리적 진입 장벽이에요. "2,000줄짜리 건드렸다가 뭔가 터지면 어떡하지"라는 두려움이 사라진 게 제일 커요. Claude Code가 영향 범위 파악하고, breaking change 체크하고, 단계별로 진행하니까 리팩토링이 무서운 작업이 아니라 그냥 할 수 있는 작업이 됐어요.

레거시 코드 보기 싫어서 미루고 있던 분들, 그냥 파일 던지고 "분석해줘"부터 시작해보세요.

 

다음 포스팅 예고: [Claude Code 실전 정복 #7] Claude Code로 테스트 코드 짜기 — 커버리지 0%에서 시작한 이야기