Claude Code로 하는 리팩터링: 계획, 작은 단계, 통과하는 테스트

리팩터링에서 Claude Code가 하는 일

• 리팩터링 백로그를 작은 단계로 처리하고, 단계마다 풀 리퀘스트를 따로 엽니다.
• 단계마다 전후로 테스트를 실행하고, 실패하면 멈춥니다.
• 마이그레이션의 기계적인 부분을 맡습니다: 코드베이스 전체의 이름 변경, API 업그레이드, 새 라이브러리로의 이전.
• 죽은 코드와 중복된 로직을 지우고, 지운 이유를 하나하나 설명합니다.

리팩터링에 쓰는 Claude Code 기능

리팩터링용 Claude Code 설정 방법

1. 도구 연결하기

   연결할 것은 없습니다. 리팩터링을 안전하게 만드는 것은 Claude가 실행할 수 있는 테스트 명령어와 단계별 크기 제한이니, 둘 다 CLAUDE.md에 넣고 워크트리에서 시작하세요.

   # 자체 워크트리에서 리팩터링 시작
   claude --worktree billing-async
   
   # 편집 전에 계획에 합의
   /plan Move the billing module from callbacks to async/await

2. CLAUDE.md에 규칙 쓰기

   Claude Code는 claude -p 실행을 포함해 모든 세션을 시작할 때 CLAUDE.md를 읽습니다. 이 일의 규칙을 여기에 넣거나, 길다면 .claude/skills/ 아래 스킬로 만드세요. CLAUDE.md 가이드를 참고하세요.

   ## 리팩터링 규칙
   - 동작은 바꾸지 마세요. 테스트를 바꿔야 한다면 멈추고 물어보세요.
   - 시작하기 전과 단계가 끝날 때마다 `npm test`를 실행하세요.
   - 풀 리퀘스트 하나에 한 단계, 변경은 400줄 미만.
   - REFACTOR.md를 최신으로 유지하세요: 끝난 것은 체크하고,
     발견한 것은 추가하세요.
   - migrations/, 생성된 파일, 공개 API는 묻지 않고 건드리지
     마세요.

3. 대화형 화면 없이 실행하기

   claude -p는 작업 하나를 실행하고 종료하므로 cron, CI, 다른 도구에서 시작할 수 있습니다. 묻지 않고 할 수 있는 일은 --allowedTools나 --permission-mode로 정하고, --output-format json을 쓰면 결과가 비용과 함께 반환됩니다.

   # REFACTOR.md 백로그에서 하루 한 단계
   claude -p "REFACTOR.md에서 체크되지 않은 다음 항목을 하고 테스트가 계속 통과하게 해 줘" \
     --allowedTools "Bash(npm test),Read,Edit"

4. 일정에 올리기

   /schedule로 클라우드 예약 작업을 만들거나(Pro, Max, Ultra, Team, Enterprise), 데스크톱 예약 작업을 쓰거나, 세션이 열려 있는 동안 /loop를 쓰세요. Claude Code를 능동적으로 만드는 방법을 참고하세요.

출처: Claude Code 문서

한계와 안전

• 테스트가 없으면 리팩터링과 동작 변경을 구분하지 못합니다. 먼저 그 영역에 테스트를 추가하세요.
• 큰 재작성을 한 번에 하면 리뷰하기 어렵습니다. 하나씩 머지되는 작은 단계가 더 안전하고, 결국 더 빠릅니다.
• 어떤 이상한 코드가 의도된 것인지 모릅니다. 그런 곳은 주석이나 규칙에 표시해 두세요.
• Claude Code v2.1.302부터 claude -p는 Manual 모드로 시작합니다. 승인이 필요한 작업은 규칙으로 허용하지 않는 한 거부됩니다. 이 일에 필요한 도구만 허용하세요.

리팩터링에는 Claude Code와 Codex 중 무엇을 쓸까요?

규칙은 그대로 옮겨 쓸 수 있습니다. AGENTS.md에 한 번 쓰고 CLAUDE.md에 @AGENTS.md를 넣으면 두 에이전트가 같은 파일을 읽습니다.

다른 에이전트용 단계별 안내: Codex에서 하는 리팩터링.

리팩터링 담당자 두기

명령어는 누군가 기억해서 실행할 때만 돌아갑니다. Crewmark는 내 Claude Code 세션을 역할, 숫자로 된 목표, 근무 시간, 하트비트를 갖춘 AI 직원으로 바꿔, 일이 일정에 맞춰 진행되고 보드에 올라오게 합니다.

1. 역할에서 시작하기

   AI 소프트웨어 엔지니어의 브리프에 이 규칙을 넣으세요.

2. 일을 보드에 올리기

   이 일을 반복 이슈로 추가하세요. 직원이 하트비트에 깨어나 일을 하고 댓글로 보고합니다.

3. 관련 페이지

   머지 전에 코드 리뷰가 각 단계를 확인합니다.

자주 묻는 질문