Claude Code 대규모 리팩토링 프로젝트 관리 베스트 프랙티스: Plan 모드, 태스크 분해, Git 체크포인트 워크플로우
Claude Code로 대규모 리팩토링 프로젝트를 체계적으로 관리하는 방법
대규모 코드베이스를 리팩토링할 때 Claude Code의 Plan 모드, 태스크 관리, Git 체크포인트 워크플로우, 컨텍스트 윈도우 최적화 전략을 활용하면 복잡한 프로젝트를 안전하고 효율적으로 완수할 수 있습니다. 이 가이드에서는 실무에서 바로 적용 가능한 워크플로우를 단계별로 안내합니다.
1단계: CLAUDE.md로 프로젝트 컨텍스트 설정
리팩토링을 시작하기 전에 프로젝트 루트에 CLAUDE.md 파일을 생성하여 Claude Code에 프로젝트의 규칙과 컨텍스트를 알려줍니다.
# CLAUDE.md 예시
프로젝트 구조
- src/core/ — 핵심 비즈니스 로직
- src/api/ — REST API 엔드포인트
- src/utils/ — 유틸리티 함수
리팩토링 규칙
- 기존 public API 시그니처를 변경하지 말 것
- 모든 변경 후 테스트 실행: npm test
- TypeScript strict 모드 유지
- 단일 PR에 500줄 이상 변경 금지
코딩 컨벤션
- 함수명: camelCase
- 파일명: kebab-case
테스트 파일: *.test.ts이 파일은 Claude Code가 매 대화 시작 시 자동으로 읽어 프로젝트의 맥락을 파악하는 데 사용됩니다.
2단계: Plan 모드로 리팩토링 전략 수립
대규모 리팩토링은 코드를 바로 수정하기 전에 반드시 계획을 먼저 세워야 합니다. Claude Code의 Plan 모드를 활용하세요.
# Plan 모드 진입 (Shift+Tab으로 토글)
또는 프롬프트에서 직접 요청
우리 프로젝트의 인증 모듈을 JWT에서 OAuth2로 마이그레이션해야 합니다. 먼저 계획을 세워주세요. 코드를 수정하지 마세요.Plan 모드에서 Claude Code는 코드베이스를 분석하고, 의존성을 파악하며, 단계별 실행 계획을 제안합니다. 계획이 확정되면 Shift+Tab으로 실행 모드로 전환하여 작업을 진행합니다.
효과적인 Plan 프롬프트 작성법
- 범위를 명확히 지정: “src/auth 디렉토리의 모든 파일을 대상으로”- 제약조건 명시: “하위 호환성을 유지하면서”- 성공 기준 정의: “모든 기존 테스트가 통과해야 함”- 우선순위 표시: “가장 의존성이 적은 모듈부터 시작”
3단계: 태스크 분해로 작업 추적
Plan 모드에서 수립한 전략을 구체적인 태스크로 분해합니다. Claude Code는 대화 내에서 태스크 진행 상황을 자동으로 추적합니다.
# 태스크 분해 요청 예시
위 계획을 실행 가능한 태스크로 분해해줘. 각 태스크는:
- 독립적으로 커밋 가능할 것
- 하나의 논리적 변경만 포함할 것
테스트 가능할 것Claude Code가 생성하는 태스크 목록 예시:
- OAuth2 클라이언트 설정 파일 생성 (
src/auth/oauth-config.ts)- 토큰 검증 미들웨어 교체 (src/middleware/auth.ts)- 사용자 세션 관리 로직 업데이트 (src/auth/session.ts)- 기존 JWT 유틸리티에 deprecation 경고 추가- 통합 테스트 업데이트 및 실행
4단계: Git 체크포인트 워크플로우
각 태스크 완료 후 Git 체크포인트를 생성하여 안전하게 진행합니다. Claude Code에서 직접 Git 명령을 실행할 수 있습니다.
# 작업 브랜치 생성
git checkout -b refactor/auth-oauth2-migration
태스크 1 완료 후 체크포인트
git add src/auth/oauth-config.ts
git commit -m “feat(auth): add OAuth2 client configuration”
태스크 2 완료 후 체크포인트
git add src/middleware/auth.ts
git commit -m “refactor(auth): replace JWT middleware with OAuth2 token validation”
문제 발생 시 이전 체크포인트로 복원
git log —oneline -5
git reset —soft HEAD~1 # 마지막 커밋만 되돌리기
Claude Code에 자동 커밋 워크플로우를 요청할 수도 있습니다:
> 각 태스크를 완료할 때마다 의미 있는 커밋 메시지와 함께
자동으로 커밋해줘. 커밋 전에 반드시 npm test를 실행하고, 테스트가 실패하면 커밋하지 마.
5단계: 컨텍스트 윈도우 최적화 전략
대규모 프로젝트에서는 컨텍스트 윈도우를 효율적으로 관리하는 것이 핵심입니다.
핵심 전략
| 전략 | 설명 | 적용 방법 |
|---|---|---|
| 범위 한정 | 한 번에 하나의 모듈만 다루기 | > src/auth 디렉토리만 집중해서 작업해줘 |
| 서브에이전트 활용 | 탐색과 실행을 분리 | 복잡한 검색은 Explore 에이전트에 위임 |
| 대화 분리 | 태스크별로 새 대화 시작 | 태스크 1 완료 → 새 대화에서 태스크 2 시작 |
| CLAUDE.md 활용 | 반복 정보를 파일로 관리 | 프로젝트 규칙을 CLAUDE.md에 기록 |
| 간결한 프롬프트 | 불필요한 설명 최소화 | 핵심 요구사항만 전달 |
# 컨텍스트 효율적 활용을 위한 대화 시작 예시
CLAUDE.md를 참고해줘. 현재 태스크: OAuth2 토큰 검증 미들웨어 교체 대상 파일: src/middleware/auth.ts 이전 태스크에서 src/auth/oauth-config.ts가 이미 완성됨 시작해줘.
메모리 시스템 활용
Claude Code의 메모리 기능을 사용하면 대화 간에 프로젝트 진행 상황을 유지할 수 있습니다:
> 현재까지의 리팩토링 진행 상황을 기억해줘:
> - 태스크 1, 2 완료
> - 태스크 3 진행 중 (세션 관리 로직 50% 완료)
> - 발견된 이슈: redis 세션 스토어 호환성 문제
## Pro Tips: 파워 유저를 위한 고급 팁
- **Compact 활용:** 대화가 길어지면 /compact 명령으로 컨텍스트를 압축하세요. 핵심 정보만 유지되어 후속 작업의 정확도가 높아집니다.- **병렬 대화:** 독립적인 모듈은 별도의 Claude Code 세션에서 동시에 리팩토링하세요.- **테스트 주도 리팩토링:** "먼저 실패하는 테스트를 작성하고, 그 다음 리팩토링해줘"라고 요청하면 안전한 리팩토링이 가능합니다.- **Diff 리뷰:** 커밋 전 git diff --stat으로 변경 범위를 확인하도록 워크플로우에 포함하세요.- **점진적 타입 강화:** // @ts-expect-error를 활용한 점진적 마이그레이션을 요청할 수 있습니다.
## Troubleshooting: 자주 발생하는 문제 해결
문제: 컨텍스트 윈도우 한계 도달
**증상:** Claude Code가 이전 대화 내용을 잊거나 반복적인 실수를 합니다.
**해결:**
# 1. /compact로 컨텍스트 압축
/compact
2. 새 대화를 시작하면서 핵심 맥락만 전달
claude
CLAUDE.md 참고. 태스크 3부터 이어서 진행. src/auth/session.ts 수정 필요.
문제: Plan과 실행 결과가 다름
**증상:** 계획했던 변경과 실제 코드 수정이 다릅니다.
**해결:** Plan 모드에서 계획을 확정한 후, 각 단계별로 확인하며 진행하세요.
> 계획의 1단계만 실행해줘. 완료 후 결과를 보여주고 멈춰.
### 문제: Git 충돌 발생
**증상:** 여러 태스크를 병렬로 진행하다 merge conflict 발생.
**해결:**
# 충돌 파일 확인
git status
Claude Code에 충돌 해결 요청
git merge conflict가 발생했어. src/auth/session.ts의 충돌을 해결해줘. 우리 브랜치(ours)의 OAuth2 로직을 우선으로 해줘.
자주 묻는 질문 (FAQ)
Q1: Plan 모드에서 세운 계획을 다음 대화에서도 사용할 수 있나요?
네, 가능합니다. Plan 모드에서 생성된 계획을 CLAUDE.md 파일이나 별도의 마크다운 파일에 저장해두면 새로운 대화에서도 해당 파일을 참조하여 이어서 작업할 수 있습니다. 또한 Claude Code의 메모리 기능을 통해 "이 계획을 기억해줘"라고 요청하면 후속 대화에서 자동으로 컨텍스트가 로드됩니다.
Q2: 리팩토링 중 테스트가 깨지면 자동으로 롤백할 수 있나요?
Git 체크포인트 워크플로우를 설정하면 가능합니다. Claude Code에 “테스트 실패 시 마지막 성공 커밋으로 자동 복원해줘”라고 요청하면, npm test 실행 후 실패 시 git reset —hard HEAD를 자동 수행합니다. 다만 이는 파괴적 작업이므로 Claude Code가 실행 전 확인을 요청할 수 있습니다.
Q3: 컨텍스트 윈도우가 부족할 때 가장 효과적인 대처법은 무엇인가요?
가장 효과적인 방법은 태스크 단위로 대화를 분리하는 것입니다. 하나의 대화에서 전체 리팩토링을 시도하지 말고, 각 태스크를 독립적인 대화에서 처리하세요. CLAUDE.md에 프로젝트 규칙과 진행 상황을 기록해두면 새 대화에서도 맥락이 자동으로 전달됩니다. 또한 /compact 명령으로 현재 대화의 컨텍스트를 압축하는 것도 효과적입니다.