Claude Code Plan Mode + /effort max로 대규모 리팩터링 안전하게 하기
읽기 전용 분석으로 코드 손상 없이 진행하는 법
대규모 리팩터링은 늘 아슬아슬하다. auth 모듈 하나를 건드리다 보면 어느새 routes까지 반쯤 마이그레이션된 채 빌드가 깨지고, 몇 주 공들인 변경사항이 레이스 컨디션을 품고 있다는 사실을 프로덕션에서야 알게 되는 일은 개발자라면 누구나 한 번쯤 겪어봤을 것이다. 레이스 컨디션처럼 코드 리뷰로는 잘 드러나지 않는 버그가 AI 생성 코드에 어떻게 숨어드는지는 이 글의 [단점 및 주의사항] 섹션에서 자세히 다룬다. AI 코딩 에이전트를 도입해도 이 문제는 사라지지 않는다. 오히려 AI가 "계획도 없이 일단 파일을 열어서 고쳐버리는" 방식으로 동작하면 더 빠르게, 더 넓은 범위로 코드를 망가뜨릴 수 있다.
Claude Code는 이 문제를 구조적으로 해결하는 두 가지 도구를 제공한다. 파일을 건드리지 않고 분석만 수행하는 Plan Mode와, 응답 전 내부 추론의 깊이를 제어하는 /effort 커맨드다. 이 둘을 조합하면 "먼저 계획을 완성하고, 그 계획의 품질을 최고로 끌어올린 뒤 구현에 들어간다"는 워크플로가 완성된다.
이 글을 다 읽고 나면 Plan Mode와 /effort의 동작 원리, 두 기능의 황금 조합 패턴, 그리고 실무에서 자주 마주치는 함정을 피하는 방법을 익혀 다음 리팩터링 세션에 바로 적용해볼 수 있습니다. Claude Code를 처음 접하는 독자라면 공식 문서를 먼저 살펴보시면 좋습니다.
핵심 개념
Plan Mode: 읽기 전용 분석 단계
한 줄 요약: 코드 변경을 구조적으로 차단한 채 분석과 계획 수립만 허용하는 안전 모드
Plan Mode는 Claude Code에서 Shift+Tab을 두 번 눌러 활성화하는 읽기 전용 모드다. 이 모드에서 Claude는 다음 세 가지만 수행할 수 있다.
- 파일 읽기 및 코드베이스 탐색
- 아키텍처 이해 및 의존성 분석
- 실행 계획 초안 작성 및 질문 생성
파일 쓰기·편집·파일 시스템 변경 및 상태 변경 셸 명령은 차단된다. git status, ls 같은 읽기 전용 셸 조회는 버전에 따라 허용 여부가 다를 수 있다. AI가 분석 중 의도치 않게 파일을 변경하는 사고를 구조적으로 불가능하게 만드는 안전 장치다.
Plan Mode란 코드 변경 없이 아키텍처 이해와 실행 계획 수립만을 강제하는 Claude Code의 읽기 전용 분석 단계다.
Shift+Tab두 번으로 진입하며, 계획이 완성될 때까지 구현을 원천적으로 차단한다.
/effort: 추론 깊이 제어
한 줄 요약: Claude 응답 전 내부 추론에 쓸 수 있는 토큰 예산을 세션 단위로 설정하는 커맨드
/effort 커맨드는 Claude가 응답 전 내부 추론에 사용할 수 있는 **토큰 예산(thinking budget)**을 조절한다. 세션 전체에 지속 적용되며, 다섯 가지 레벨을 지원한다.
/effort low # 빠른 응답, 단순 작업에 적합
/effort medium # 기본값 (Pro/Max 구독자 기준, 2026년 초 high에서 변경)
/effort high # 복잡한 분석, API 키·Team·Enterprise 기본값
/effort max # 최고 수준 추론, 다단계 아키텍처 분석
/effort auto # Claude가 작업 복잡도에 따라 자동 조정| 레벨 | 응답 속도 | 비용 | 적합한 작업 |
|---|---|---|---|
| low | 매우 빠름 | 최저 | 단순 질문, 포맷 변환 |
| medium | 빠름 | 낮음 | 일반적인 코드 작성 |
| high | 보통 | 중간 | 복잡한 버그 수정, 설계 검토 |
| max | 느림 | 높음 | 대규모 리팩터링 계획, 아키텍처 분석 |
| auto | 작업별 상이 | 작업별 상이 | 혼합 작업 세션 |
2026년 초 기본값 변경: Pro/Max 구독자의 /effort 기본값이 high에서 medium으로 낮아졌다. 이 변경으로 구독 요금이 최적화되었으나 일부 사용자가 출력 품질 저하를 경험했고, 커뮤니티에서 반발이 있었다. API 키·Team·Enterprise 사용자는 여전히 high가 기본값이다.
토큰 예산(thinking budget)이란 Claude가 응답을 생성하기 전 내부 추론에 사용할 수 있는 최대 토큰 수다. 예산이 클수록 더 긴 사고 체인이 가능하지만 응답 시간과 비용이 증가한다. max와 medium의 비용 차이는 작업 복잡도에 따라 수 배에 달할 수 있으므로, 비용이 민감하다면 Anthropic 공식 가격 페이지에서 추론 토큰 요금을 확인해보시면 좋습니다.
Ultrathink: 일회성 고추론 트리거
한 줄 요약: 세션 설정을 바꾸지 않고 해당 턴에만 최고 수준 추론을 요청하는 키워드
ultrathink는 프롬프트 어디에나 포함하면 해당 턴에 한해 high effort로 격상되는 per-turn 오버라이드다. 세션 전체 설정을 바꾸지 않고 특정 분석 요청에만 최고 수준의 추론을 요청할 때 유용하다.
# 세션 기본값은 medium으로 유지하되,
# 계획 수립 턴에만 최고 수준 추론 적용
ultrathink. auth 모듈 의존성 전체를 분석해줘.Ultrathink vs /effort max —
/effort max는 세션 전체에 지속 적용되고,ultrathink키워드는 해당 턴에만 일회성으로 적용된다. 비용 최적화가 필요하다면ultrathink로 핵심 분석 턴만 선택적으로 격상하는 방식을 선택할 수 있다.
두 기능의 조합 원리
"plan first, max effort second" — 먼저 읽기 전용 Plan Mode로 변경 범위를 완전히 이해하고 확정한다. 그 다음 /effort max(또는 ultrathink)로 계획과 구현 각 단계에서 최고 수준의 추론을 확보한다.
Plan Mode가 "무엇을 바꿀 것인가"를 안전하게 결정하는 단계라면, /effort max는 그 결정의 품질을 끌어올리는 역할을 한다. 두 기능은 상호 보완적으로 작동한다.
실전 적용
예시 1: 기본 패턴 — auth 모듈 추출
수십 개 파일에 흩어진 auth 로직을 독립 패키지로 분리하는 시나리오다. 실수하면 임포트 경로가 뒤죽박죽이 되는 전형적인 위험 작업이다.
# Step 1: 세션 전체에 최고 추론 적용
/effort max
# Step 2: Plan Mode 진입 (Shift+Tab 두 번)
# 터미널 프롬프트에 [PLAN] 표시가 나타남# Step 3: Claude에게 입력하는 프롬프트 — 구현 금지 명시
ultrathink. auth 모듈 전체를 @auth-core 패키지로 추출하는 계획을 수립해줘.
영향받는 파일, 의존성, 잠재적 브레이킹 체인지를 모두 나열하고,
각 단계에 검증 기준(테스트 통과, 빌드 성공)을 포함해줘.
코드는 절대 건드리지 마.Claude가 plan.md를 생성하면 에디터에서 직접 열어 검토한다. 잘못된 판단이나 빠진 의존성에 인라인 주석을 추가한 뒤, Claude Code의 @파일명 파일 참조 문법으로 수정된 파일을 다시 전달할 수 있다.
# Step 4: 주석 반영 요청 (여전히 Plan Mode 유지)
@plan.md의 모든 주석을 반영해서 계획을 수정해줘. 아직 구현하지 마.# Step 5: 계획이 만족스러우면 Shift+Tab 한 번으로 Plan Mode 종료# Step 5: 구현 시작 프롬프트
계획대로 1단계(테스트 작성)부터 시작해줘.| 단계 | 모드 | /effort | 목적 |
|---|---|---|---|
| 의존성 분석 | Plan Mode | max | 영향 범위 파악 |
| 계획 초안 작성 | Plan Mode | max | 실행 순서 확정 |
| 계획 검토·수정 | Plan Mode | max | 인간 검토 게이트 |
| 구현 | 일반 모드 | high | 단계별 실행 |
| 테스트 검증 | 일반 모드 | medium | 회귀 확인 |
예시 2: 대형 프로젝트 — 세션 단위 분리
한 세션에 담기 어려운 대형 리팩터링은 독립적인 세션으로 분리하는 것이 안전하다. 컨텍스트 한계(200K 토큰)를 넘으면 Claude가 진행 중인 작업 맥락을 잃어버릴 수 있기 때문이다.
# 세션 1: auth/ 추출
/effort high
# Plan Mode 진입 (Shift+Tab 두 번)# 세션 1 Plan Mode 프롬프트
ultrathink. auth/ 디렉터리를 별도 패키지로 추출하기 위한
현재 코드베이스 상태와 단계별 계획을 수립해줘.
코드는 건드리지 마.# 세션 2: routes/ 분리 (auth/ 추출 완료 후 새 세션으로 시작)
/effort high
# Plan Mode 진입# 세션 2 Plan Mode 프롬프트
ultrathink. auth/ 추출이 완료된 현재 코드베이스에서
routes/를 분리하기 위한 영향 범위와 단계별 계획을 수립해줘.
auth/ 변경사항과 충돌하는 의존성에 특히 주의하고, 코드는 건드리지 마.각 세션을 시작할 때마다 Plan Mode로 현재 코드베이스 상태를 재분석한 뒤 진행하는 것이 중요하다. 이전 세션의 변경사항이 다음 세션의 계획에 영향을 줄 수 있기 때문이다.
예시 3: TDD 결합 패턴 — 회귀 조기 감지
Plan Mode가 생성한 계획 안에 테스트 작성 단계를 먼저 포함시키면 회귀를 조기에 감지할 수 있다.
# plan.md 예시
## auth/ 추출 계획
### 1단계: 테스트 작성 (구현 전)
- `auth/login.test.ts` — 로그인 성공/실패 케이스
- `auth/token.test.ts` — 토큰 발급·검증·만료 케이스
- **검증 기준**: `pnpm test auth/` 통과
### 2단계: 패키지 추출
- `packages/auth-core/` 디렉터리 생성
- auth/ 코드 이동 및 임포트 경로 업데이트
- **검증 기준**: `pnpm build` 성공 + `pnpm test auth/` 통과
### 3단계: 소비자 업데이트
- routes/, middleware/ 임포트 경로 일괄 업데이트
- **검증 기준**: `pnpm test` 전체 통과계획이 승인되면 Plan Mode를 해제하고 아래처럼 단계별로 진행할 수 있다.
# 1단계만 먼저 진행하는 프롬프트
@plan.md의 1단계에 따라 auth/ 함수 테스트를 먼저 작성해줘.
테스트가 모두 통과하면 알려줘. 2단계 코드 추출은 아직 시작하지 마.예시 4: CI/자동화 환경 — effort 레벨 고정
# 환경변수로 effort 레벨 고정 (CI 파이프라인, 자동화 스크립트)
export CLAUDE_CODE_EFFORT_LEVEL=max⚠️
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1은 커뮤니티에서 사용이 보고된 환경변수이나, 공식 문서에서 확인되지 않은 설정이다. 사용 전 현재 Claude Code 버전의 공식 문서를 먼저 확인해보시면 좋습니다.
예시 5 [Preview]: 팀 협업 — Ultraplan 활용 (v2.1.91+)
⚠️ Ultraplan은 현재(2026년 4월) Preview 상태다. Claude Code v2.1.91 이상, GitHub 저장소 연결이 필요하다. Preview 기능은 정식 출시 전 변경될 수 있으므로, 프로덕션 환경에서의 의존은 주의가 필요하다.
Claude Code 웹 인터페이스에서 Ultraplan을 활성화하면 계획 수립이 백그라운드에서 진행되는 동안 터미널을 자유롭게 사용할 수 있다. 팀원이 브라우저에서 인라인 코멘트와 이모지 반응으로 계획을 검토·승인하면 로컬 환경에서 다음 중 하나를 선택할 수 있다.
| 선택지 | 동작 |
|---|---|
| Implement here | 현재 터미널에서 즉시 구현 시작 |
| Start new session | 새 세션에서 구현 시작 |
| Cancel | 계획을 파일로 저장만 함 |
정확한 UI 흐름(알림 방식, 승인 다이얼로그 형태 등)은 Claude Code 버전과 실행 환경(로컬 터미널 vs 웹 인터페이스)에 따라 다를 수 있다.
장단점 분석
장점
이 워크플로를 실제로 적용해보면 가장 먼저 체감하는 변화는 '실수를 저지를 기회 자체가 없다'는 점이다. 수십 개 파일에 걸친 auth 모듈 추출 작업에서 Plan Mode를 유지하는 동안 의도치 않은 파일 변경 사고는 한 건도 발생하지 않았다. 분석 단계에서 Claude가 놓친 의존성을 인라인 주석으로 세 차례 보완했고, 이 과정이 구현 단계에서의 임포트 경로 충돌을 사전에 막아냈다.
| 항목 | 내용 |
|---|---|
| 안전한 분석 단계 | Plan Mode의 읽기 전용 강제로 분석 중 의도치 않은 파일 변경을 원천 차단 |
| 깊은 추론 품질 | /effort max + ultrathink 조합으로 복잡한 의존성·아키텍처 패턴을 정확하게 분석 |
| 인간 검토 게이트 | 구현 전 계획을 편집기에서 직접 검토·수정할 수 있어 AI 판단 오류를 사전 차단 |
| 컨텍스트 보존 | Plan Mode에서 얻은 분석이 구현 단계로 이어져 일관성 유지 |
| 점진적 실행 | 세션 단위로 분리하여 각 단계의 테스트 통과를 확인하며 진행 가능 |
단점 및 주의사항
| 항목 | 내용 | 대응 방안 |
|---|---|---|
| 컨텍스트 한계 | 200K 토큰 초과 시 대화가 자동 압축되어 Claude가 맥락을 잃을 수 있음 | 세션을 모듈 단위로 분리, CLAUDE.md로 핵심 컨텍스트를 압축 보존 |
| 아키텍처 패턴 무시 | CLAUDE.md 없이 대규모 저장소에 투입 시 컨벤션을 모르는 코드가 생성될 수 있음 | Plan Mode 진입 전 CLAUDE.md에 컨벤션·금지 패턴을 명시 |
| 숨겨진 버그 | 레이스 컨디션, DB 연결 한계처럼 코드 리뷰로는 드러나지 않는 문제가 AI 생성 코드에 잠복할 수 있음 | 통합 테스트와 부하 테스트를 계획 단계부터 검증 기준에 포함 |
| 계획 이탈 | Claude가 auth와 routes를 동시에 건드려 반쯤 마이그레이션된 코드베이스가 생길 수 있음 | 계획의 각 단계에 검증 기준 명시, 한 단계 완료 후 다음 단계 진행 |
| 비용 | /effort max는 토큰 소비가 빠르고 단순 작업에도 불필요한 비용 발생 | 계획 단계만 max, 구현 단계는 medium/high로 조정 |
컨텍스트 압축(compact)이란 Claude Code가 대화 히스토리가 컨텍스트 한계에 근접할 때 자동으로 과거 메시지를 요약·압축하는 동작이다. 이 과정에서 세부 분석 내용이 손실될 수 있으므로, 중요한 계획은 반드시
plan.md파일로 외부에 저장해두는 것이 안전하다.
실무에서 가장 흔한 실수
- CLAUDE.md 없이 Plan Mode를 시작하는 것 — 프로젝트 컨벤션, 아키텍처 원칙, 금지 패턴이 명시되지 않으면 Claude는 기술적으로는 올바르지만 팀 표준과 맞지 않는 계획을 생성한다. Plan Mode 진입 전 CLAUDE.md를 먼저 정비하는 것을 권장한다.
- 계획에 검증 기준을 포함하지 않는 것 — "auth/ 추출 완료"처럼 모호한 단계 대신 "
pnpm test auth/전체 통과"처럼 구체적인 검증 기준을 명시해야 계획 이탈(Plan Drift)을 조기에 감지할 수 있다. - 세션 전체에 /effort max를 유지하는 것 — 계획 수립 단계에서만 max를 적용하고, 루틴한 구현 단계는 medium/high로 낮추는 방식이 비용 효율적이다.
ultrathink키워드로 핵심 턴만 선택적으로 격상하는 방법도 좋은 대안이다.
마치며
Plan Mode와 /effort max의 조합은 "AI가 코드를 더 빠르게 바꾸는 도구"가 아니라 "인간이 계획을 더 깊이 검토할 수 있는 구조"를 만들어주는 워크플로다. 속도보다 안전이 중요한 대규모 리팩터링에서 이 철학은 특히 강력하게 작동한다. 실제로 수십 개 파일, 세 개 모듈을 수정하는 리팩터링을 이 워크플로로 진행했을 때 계획 이탈 없이 모든 단계를 순서대로 완료할 수 있었다.
지금 바로 시작해볼 수 있는 3단계:
- 리팩터링 대상 프로젝트의 루트에
CLAUDE.md파일이 없다면 먼저 만들어보시면 좋습니다. 프로젝트 컨벤션, 아키텍처 원칙, 절대 변경하지 않아야 할 패턴을 간략히 적어두는 것으로 시작할 수 있습니다. - Claude Code를 열고
/effort max를 입력한 뒤Shift+Tab을 두 번 눌러 Plan Mode로 진입해보시면 좋습니다. 가장 오래된 tech debt 중 하나를 골라 아래 프롬프트를 그대로 활용해볼 수 있습니다.
ultrathink. [대상]의 영향 범위와 단계별 계획을 수립해줘.
각 단계에 검증 기준을 포함하고, 코드는 건드리지 마.- Claude가 생성한 계획을
plan.md로 저장하고 에디터에서 직접 검토하면서 의문스러운 부분에 주석을 추가해보시면 좋습니다. 만족스러운 계획이 완성된 뒤에야 Plan Mode를 해제하고 구현을 시작하는 습관을 들여보시면 됩니다.
이 시리즈의 다음 편: CLAUDE.md 작성 가이드 — AI 코딩 에이전트가 프로젝트 컨텍스트를 올바르게 이해하도록 지시 파일을 구조화하는 방법
참고 자료
- Common Workflows | Claude Code 공식 문서
- Ultraplan | Claude Code 공식 문서
- Model Configuration | Claude Code 공식 문서
- Effort | Claude API 공식 문서
- Adaptive Thinking | Claude API 공식 문서
- Claude Code Plan Mode: Design Review-First Refactoring Loops | DataCamp
- Claude Code Best Practices | DataCamp
- Claude Code /effort Explained | Vincent's Blog
- Claude Code Effort Levels Explained | MindStudio
- Claude Code's Ultraplan Bridges the Gap Between Planning and Execution | DevOps.com
- What is /effort Command in Claude Code | ClaudeLog
- Claude Code Planning Mode: Shift+Tab Twice | claudefa.st
- Using Claude Code and Aider to Refactor Large Projects | Codenotary
- Plan Mode in Claude Code | codewithmukesh
- Unlocking Claude Code's Hidden Thinking Levels: From 'Think' to 'Ultrathink' | mauricioacosta.dev