Claude Code로 코드 리팩터링하는 방법
코딩 에이전트는 짧은 시간 안에 많은 코드를 구현하는 데 뛰어납니다. 하지만 코딩 에이전트를 많이 사용해 본 사람이라면 어느 순간부터 에이전트가 점점 힘들어하는 것을 눈치챌 수 있습니다. AI와 함께 며칠 동안 코드를 작성했을 때는 모든 것이 완벽하고 빠르게 진행되지만, 점점 작업 시간이 길어지고 실수가 늘어나는 것을 느끼게 됩니다.
이는 코드 리팩터링을 시작해야 한다는 명확한 신호입니다. 코딩 에이전트와 함께 많은 코드를 구현한 뒤에는 코드베이스를 리팩터링하는 것이 표준이 될 것이라고 생각합니다. 코딩 에이전트는 실수를 하고 완벽한 코드를 작성하지 못합니다. 또한 기존 코드에서 모범 사례를 따르지 않으면 AI도 새로운 코드를 생성할 때 모범 사례를 따르지 않게 됩니다. 따라서 레포지토리를 지속적으로 리팩터링해야 합니다.
이 글에서는 언제 코드를 리팩터링해야 하는지, 어떤 신호를 찾아야 하는지, 그리고 Claude Code 혹은 다른 코딩 에이전트를 사용해 효과적으로 리팩터링하는 방법을 논의합니다.
이 인포그래픽은 본 글의 주요 내용을 강조합니다. 저는 Claude Code 또는 다른 코딩 에이전트를 사용해 코드를 리팩터링하는 방법을 설명할 것입니다. 왜 리팩터링이 필요한지, 언제 리팩터링을 해야 하는지, 어떤 신호를 찾아야 하는지, 그리고 코드를 효과적으로 리팩터링하는 방법을 단계별로 안내합니다. 마지막으로 코드 리팩터링이 왜 중요한지, 이를 통해 코딩 에이전트가 코드 레포지토리에서 구현 작업을 훨씬 더 효율적으로 수행할 수 있게 되는지를 강조합니다. 이미지 출처: ChatGPT.
코드 리팩터링이 왜 필요할까?
우선 제가 다루는 주제에 왜 관심을 가져야 하는지 설명하고 싶습니다. 리팩터링은 지루한 작업처럼 들리지만, 실제로는 가끔씩 해야 하는 매우 지루한 작업이었습니다. 몇 년 전만 해도 사람들은 직접 레포지토리 안으로 들어가 리팩터링이 필요한 부분을 찾아 코드를 수정해야 했습니다.
보통 이런 작업은 코드에 많은 구현이 이루어진 직후 한 번 발생합니다. 코드는 사람이나 AI가 계속해서 수정하고 작업하면서 자연스럽게 완벽한 상태에서 더 복잡하고 어수선한 상태로 흐트러지기 때문입니다. 인간이든 AI 에이전트든 코드베이스를 다루면 언제든 이런 현상이 일어납니다.
코드가 어수선해지면 구현에 더 많은 시간이 걸리고 오류가 발생할 확률이 높아지기 때문에 리팩터링이 필요합니다.
구체적인 예를 들어 보겠습니다. 여러분의 애플리케이션에 사용자가 AI 봇에게 메시지를 보내고 응답을 받는 챗봇 기능이 있다고 가정해 보세요. 이는 기본적으로 AI 응답과 사용자 응답을 보여주는 채팅 박스 필드입니다. 좋은 코드베이스라면 Chat이라는 단일 컴포넌트를 만들어 앱 전역에서 동일하게 사용합니다. 반면 설계가 부실한 코드베이스는 앱 내 각 위치마다 별도의 채팅 컴포넌트를 가지고 있습니다.
이제 채팅 인터페이스의 색상이나 AI 아이콘을 바꾸고 싶다고 하면, 좋은 코드베이스에서는 중앙에 정의된 하나의 컴포넌트만 수정하면 되지만, 부실한 코드베이스에서는 여러 곳을 일일이 수정해야 합니다.
잘 작성된 코드는 한 곳만 수정하면 되므로 구현이 훨씬 쉬워지고 오류 가능성도 크게 줄어듭니다. 이것이 바로 리팩터링이 중요한 이유입니다.
언제 코드베이스를 리팩터링해야 할까
먼저 코드베이스를 리팩터링해야 하는 시점과 찾아야 할 신호에 대해 설명합니다.
간단히 말해, 코딩 에이전트가 구현 속도가 느려지고 버그를 더 많이 만들어내기 시작하면 리팩터링을 해야 합니다. 예상치 못한 위치에서 문제가 발생하거나, 직접 건드리지 않은 코드에서 오류가 나타난다면 이는 리팩터링이 필요하다는 명확한 신호입니다.
또한 가능한 한 빨리 리팩터링을 시작하는 것이 좋습니다. 물론 리팩터링이 필요한 코드를 다루는 것은 시간이 더 걸리고 오류 위험도 높아지지만, 그 과정에서 에이전트가 지시한 대로 코드를 수정하지 못하는 상황에 좌절감을 느끼게 됩니다.
리팩터링이 필요해지는 정확한 시점은 정해져 있지 않습니다. 특정 일수나 코드 라인 수가 기준이 되는 것이 아니라, 레포지토리에 작업이 많이 쌓일수록 자연스럽게 나타나는 현상입니다.
제 생각에는 작은 코드 조각이 이상적인 상태에서 조금씩 벗어나기 시작하고, 그 영역에 대한 추가 작업이 누적되면서 그 편차가 증폭되기 때문입니다. 시간이 지나면 코딩 에이전트나 인간 모두 해당 부분에서 효율적으로 코드를 작성하기 어려워집니다.
가능하면 이런 상황을 피하고 싶겠지만, 리팩터링을 완전히 없애려는 목표는 비현실적입니다. 리팩터링은 코드베이스 진화의 자연스러운 일부이며, 가끔씩은 반드시 수행해야 한다는 점을 받아들이고, 언제 시작해야 할지에 대한 신호를 인지하는 것이 중요합니다.
Claude Code로 코드 리팩터링하기
이제 언제 리팩터링해야 하는지 알았으니, Claude Code(또는 선호하는 다른 코딩 에이전트)를 사용해 코드베이스를 리팩터링하는 방법을 살펴보겠습니다.
제가 리팩터링을 시작할 때 따르는 간단한 규칙 몇 가지를 소개합니다.
- 가능한 가장 고급·고노력 추론을 활용하세요. 리팩터링은 높은 지능을 요구하는 작업이며 실수를 최소화해야 합니다. 예시: Claude Code의 워크플로우 기능 사용, 혹은 GPT‑5.5의 고차원 사고 활용
- 레포지토리에서는 한 번에 하나의 리팩터링만 수행하세요. 다른 구현 작업과 동시에 진행해도 되지만, 동시에 여러 리팩터링 작업을 돌리지는 마세요
- 최적의 폴더 구조가 확실치 않다면, 구조가 좋은 다른 레포지토리를 코딩 에이전트에 제공하고 “그 구조를 모방해라”고 지시하세요
- 리팩터링은 시간이 걸립니다. 다른 작업을 하면서 백그라운드 작업으로 진행하도록 계획하세요
보통 저는 다음과 같은 흐름으로 리팩터링을 시작합니다. 레포지토리의 새로운 워크트리에 Claude Code를 열고, Claude Code에서 제공하는 가장 높은 노력 옵션인 Ultracode를 활성화합니다.
리팩터링 대상이 명확하면, Ultracode와 Claude에게 무엇을 리팩터링할지, 왜 리팩터링해야 하는지 가능한 한 자세히 알려줍니다. “왜”를 언급하는 것이 꼭 필요하지 않을 수도 있지만, 저는 AI가 제가 어떤 목적을 가지고 작업하는지 이해하도록 하는 것이 매우 유용하다고 생각합니다.
그 다음 에이전트에게 레포지토리 전체, 특히 리팩터링하고 싶은 부분을 충분히 탐색할 시간을 줍니다. 에이전트는 상세한 리팩터링 계획을 수립하고, 저는 Claude Code의 Plan 모드에서 그 계획을 확인합니다.
계획을 검토하여 기대와 일치하는지 확인합니다. 보통 에이전트가 제가 직접 하는 것보다 리팩터링에 더 능숙하기 때문에 첫 시도에서도 꽤 만족스러운 결과를 얻습니다.
제가 리팩터링을 수행할 때 프롬프트에 반드시 포함시키는 중요한 요소는 리팩터링 전·후에 실행할 테스트를 구현하도록 지시하는 것입니다. 테스트는 리팩터링 전에도 정상적으로 통과해야 하고, 리팩터링이 끝난 뒤에도 모두 다시 통과해야 합니다. 이는 모델이 자신의 작업을 검증하고, 실수 없이 진행했는지 확인하는 데 큰 도움이 됩니다.