Claude Code로 레거시 코드 리팩터링하기: 실전 프롬프트 5가지

오래된 코드를 건드리는 건 항상 부담입니다. Claude Code로 리팩터링을 해보니 특히 '어디서부터 시작할지 모를 때' 도움이 됐습니다. 실제 작업에서 검증한 프롬프트 패턴 다섯 가지를 정리했습니다.

지난 글에서 "복잡한 구조를 다루는 일이 많다면 Claude"라고 말씀드렸는데, 정작 실무에서 어떻게 프롬프트를 짜야 하는지가 궁금하실 겁니다. 이번 글에서는 실제로 레거시 코드베이스를 리팩터링할 때 제가 반복해서 쓰는 프롬프트 패턴 5가지를 코드 예시와 함께 정리했습니다. 막연히 "이 코드 좀 정리해줘"라고 던지는 것과, 아래 방식대로 요청하는 것은 결과물의 품질이 확연히 다릅니다.

 

1. 시작 전에: CLAUDE.md부터 세팅하라

가장 많이 하는 실수가 바로 이거입니다. 새 세션을 열자마자 "이 함수 리팩터링해줘"라고 바로 던지는 것. Claude Code는 프로젝트 루트의 CLAUDE.md 파일을 매 세션 자동으로 읽기 때문에, 여기에 코딩 컨벤션, 금지 패턴, 테스트 실행 명령어를 미리 적어두면 매번 같은 설명을 반복할 필요가 없습니다.

다만 CLAUDE.md가 지나치게 길어지면 오히려 지시사항이 무시될 확률이 올라간다는 점은 주의해야 합니다. "많이 적을수록 좋다"가 아니라 "짧고 명확할수록 성능이 좋다"가 원칙입니다. 저는 보통 20줄을 넘기지 않으려고 합니다.

2. 실전 프롬프트 패턴 5가지

패턴 1 — 탐색과 실행을 분리하라 (플랜 모드)

"이 모듈 리팩터링해줘" 대신 이렇게 요청합니다.

> "payment 모듈의 구조를 먼저 분석하고, 어떤 부분이 중복되어 있는지 설명해줘. 아직 코드는 수정하지 마."

플랜 모드로 먼저 탐색시키고 계획에 동의한 뒤에야 실행 단계로 넘어가면, 엉뚱한 문제를 해결하는 사고를 크게 줄일 수 있습니다.

패턴 2 — 범위를 명시적으로 좁혀라

전체 저장소를 통째로 던지지 말고, 건드려도 되는 파일과 건드리면 안 되는 파일을 명확히 구분해서 지시합니다.

> "src/services/order 디렉토리 안의 파일만 리팩터링해. src/api 쪽은 절대 건드리지 마."

패턴 3 — 체크포인트 단위로 쪼개라

한 번에 거대한 리팩터링을 맡기기보다, 프롬프트 하나하나를 작은 체크포인트로 나눕니다. 각 프롬프트가 끝날 때마다 결과를 확인하고 다음 단계로 넘어가는 편이, 나중에 몰아서 검토하는 것보다 되돌리기도 쉽고 실패를 빨리 잡아낼 수 있습니다.

패턴 4 — 서브에이전트로 교차 검증시켜라

큰 작업을 마쳤다고 바로 끝내지 않고, 새로운 컨텍스트를 가진 서브에이전트에게 diff만 넘겨서 리뷰를 시킵니다.

> "방금 변경된 diff를 신선한 시각으로 검토하고, 빠뜨린 엣지케이스나 기존 테스트를 깨뜨릴 만한 부분이 있는지 보고해줘."

Claude가 오래 무인으로 작업할수록 이 독립적인 검증 단계가 더욱 중요해집니다.

패턴 5 — 반복 작업은 슬래시 커맨드로 템플릿화하라

같은 유형의 리팩터링을 여러 파일에 반복해야 한다면, 매번 프롬프트를 새로 타이핑하는 대신 슬래시 커맨드로 템플릿을 만들어두는 편이 훨씬 빠릅니다. 프롬프트 템플릿에는 슬래시 커맨드를, 실제 도메인 로직이나 헬퍼가 필요할 때는 스킬을, 격리된 병렬 작업에는 서브에이전트를 쓰는 것이 현재 기준 가장 합리적인 역할 분담입니다.

3. 자주 하는 실수 3가지

- 코드를 수정하기 전에 왜 이렇게 짜여 있는지 묻지 않고 바로 고치라고 시키는 것 — 배경을 모르면 겉보기에만 그럴듯한 리팩터링이 나옵니다.

- 테스트 실행 명령어를 CLAUDE.md에 적어두지 않아서, 매번 Claude가 잘못된 명령어로 테스트를 돌리려다 실패하는 것.

- 결과물을 검토 없이 바로 커밋하는 것 — 특히 무인으로 오래 돌린 작업일수록 서브에이전트 리뷰 단계를 생략하면 안 됩니다.

자주 묻는 질문

Q. 이 방식이 Codex에도 그대로 적용되나요?

탐색과 실행을 분리하라, 범위를 좁혀라, 체크포인트로 쪼개라는 원칙 자체는 도구에 상관없이 유효합니다. 다만 슬래시 커맨드나 서브에이전트, CLAUDE.md 같은 구체적인 기능명은 Claude Code 고유의 인터페이스이므로 Codex를 쓰신다면 해당 도구의 대응 기능(설정 파일, 프로필 등)으로 바꿔 적용하시면 됩니다.

Q. 초보자도 바로 따라 할 수 있나요?

네, 다만 처음부터 패턴 5개를 다 쓰려고 하지 마시고 패턴 1(플랜 모드)과 패턴 2(범위 좁히기)부터 익숙해지시는 걸 추천드립니다. 이 두 가지만 제대로 적용해도 결과물의 정확도가 눈에 띄게 좋아집니다.

마무리

결국 좋은 리팩터링 프롬프트의 핵심은 "한 번에 다 시키지 않는 것"입니다. 탐색-계획-실행-검증을 단계별로 쪼개고, 각 단계마다 신선한 눈으로 확인하는 습관을 들이면 Claude Code의 강점인 맥락 유지력을 최대한 활용할 수 있습니다. 다음 글에서는 Claude, Codex, Gemini 등 주요 AI 코딩 도구의 2026년 최신 요금제를 한눈에 비교해보겠습니다.

본 글은 2026년 7월 기준 공개된 각 사 공식 문서와 커뮤니티 사례를 바탕으로 작성되었습니다.

 

 

이 글은 텍드(TechDrift)가 2026년 7월 기준 직접 사용한 경험을 바탕으로 작성했습니다. 요금·정책은 변동될 수 있으니 공식 사이트에서 최신 정보를 확인하세요.