Claude Code Plan Mode로 복잡한 리팩토링 작업 분해하기: 단계별 실행 및 진행 추적 가이드
Claude Code Plan Mode란?
Claude Code의 Plan Mode는 복잡한 코딩 작업을 체계적으로 분해하고, 단계별로 실행하며, 진행 상황을 추적할 수 있는 강력한 기능입니다. 특히 대규모 리팩토링 작업에서 코드 변경의 범위를 명확히 파악하고, 안전하게 실행할 수 있도록 도와줍니다. 이 가이드에서는 Plan Mode를 활용하여 실제 리팩토링 프로젝트를 수행하는 전체 워크플로우를 단계별로 안내합니다.
사전 준비
1단계: Claude Code 설치
Claude Code를 아직 설치하지 않았다면 npm을 통해 전역 설치합니다.
npm install -g @anthropic-ai/claude-code
2단계: 인증 설정
처음 실행 시 Anthropic 계정으로 인증합니다.
claude
# 브라우저가 열리며 인증 진행
# 또는 API 키 직접 설정
export ANTHROPIC_API_KEY=YOUR_API_KEY
### 3단계: 프로젝트 디렉토리에서 시작
cd /your-project-directory
claude4단계: Plan Mode 진입
Claude Code 대화 중 Shift+Tab 키를 눌러 Plan Mode로 전환합니다. 프롬프트 표시줄이 **[plan]**으로 변경되어 현재 Plan Mode임을 알 수 있습니다.
# Claude Code 실행 후
claude
Plan Mode 전환: Shift+Tab 누르기
프롬프트가 [plan] 모드로 변경됨
5단계: 리팩토링 작업 설명
Plan Mode에서 리팩토링 목표를 상세히 설명합니다. 구체적일수록 더 나은 계획을 생성합니다.
[plan] 이 프로젝트의 사용자 인증 모듈을 리팩토링해줘.
현재 모놀리식 auth.js 파일(800줄)을 다음과 같이 분리하고 싶어:
- 토큰 관리 모듈
- 세션 처리 모듈
- 미들웨어 모듈
- 유틸리티 함수 모듈
기존 테스트가 모두 통과하도록 유지해야 해.
### 6단계: 생성된 계획 검토
Claude Code가 다음과 같은 구조화된 계획을 생성합니다.
| 단계 | 작업 내용 | 예상 영향 |
|---|---|---|
| 1 | 기존 auth.js 코드 분석 및 의존성 매핑 | 코드 읽기만, 변경 없음 |
| 2 | tokenManager.js 모듈 생성 및 토큰 관련 함수 이동 | 새 파일 생성 |
| 3 | sessionHandler.js 모듈 생성 및 세션 로직 분리 | 새 파일 생성 |
| 4 | authMiddleware.js 모듈 생성 | 새 파일 생성 |
| 5 | authUtils.js 유틸리티 함수 분리 | 새 파일 생성 |
| 6 | auth.js를 통합 진입점으로 리팩토링 | 기존 파일 수정 |
| 7 | import 경로 업데이트 및 테스트 실행 | 다수 파일 수정 |
[plan] 3단계와 4단계 사이에 인터페이스 타입 정의 단계를 추가해줘.
그리고 각 단계마다 테스트를 실행하는 검증 과정도 포함해줘.
## 단계별 실행 및 진행 추적
8단계: 실행 모드로 전환
계획이 확정되면 다시 Shift+Tab을 눌러 일반 모드로 돌아가 실행을 시작합니다.
# Shift+Tab으로 일반 모드 복귀
계획의 1단계부터 실행해줘.
### 9단계: 단계별 진행 및 확인
각 단계가 완료될 때마다 Claude Code가 변경 사항을 보여주고, 다음 단계 진행 여부를 확인합니다.
# 각 단계 완료 후 검증
현재까지 변경된 파일 목록과 테스트 결과를 보여줘.
# 테스트 실행으로 안정성 확인 npm test또는 특정 테스트 파일만 실행
npm test — —testPathPattern=auth
10단계: 진행 상황 추적
Plan Mode로 다시 전환하여 현재 진행 상황을 확인할 수 있습니다.
[plan] 현재 진행 상황을 요약해줘. 어떤 단계가 완료되었고 남은 작업은 뭐야?
Claude Code는 완료된 단계에 체크 표시를 하고 남은 작업을 명확히 보여줍니다.
실전 예제: API 라우터 리팩토링
다음은 Express.js 프로젝트에서 실제로 Plan Mode를 사용하는 예시입니다.
# Claude Code 시작
claude
Plan Mode 진입 (Shift+Tab)
[plan] routes/api.js 파일이 50개 이상의 엔드포인트를 포함하고 있어.
도메인별로 분리해줘:
- routes/users.js (사용자 관련)
- routes/products.js (상품 관련)
- routes/orders.js (주문 관련)
routes/index.js (라우터 통합) Swagger 문서도 업데이트 필요해.# 계획 확인 후 실행 모드로 전환 (Shift+Tab) 계획대로 실행해줘. 각 단계마다 git commit도 해줘.
Claude Code가 각 단계를 실행하며:
1. 파일 분석
2. 도메인별 라우터 파일 생성
3. 엔드포인트 이동
4. import 경로 수정
5. 테스트 실행 및 검증
Pro Tips: 파워 유저를 위한 고급 팁
- 계획 범위 제한: 한 번에 너무 많은 변경을 요청하지 마세요. 모듈 단위로 나누어 계획을 세우면 오류 발생 시 롤백이 쉽습니다.- CLAUDE.md 활용: 프로젝트 루트에
CLAUDE.md파일을 생성하여 코딩 컨벤션, 아키텍처 규칙, 금지 패턴 등을 명시하면 Plan Mode가 이를 반영합니다.- Git 연동 전략: 각 단계 완료 시git commit을 요청하면 단계별 롤백이 가능합니다.“각 단계마다 의미 있는 커밋 메시지와 함께 커밋해줘”라고 지시하세요.- 점진적 계획 세분화: 초기 계획이 너무 추상적이면[plan] 2단계를 더 세부적으로 분해해줘와 같이 특정 단계만 세분화할 수 있습니다.- 컨텍스트 유지: 긴 리팩토링 작업 중/compact명령으로 대화를 압축하여 컨텍스트 윈도우를 효율적으로 관리하세요.
Troubleshooting: 일반적인 문제 해결
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| Plan Mode 전환이 안 됨 | 터미널 키 바인딩 충돌 | 다른 터미널 에뮬레이터 사용 또는 키 바인딩 확인 |
| 계획 실행 중 파일 충돌 | 외부에서 동일 파일 수정 | git stash로 임시 저장 후 재시도 |
| 테스트 실패 후 진행 불가 | 의존성 변경 미반영 | [plan] 현재 테스트 실패 원인을 분석하고 계획을 수정해줘 |
| 컨텍스트 윈도우 초과 | 대규모 파일 다수 로딩 | /compact 실행 후 현재 단계부터 재개 |
| 변경 사항이 너무 광범위함 | 계획 범위가 과도함 | Plan Mode에서 계획을 더 작은 단위로 분할 요청 |
Q1: Plan Mode와 일반 모드의 차이점은 무엇인가요?
일반 모드에서 Claude Code는 요청을 즉시 실행하며 파일을 읽고 수정합니다. 반면 Plan Mode에서는 코드를 변경하지 않고 분석과 계획 수립만 수행합니다. Shift+Tab으로 두 모드를 자유롭게 전환할 수 있으며, 복잡한 작업에서는 Plan Mode로 먼저 전체 그림을 그린 뒤 실행하는 것이 안전합니다.
Q2: Plan Mode에서 생성한 계획을 중간에 수정할 수 있나요?
네, 가능합니다. 실행 중이라도 Shift+Tab으로 Plan Mode로 전환하여 남은 단계를 수정하거나, 새로운 단계를 추가하거나, 기존 단계를 삭제할 수 있습니다. 이미 완료된 단계의 결과물은 유지되며, 수정된 계획에 따라 이후 단계가 진행됩니다.
Q3: 대규모 리팩토링 작업 시 Plan Mode 사용의 권장 범위는 어떻게 되나요?
하나의 계획에 7~10단계 이내로 구성하는 것을 권장합니다. 그 이상의 규모라면 전체 작업을 여러 개의 독립적인 Plan으로 나누는 것이 좋습니다. 예를 들어, 100개 파일을 리팩토링해야 한다면 모듈 그룹별로 별도의 Plan을 수립하고, 각 Plan 완료 후 커밋하여 진행하는 방식이 효과적입니다.