Claude Code로 리팩토링을 자동화하는 방법

왜 Claude Code로 리팩토링을 해야 할까?

리팩토링이 중요하다는 건 누구나 알지만, 수동으로 하기엔 귀찮고 우선순위에서 밀리기 쉽습니다. Claude Code는 전체 프로젝트를 이해하고 여러 파일에 걸친 리팩토링을 자율적으로 수행할 수 있습니다.

패턴 1: 타입 안전성 개선

any 타입 제거

> 프로젝트에서 모든 any 타입을 찾아서 적절한 타입으로 교체해 줘.
> 변경 후 npx tsc --noEmit이 통과하는지 확인해 줘.

Claude Code의 처리 과정:

1. any 타입이 포함된 파일 검색
2. 주변 코드를 기반으로 적절한 타입 추론
3. 필요시 타입 정의 파일 생성
4. 타입 체커를 실행하여 컴파일 검증

리팩토링 전후 비교

// 리팩토링 전
function processData(data: any): any {
  return data.items.map((item: any) => item.name);
}

// 리팩토링 후
interface DataPayload {
  items: Array<{ name: string; id: number }>;
}

function processData(data: DataPayload): string[] {
  return data.items.map((item) => item.name);
}

패턴 2: 함수 분리 및 책임 명확화

비대해진 함수를 분리하는 것은 Claude Code가 특히 잘하는 영역입니다.

> src/services/orderService.ts의 createOrder 함수가 200줄이 넘어.
> 단일 책임 원칙에 따라 작은 함수들로 분리해 줘.
> 기존 테스트가 계속 통과하도록 해 줘.

분리를 위한 프롬프트

> 다음 가이드라인에 따라 함수를 분리해 줘:
> - 각 함수는 30줄 이내
> - 검증, 비즈니스 로직, 영속성 분리
> - 각 함수에 JSDoc 주석 추가
> - 새로운 함수 경계에 맞게 테스트도 분리

패턴 3: 에러 처리 표준화

프로젝트 전체에서 에러 처리 패턴을 통일합니다.

> 프로젝트의 에러 처리를 표준화해 줘:
> - 커스텀 에러 클래스(AppError) 사용
> - 에러 코드를 상수로 정의
> - try-catch 블록에 항상 로깅 포함

Claude Code가 생성하는 예시:

// src/errors/app-error.ts
export class AppError extends Error {
  constructor(
    public readonly code: string,
    message: string,
    public readonly statusCode: number = 500,
    public readonly cause?: Error
  ) {
    super(message);
    this.name = 'AppError';
  }
}

// 에러 코드 상수
export const ErrorCodes = {
  USER_NOT_FOUND: 'USER_NOT_FOUND',
  INVALID_INPUT: 'INVALID_INPUT',
  DB_CONNECTION_ERROR: 'DB_CONNECTION_ERROR',
} as const;

패턴 4: 테스트 보완 및 개선

커버리지가 부족한 곳에 테스트를 추가합니다.

# 커버리지 보고서를 활용한 테스트 추가
npx vitest run --coverage | claude -p "커버리지가 낮은 파일을 찾고 누락된 테스트 케이스를 추가해 줘"

> src/services/ 하위의 모든 파일에 대해 테스트 커버리지를 80% 이상으로 올려 줘.
> 정상 경로뿐만 아니라 엣지 케이스와 에러 시나리오도 커버해 줘.

패턴 5: API 응답 형식 통일

> 모든 API 엔드포인트의 응답 형식을 다음으로 통일해 줘:
>
> 성공: { success: true, data: T }
> 실패: { success: false, error: { code: string, message: string } }
>
> 프론트엔드 코드도 새 형식에 맞게 업데이트해 줘.

안전한 리팩토링을 위한 팁

1. 먼저 테스트 통과 확인

> 먼저 npm test를 실행해서 기존 테스트가 모두 통과하는지 확인해 줘.
> 실패하는 테스트가 있으면 코드 변경 전에 알려 줘.

2. 점진적으로 진행

한 번에 모든 것을 바꾸지 말고 모듈 단위로 리팩토링하세요.

> 먼저 src/services/userService.ts만 리팩토링해 줘.
> 변경 후 테스트가 통과하는 것을 확인하고 다음으로 넘어가 줘.

3. diff 확인

> git diff를 보여 줘. 너무 크면 파일별로 변경 사항을 요약해 줘.

4. 별도 브랜치에서 작업

git checkout -b refactor/error-handling
claude
> 에러 처리 리팩토링을 시작해 줘...

실전 사례: 레거시 코드 현대화

오래된 코드베이스를 점진적으로 현대화하는 방법:

> 이 프로젝트를 다음과 같이 현대화해 줘:
> 1. var를 const/let으로 교체
> 2. 콜백 함수를 async/await로 변환
> 3. require를 import로 변환
> 4. 각 변경 후 테스트 통과 확인
> 5. 한 단계씩 진행하고 각 단계의 결과를 보고

결론

Claude Code를 활용하면 며칠 걸리던 리팩토링을 몇 시간 만에 완료할 수 있습니다. 핵심은 명확한 규칙을 제시하고, 점진적으로 진행하며, 항상 테스트로 검증하는 것입니다. 작은 모듈부터 시작해서 직접 결과를 확인해 보세요.