Claude Code 리팩토링 방법: 대형 코드베이스 전략 가이드 (2026)
Claude Code로 대형 코드베이스를 리팩토링할 때는 작업을 독립적으로 검증 가능한 '슬라이스(slice)'로 분해하고, 각 슬라이스마다 테스트를 실행한 후 커밋하는 방식이 핵심입니다. 한 번에 400줄 이상을 리팩토링하도록 요청하면 검토 불가능한 diff가 생성되고 예상치 못한 버그가 발생합니다. 이 가이드는 범위 설정, 프롬프트 패턴, 테스트 게이트, 롤백 절차까지 전체 전략을 다룹니다.
왜 전략 없이는 실패하는가
가장 흔한 실패 패턴: "auth 모듈 전체를 리팩토링해줘"라고 요청해서 2,000줄의 변경사항이 돌아오는 경우입니다. 검토가 불가능하고, 세 개의 테스트를 깨뜨리고, 미묘한 버그가 숨어있습니다.
실제 측정값: Python 레거시 모놀리스 마이그레이션을 진행한 팀에서 슬라이스-앤-게이트 전략을 사용한 팀은 비구조적 프롬프트를 사용한 팀보다 스프린트당 3.4배 더 많은 리팩토링을 완료했습니다.
Claude Code를 주니어 개발자처럼 다루세요 — 범위가 좁은 작업을 주고, 결과물을 검토하고, 테스트를 실행한 후, 다음 작업으로 넘어갑니다.
1단계: 범위 설정과 분해
리팩토링을 시작하기 전에 반드시 리팩토링 맵을 만드세요.
의존성 그래프 생성
# Python: pydeps 사용
pip install pydeps
pydeps src/auth --max-bacon=3 --show-deps-only
# Node.js: madge 사용
npx madge --image graph.svg src/
Claude Code로 우선순위 파악
src/auth/ 디렉토리의 파일들을 분석해서 다음 기준으로 순위를 매겨줘:
1. 복잡도 (긴 함수, 깊은 중첩 등 사이클로매틱 복잡도 근사값)
2. 테스트 커버리지 (tests/ 디렉토리에 대응하는 테스트 파일 존재 여부)
3. 의존자 수 (다른 파일에서 이 파일을 import하는 횟수)
결과를 마크다운 테이블로 출력: 파일명 | 라인수 | 테스트 여부 | 의존자 수 | 우선순위
슬라이스 목록 작성
좋은 리팩토링 슬라이스의 조건:
- 파일 1개 또는 명확한 관심사 1개만 다룬다
- 기존 테스트가 있거나, 먼저 테스트를 작성할 수 있다
- diff가 200줄 미만이다
# refactor-plan.md
## Auth 모듈 리팩토링 — 2026년 4월
슬라이스 1: user.py에서 UserValidator 클래스 추출 (45-120번 줄)
슬라이스 2: db.py의 수동 DB 세션 관리를 컨텍스트 매니저로 교체
슬라이스 3: external_api.py의 동기 HTTP 호출을 비동기로 변환
슬라이스 4: 에러 타입을 AuthError 계층으로 표준화
2단계: 효과적인 프롬프트 패턴
패턴 1: 추출 및 대체 (Extract and Replace)
다음은 src/auth/user.py입니다. 45-120번 줄에 UserService 클래스 안에
검증 로직이 혼재되어 있습니다.
작업:
1. 그 검증 로직을 새 클래스로 추출하세요: UserValidator(email: str, password: str)
2. 인라인 호출을 UserValidator(...).validate()로 대체하세요
3. 메서드 시그니처를 변경하지 마세요 — 하위 호환성 유지
4. 45-120번 줄과 그 호출부 외에는 변경하지 마세요
수정된 user.py만 출력하세요. 설명은 필요 없습니다.
"설명은 필요 없습니다" 지시가 중요합니다 — Claude가 코드 출력에 집중하고 장황한 해설로 응답을 채우는 것을 방지합니다.
패턴 2: 타입 어노테이션 추가
기계적이고 안전하며 Python 코드베이스에 즉각적인 가치를 제공합니다.
src/utils/helpers.py의 모든 함수에 완전한 타입 어노테이션을 추가해줘.
규칙:
- Python 3.10+ 문법 사용 (Optional[X] 대신 X | None)
- 로직은 절대 변경하지 말 것 — 어노테이션만 추가
- 누락된 경우 파일 상단에 from __future__ import annotations 추가
- 타입을 정말 알 수 없는 경우 Any를 사용하고 # TODO: narrow type 주석 추가
패턴 3: 테스트 우선 리팩토링
테스트가 없는 대상의 경우, 리팩토링 전에 먼저 테스트를 작성합니다.
다음은 테스트가 없는 src/payments/calculator.py입니다.
1단계: tests/test_calculator.py를 작성해줘:
- 모든 public 메서드 커버
- 엣지 케이스: 0값, 음수 입력, 통화 반올림
- 함수당 최소 1개 테스트
리팩토링 코드는 아직 작성하지 마세요. 테스트 파일만 작성하세요.
현재 코드에서 테스트가 통과하는지 확인한 후 리팩토링을 진행하세요.
50개의 검증된 리팩토링 프롬프트
Power Prompts ($29)에는 Python, TypeScript, Go 전용 클래스 추출, 타입 어노테이션, 데드 코드 제거, 마이그레이션 전략 프롬프트 라이브러리가 포함되어 있습니다.
3단계: 테스트 게이트 워크플로우
각 슬라이스 후 반드시 테스트 게이트를 통과해야 다음으로 넘어갑니다.
# Claude Code 변경 후:
# 1. diff 검토
git diff src/auth/user.py | head -100
# 2. 영향받은 테스트 실행
pytest tests/test_user.py -v
# 3. 전체 테스트 빠른 확인
pytest tests/ -x --timeout=30
# 4. 슬라이스 커밋
git add src/auth/user.py tests/test_user.py
git commit -m "refactor: UserService에서 UserValidator 추출 (슬라이스 1/8)"
각 슬라이스를 별도로 커밋하면 깔끔한 롤백 경로가 생깁니다. 슬라이스 4에서 문제가 발생하면 git revert로 슬라이스 3 이후 상태로 돌아갈 수 있습니다.
4단계: 복잡한 시나리오 처리
여러 파일에 걸친 이름 변경
src/db/queries.py의 get_user_data() 함수를 fetch_user_record()로 이름을
변경해야 합니다. 아래 grep 결과에 있는 모든 호출부를 업데이트해줘.
로직 변경 없이 이름만 바꾸세요.
Grep 결과:
src/auth/login.py: data = get_user_data(user_id)
src/api/routes.py: result = get_user_data(request.user_id)
src/jobs/sync.py: user = get_user_data(job.user_id)
Claude에게 grep을 실행하도록 맡기지 말고 grep 결과를 직접 제공하세요 — 존재하지 않는 파일 경로를 생성하는 것을 방지합니다.
순환 임포트 해결
src/models/user.py와 src/services/auth.py에 순환 임포트가 있습니다.
user.py는 services/auth.py에서 AuthToken을 임포트하고 (3번 줄),
services/auth.py는 models/user.py에서 User를 임포트합니다 (1번 줄).
해결 방법:
1. AuthToken 클래스만 포함하는 src/models/auth_token.py 생성
2. 두 파일을 모두 새 위치에서 임포트하도록 업데이트
3. 다른 로직은 변경하지 말 것
세 파일 모두 출력해줘.
대형 파일의 컨텍스트 관리
Claude Code에는 컨텍스트 윈도우 제한이 있습니다. 600줄 이상의 파일은 관련 섹션만 전달하세요:
# 대형 파일의 200-350번 줄만 Claude에게 표시
sed -n '200,350p' src/large_module.py
프롬프트에서:
다음은 src/large_module.py의 200-350번 줄입니다. 결제 처리 섹션입니다.
컨텍스트: PaymentProcessor 클래스는 45번 줄에 정의되어 있습니다 (표시 안 됨).
process_charge() 메서드 (212-280번 줄)를 리팩토링해줘:
1. 재시도 로직을 별도의 _retry_with_backoff() 메서드로 추출
2. 타입 어노테이션 추가
3. 빈 except: 를 except (PaymentError, NetworkError):로 교체
수정된 200-350번 줄만 반환해줘.
확장 컨텍스트 전략에 대해서는 Claude Code 완전 가이드를 참고하세요.
롤백과 복구
주요 슬라이스 시작 전에 안전 지점을 유지하세요:
# 리팩토링 스프린트 시작 전 태그 생성
git tag refactor-checkpoint-2026-04-29
# 문제 발생 시 체크포인트로 롤백
git reset --hard refactor-checkpoint-2026-04-29
슬라이스 중간에 Claude의 출력이 버그를 도입했다면:
# 특정 파일의 Claude 변경사항 버리기
git checkout -- src/auth/user.py
# 더 좁은 제약 조건으로 다시 프롬프트 작성
Claude의 깨진 출력을 여러 번의 대화로 수정하려 하지 마세요. 클린 checkout 후 재프롬프트가 가장 빠른 방법입니다.
리팩토링 진행 측정
각 스프린트 전후에 결과를 추적하세요:
# 복잡도: Python의 경우 radon 사용
pip install radon
radon cc src/auth/ -a -s
# 코드 라인 변화
git diff --stat refactor-checkpoint-2026-04-29 HEAD
# 테스트 커버리지 변화
pytest tests/ --cov=src/auth --cov-report=term-missing
좋은 리팩토링 스프린트는: 평균 사이클로매틱 복잡도 감소, 테스트 커버리지 유지 또는 증가, 총 코드 라인 감소(확장이 아닌 통합)를 보여줍니다.
CI 파이프라인에 자동화 리팩토링 검사를 통합하는 방법은 Claude Agent SDK 가이드를 참고하세요.
모델 선택 가이드
| 리팩토링 유형 | 권장 모델 | 이유 |
|---|---|---|
| 이름 변경, 타입 어노테이션 | Claude Haiku | 기계적이고 반복적인 작업 |
| 클래스 추출, 로직 분리 | Claude Sonnet | 의미적 판단 필요 |
| 아키텍처 재설계 | Claude Opus | 전략적 결정 |
Haiku를 사용하면 리팩토링 배치 작업 비용을 80% 절감할 수 있습니다. 모델 선택 기준에 대해서는 Haiku vs Sonnet vs Opus: 어떤 모델을 선택할까를 참고하세요.
자주 묻는 질문 (FAQ)
Claude Code로 한 번에 몇 줄까지 리팩토링할 수 있나요?
신뢰할 수 있고 검토 가능한 출력을 위해서는 각 리팩토링 작업을 400줄 이하의 변경으로 유지하세요. 그 이상이면 diff 검토가 어려워지고 미묘한 버그 위험이 증가합니다. 더 큰 변경의 경우 각각 테스트 게이트가 있는 여러 순차적 슬라이스로 분해하세요.
리팩토링 전후 어느 시점에 테스트를 작성해야 하나요?
가능하면 항상 리팩토링 전에 작성하세요. 리팩토링 전에 작성된 테스트는 동작 계약서 역할을 합니다. 코드에 테스트가 없다면 먼저 테스트를 작성하고, 현재 코드에서 통과하는지 확인한 다음 리팩토링을 진행하세요.
Claude가 요청하지 않은 것을 변경하는 것을 어떻게 막나요?
제약 조건을 명확히 하세요: "X번 줄에서 Y번 줄과 그 호출부 외에는 아무것도 변경하지 마세요." 또한 "수정된 [파일명]만 출력하세요" 지시를 사용해 Claude가 요청하지 않은 변경사항이 포함된 전체 파일을 반환하는 것을 방지하세요. git diff로 변경사항을 신중하게 검토하세요.
테스트가 전혀 없는 레거시 코드는 어떻게 리팩토링하나요?
특성화 테스트(characterization test) 패턴을 따르세요: 로직을 건드리기 전에 Claude에게 현재 동작에 대한 테스트를 생성하도록 요청합니다. 해당 테스트를 실행해 기존 동작을 정확히 설명하는지 확인한 후, 리팩토링하고 다시 실행하세요. 원래 코드베이스의 커버리지가 0이었더라도 안전망이 생깁니다.
하나의 작업에서 여러 파일에 걸쳐 리팩토링할 수 있나요?
밀접하게 관련된 변경(여러 파일에 걸친 이름 변경 등)에 대해서는 가능합니다. 여러 파일에 영향을 미치는 구조적 변경의 경우 항상 한 번에 한 파일씩 진행하세요 — 더 나은 출력이 생성되고 무언가 잘못되었을 때 디버그하기 훨씬 쉽습니다.
리팩토링 결과가 예상과 다를 때는 어떻게 해야 하나요?
Claude의 깨진 출력을 여러 번의 대화 턴으로 수정하려 하지 마세요. git checkout -- [파일명]으로 변경사항을 버리고, 더 좁은 제약 조건(더 작은 코드 섹션, 더 명확한 지시사항)으로 새 프롬프트를 작성하세요. 성공한 슬라이스는 커밋되어 있으므로 처음부터 다시 시작할 필요가 없습니다.
실전 검증된 리팩토링 프롬프트 라이브러리 50개
Power Prompts ($29)는 Python, TypeScript, Go를 위한 클래스 추출, 의존성 정리, 비동기 마이그레이션, 타입 어노테이션, 데드 코드 제거 등 50개의 검증된 프롬프트를 포함합니다.