Claude Code Plan Mode로 복잡한 리팩토링 작업 단계별 분해 및 실행 추적하기
Claude Code Plan Mode란?
Claude Code의 Plan Mode는 복잡한 코딩 작업을 체계적으로 분해하고, 각 단계의 실행 상태를 추적할 수 있는 강력한 기능입니다. 대규모 리팩토링처럼 여러 파일과 모듈에 걸친 변경 작업을 수행할 때, Plan Mode를 활용하면 작업의 전체 구조를 먼저 파악하고 승인한 후 단계별로 안전하게 실행할 수 있습니다.
사전 준비
1단계: Claude Code 설치
Claude Code는 Node.js 18 이상이 필요합니다. 터미널에서 다음 명령어로 설치합니다.
npm install -g @anthropic-ai/claude-code
2단계: 인증 설정
# API 키 설정
export ANTHROPIC_API_KEY=YOUR_API_KEY
# 설치 확인
claude --version3단계: 프로젝트 디렉토리에서 실행
cd /your-project-directory
claudePlan Mode 활성화 및 사용법
4단계: Plan Mode 진입
Claude Code 세션 내에서 Shift+Tab 키를 눌러 모드를 전환합니다. 모드는 세 가지가 있습니다.
| 모드 | 설명 | 사용 시점 |
|---|---|---|
| **Normal** | 계획 수립 + 코드 실행 | 일반 작업 |
| **Plan** | 계획만 수립 (코드 변경 없음) | 복잡한 작업 분석 시 |
| **Auto** | 자동 승인으로 실행 | 신뢰할 수 있는 반복 작업 |
[plan]으로 변경됩니다.
5단계: 리팩토링 계획 요청
Plan Mode에서 복잡한 리팩토링 작업을 설명합니다.
[plan] > 이 프로젝트의 UserService 클래스를 리팩토링해줘.
인증 로직을 AuthService로 분리하고,
데이터 접근 로직을 UserRepository 패턴으로 변경하고,
기존 테스트가 모두 통과하도록 해줘.
Claude Code는 코드를 수정하지 않고 다음과 같은 구조화된 계획을 생성합니다.
📋 리팩토링 계획:
-
[ ] UserService 현재 구조 분석
- 의존성 매핑
- 인증 관련 메서드 식별
-
[ ] AuthService 클래스 생성
- src/services/AuthService.ts 작성
- login(), logout(), validateToken() 이동
-
[ ] UserRepository 인터페이스 정의
- src/repositories/UserRepository.ts 작성
- findById(), create(), update(), delete() 정의
-
[ ] UserService에서 분리된 로직 제거 및 의존성 주입
- constructor에 AuthService, UserRepository 주입
-
[ ] 기존 테스트 업데이트 및 신규 테스트 추가
[ ] 전체 테스트 스위트 실행 및 검증
6단계: 계획 검토 및 수정
계획을 검토한 후, 수정이 필요하면 Plan Mode 상태에서 피드백을 제공합니다.
[plan] > 2단계에서 AuthService에 refreshToken() 메서드도 추가해줘.
그리고 4단계 전에 기존 통합 테스트 백업 단계를 넣어줘.
Claude는 피드백을 반영하여 계획을 업데이트합니다.
7단계: 계획 승인 후 실행
Shift+Tab으로 Normal 모드로 전환한 뒤, 승인된 계획의 실행을 요청합니다.
> 위 계획대로 리팩토링을 진행해줘. 각 단계마다 확인을 받고 넘어가줘.
Claude Code는 각 단계를 순차적으로 실행하며, 파일 변경 전에 승인을 요청합니다.
8단계: 실행 추적 및 검증
각 단계 완료 후 Claude Code는 진행 상태를 업데이트합니다.
📋 리팩토링 진행 상황:
- [✅] UserService 현재 구조 분석
- [✅] AuthService 클래스 생성
- [🔄] UserRepository 인터페이스 정의 (진행 중)
- [ ] UserService 리팩토링
- [ ] 테스트 업데이트
[ ] 전체 검증각 단계에서 테스트를 실행하여 안전성을 확인합니다.
> 현재까지 변경된 부분에 대해 테스트를 실행해줘.
실전 예제: 모놀리식 함수 분해
다음은 하나의 거대한 함수를 여러 모듈로 분해하는 실전 시나리오입니다.
[plan] > src/utils/processOrder.ts의 processOrder 함수가 450줄입니다.
다음 기준으로 분해 계획을 세워줘:
- 검증 로직 → OrderValidator
- 가격 계산 → PricingEngine
- 재고 확인 → InventoryChecker
- 알림 발송 → NotificationDispatcher
각 모듈은 단일 책임 원칙을 따르고 단위 테스트 가능해야 합니다.
Claude Code는 파일별, 함수별로 상세한 이동 계획을 수립하며, 각 단계에서 어떤 코드가 어디로 이동하는지 명확하게 보여줍니다.
Pro Tips
- CLAUDE.md 파일 활용: 프로젝트 루트에
CLAUDE.md파일을 만들어 코딩 컨벤션과 아키텍처 규칙을 명시하면, Plan Mode가 이를 반영한 계획을 생성합니다.- 점진적 실행: 대규모 리팩토링은 한 번에 실행하지 말고, 계획의 각 단계를 개별 커밋으로 분리하세요.> 이 단계를 커밋해줘명령으로 중간 저장이 가능합니다.- Auto 모드 주의:Shift+Tab으로 Auto 모드에 진입하면 모든 파일 변경이 자동 승인됩니다. 리팩토링 초기에는 Normal 모드를 유지하고, 반복적인 패턴 적용 시에만 Auto 모드를 사용하세요.- CLI 플래그 활용:claude —plan플래그로 세션 시작 시 바로 Plan Mode로 진입할 수 있습니다.- 복잡도 기준: 3개 이상의 파일을 동시에 수정해야 하는 작업이라면 항상 Plan Mode를 먼저 사용하세요.
Troubleshooting
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| Plan Mode에서 코드가 직접 수정됨 | 모드가 Normal로 되어 있음 | Shift+Tab으로 모드 확인. 프롬프트에 [plan] 표시 확인 |
| 계획이 너무 추상적임 | 프롬프트가 구체적이지 않음 | 파일 경로, 클래스명, 메서드명을 명시적으로 포함하여 요청 |
| 단계 실행 중 테스트 실패 | 의존성 순서 문제 | 계획의 실행 순서를 재조정하도록 요청. 인터페이스 → 구현 → 테스트 순서 권장 |
| 컨텍스트 윈도우 초과 | 프로젝트가 너무 큼 | 리팩토링 범위를 모듈 단위로 나누어 별도 세션에서 진행 |
ANTHROPIC_API_KEY 오류 | 환경 변수 미설정 | export ANTHROPIC_API_KEY=YOUR_API_KEY 재실행 |
Q1: Plan Mode에서 생성된 계획을 파일로 저장할 수 있나요?
네, Claude Code는 계획을 ~/.claude/plans/ 디렉토리에 자동으로 저장합니다. 세션이 종료된 후에도 다음 세션에서 이전 계획을 이어서 진행해줘라고 요청하면 저장된 계획을 불러와 이어서 실행할 수 있습니다. 또한, 계획 내용을 복사하여 프로젝트 문서로 관리하는 것도 좋은 방법입니다.
Q2: Plan Mode와 Normal Mode를 작업 중간에 자유롭게 전환할 수 있나요?
네, Shift+Tab 키로 언제든 모드를 전환할 수 있습니다. 실행 중 예상치 못한 문제가 발생하면 Plan Mode로 전환하여 나머지 계획을 수정한 후, 다시 Normal Mode로 돌아와 실행을 계속할 수 있습니다. 이 유연한 전환이 Plan Mode의 핵심 장점입니다.
Q3: 여러 사람이 동시에 같은 프로젝트에서 Plan Mode를 사용해도 되나요?
각 개발자는 독립적인 Claude Code 세션에서 작업하므로, 동시 사용이 가능합니다. 다만 동일한 파일을 수정하는 계획이 있다면 Git 브랜치를 분리하여 작업하고, 나중에 병합하는 방식을 권장합니다. Plan Mode에서 먼저 계획을 공유하고 작업 범위를 조율하면 충돌을 최소화할 수 있습니다.