요약
이 글은 Claude Code를 사용하여 레거시 코드를 안전하게 리팩토링하는 방법에 대한 개인적인 경험과 워크플로우를 공유합니다. 핵심은 Claude Code를 무작정 사용하는 것이 아니라, 명확한 가이드라인과 검증 단계를 통해 리팩토링을 제어하는 것입니다.
- 특성 테스트를 통해 기존 코드의 동작을 먼저 파악하고 테스트 코드를 작성합니다.
- CLAUDE .md 파일을 설정하여 Claude에게 코드베이스의 아키텍처, 규칙, 금지 사항 등을 알려줍니다.
- 작은 단위로 점진적인 리팩토링을 수행하고, 각 단계마다 테스트를 실행하여 변경 사항을 검증합니다.
- CodeRabbit과 같은 AI 코드 리뷰 도구를 사용하여 테스트에서 놓친 잠재적인 문제를 발견합니다.
[서론]
이 글은 작성자가 Claude Code를 사용하여 5만 줄의 레거시 코드를 리팩토링한 경험을 공유하며, AI 에이전트 코딩을 활용한 워크플로우 개선에 대한 영감을 제공하는 것을 목표로 합니다. Claude Code를 사용하여 레거시 코드를 리팩토링할 때 흔히 발생하는 문제점을 지적하고, 성공적인 리팩토링을 위한 구체적인 단계를 제시합니다.
[레거시 리팩토링의 핵심 문제]
레거시 코드는 그린필드 프로젝트와 달리 명확한 스펙이 없고, 테스트가 부족하며, 오래된 코드가 프로덕션 환경에 배포되어 있어 변경 시 위험 부담이 큽니다. Claude Code는 강력하지만 코드의 의도를 이해하지 못하므로, 리팩토링 전에 기존 동작을 명확히 정의하는 것이 중요합니다.
[1단계: 특성 테스트]
Claude에게 리팩토링을 지시하기 전에 먼저 현재 코드베이스의 동작을 캡처하는 테스트를 작성합니다. "최소한의 pytest 특성 테스트를 생성하세요. 현실적인 입력에 대한 현재 출력을 캡처하는 데 집중하세요. 동작 변경은 없고, 현재 코드가 실제로 수행하는 작업을 문서화하세요."와 같은 프롬프트를 사용합니다. 이 테스트는 나중에 코드를 변경할 때 안전망 역할을 합니다.
[2단계: CLAUDE .md 파일 설정]
CLAUDE .md 파일은 Claude와의 모든 대화 시작 시 자동으로 로드되는 파일로, 프로젝트에 대한 지속적인 메모리 역할을 합니다. 레거시 리팩토링의 경우, Claude가 코드를 작성하는 방법뿐만 아니라 건드려서는 안 되는 부분도 이해해야 하므로 이 파일이 매우 중요합니다. /init 명령어를 사용하여 시작 파일을 자동 생성할 수 있지만, 리팩토링 작업을 위해서는 아키텍처 개요, 빌드 명령어, 리팩토링 가이드라인, 하드 규칙 등을 추가해야 합니다. 특히 '하드 규칙' 섹션은 변경해서는 안 되는 중요한 코드 영역을 명시하는 데 사용됩니다.
[3단계: 지속적인 검증을 통한 점진적인 리팩토링]
실제 리팩토링은 작고 구체적인 작업으로 나누어 점진적으로 수행합니다. "Invoice.process에서 할인 계산 로직을 별도의 메서드로 추출하세요.", "'usr'의 모든 인스턴스를 'user'로 이름을 바꾸세요."와 같은 프롬프트를 사용합니다. 각 변경 후에는 특성 테스트를 실행하여 변경 사항을 검증합니다. 테스트가 통과되면 커밋하고 다음 단계로 진행하고, 실패하면 디버깅합니다.
[4단계: CodeRabbit을 통한 보완]
테스트를 통과하더라도 보안 문제, 성능 저하, 미묘한 논리 오류 등 놓치는 부분이 있을 수 있습니다. CodeRabbit은 AI 코드 리뷰 도구로, 40개 이상의 분석기를 실행하여 일반적인 린터에서 놓치는 문제를 발견합니다. CodeRabbit 리뷰를 통해 SQL 인젝션 취약점과 같은 심각한 문제를 사전에 방지할 수 있습니다.
[한계점]
Claude Code는 20만 토큰 제한이 있으며, 성능은 그 전에 저하될 수 있습니다. 큰 리팩토링의 경우, 진행 상황, 결정 사항, 다음 단계를 요약한 핸드오프 문서를 사용하여 컨텍스트를 유지합니다. Claude가 존재하지 않는 API를 사용하는 경우도 발생할 수 있으며, 복잡한 아키텍처 결정은 여전히 사람이 판단해야 합니다.
[결론]
Claude Code를 강력한 도구로 활용하고 명확한 가이드라인을 따르면 3개월 걸릴 작업을 3주 만에 완료할 수 있습니다. 특성 테스트 작성, CLAUDE .md 파일 설정, 점진적인 리팩토링, CodeRabbit과 같은 AI 코드 리뷰 도구 사용, 그리고 모든 변경 사항을 직접 검토하는 것이 중요합니다.
