Claude Code: Safely Refactor Large-Scale Using Plan Mode + /effort max

How to proceed without code corruption using read-only analysis

Large-scale refactoring is always a close call. Any developer has likely experienced the frustration of tweaking a single auth module only to have the build break with routes half-migrated before they knew it, only to discover in production that changes they spent weeks working on contained race conditions. This article discusses in detail in the [Disadvantages and Precautions] section how bugs—like race conditions—that are not easily detected by code reviews can hide within AI-generated code. Introducing AI coding agents does not eliminate this problem. In fact, if AI operates by "opening files and fixing them without a plan," it can break the code faster and over a wider scope.

Claude Code provides two tools to structurally solve this problem: Plan Mode, which performs analysis without touching files, and the /effort command, which controls the depth of internal inference prior to the response. Combining these two creates a workflow where "the plan is completed first, its quality is maximized, and then implementation begins."

After reading this article, you will learn how Plan Mode and /effort work, the golden combination patterns for these two functions, and how to avoid common pitfalls encountered in practice, enabling you to apply them immediately to your next refactoring session. If you are new to Claude Code, it is recommended that you first check out the Official Documentation.

Key Concepts

Plan Mode: Read-only analysis phase

One-line Summary: Safe mode that structurally blocks code changes while allowing only analysis and planning

Plan Mode is a read-only mode activated by double-clicking Shift+Tab in Claude Code. In this mode, Claude can only perform the following three actions.

• File reading and codebase navigation
• Architecture Understanding and Dependency Analysis
• Draft execution plan and generate questions

Shell commands for writing, editing, modifying the file system, and changing the state of files are blocked. Whether read-only shell queries such as git status and ls are allowed may vary depending on the version. This is a safety mechanism that structurally makes it impossible for the AI to unintentionally modify files during analysis.

Plan Mode is a read-only analysis phase in Claude Code that enforces only architecture understanding and execution plan formulation without code modification. It is entered twice and blocks implementation until the plan is complete.

/effort: Inference depth control

One-line Summary: A command to set the token budget available for internal inference before Claude's response on a session basis

The /effort command adjusts the thinking budget that Claude can use for internal reasoning before responding. It is applied persistently throughout the session and supports five levels.

/effort low     # 빠른 응답, 단순 작업에 적합
/effort medium  # 기본값 (Pro/Max 구독자 기준, 2026년 초 high에서 변경)
/effort high    # 복잡한 분석, API 키·Team·Enterprise 기본값
/effort max     # 최고 수준 추론, 다단계 아키텍처 분석
/effort auto    # Claude가 작업 복잡도에 따라 자동 조정

Change in default value early 2026: The default value for /effort for Pro/Max subscribers has been lowered from high to medium. While this change optimized subscription rates, some users experienced reduced print quality, leading to backlash from the community. The default value remains high for API Key, Team, and Enterprise users.

The thinking budget is the maximum number of tokens Claude can use for internal reasoning before generating a response. A larger budget allows for longer thought chains but increases response time and cost. Since the cost difference between max and medium can be several times greater depending on task complexity, if you are cost-sensitive, it is recommended to check the thinking token fees on the official Anthropic pricing page.

Ultrathink: One-time Pepper Loan Trigger

One-line Summary: A keyword that requests highest level of inference only for that turn without changing session settings.

ultrathink is a per-turn override that, when included anywhere in a prompt, elevates the effort to high effort for that specific turn only. It is useful when requesting the highest level of inference only for specific analysis requests without changing the session-wide settings.

# 세션 기본값은 medium으로 유지하되,
# 계획 수립 턴에만 최고 수준 추론 적용
ultrathink. auth 모듈 의존성 전체를 분석해줘.

Ultrathink vs /effort max — /effort max is applied continuously throughout the session, while the ultrathink keyword is applied only once for that specific turn. If cost optimization is required, you can choose to selectively elevate only the key analysis turns using ultrathink.

Principle of Combining Two Functions

"plan first, max effort second" — First, fully understand and finalize the scope of changes in Read-Only Plan Mode. Then, secure the highest level of reasoning at each stage of planning and implementation using /effort max (or ultrathink).

If Plan Mode is the stage for safely deciding "what to change," /effort max plays the role of enhancing the quality of that decision. The two functions operate complementarily.

Practical Application

Example 1: Basic Pattern — Extracting the auth module

This is a scenario where authentication logic scattered across dozens of files is separated into an independent package. It is a typical risky task where a mistake can result in a jumbled import path.

# Step 1: 세션 전체에 최고 추론 적용
/effort max
 
# Step 2: Plan Mode 진입 (Shift+Tab 두 번)
# 터미널 프롬프트에 [PLAN] 표시가 나타남

# Step 3: Claude에게 입력하는 프롬프트 — 구현 금지 명시
ultrathink. auth 모듈 전체를 @auth-core 패키지로 추출하는 계획을 수립해줘.
영향받는 파일, 의존성, 잠재적 브레이킹 체인지를 모두 나열하고,
각 단계에 검증 기준(테스트 통과, 빌드 성공)을 포함해줘.
코드는 절대 건드리지 마.

When Claude generates plan.md, open it directly in the editor to review it. After adding inline comments for incorrect judgments or missing dependencies, you can return the modified file using Claude Code's @파일명 file reference syntax.

# Step 4: 주석 반영 요청 (여전히 Plan Mode 유지)
@plan.md의 모든 주석을 반영해서 계획을 수정해줘. 아직 구현하지 마.

# Step 5: 계획이 만족스러우면 Shift+Tab 한 번으로 Plan Mode 종료

# Step 5: 구현 시작 프롬프트
계획대로 1단계(테스트 작성)부터 시작해줘.

Example 2: Large Project — Session-based Session Separation

It is safer to separate large-scale refactoring that is difficult to fit into a single session into an independent session. This is because if the context limit (200,000 tokens) is exceeded, Claude could lose the context of his ongoing work.

# 세션 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/ 변경사항과 충돌하는 의존성에 특히 주의하고, 코드는 건드리지 마.

It is important to reanalyze the current codebase state in Plan Mode before starting each session, as changes from the previous session can affect the plan for the next.

Example 3: TDD Combined Pattern — Early Regression Detection

If you include the test writing step first in the plan generated by Plan Mode, regressions can be detected early.

# 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` 전체 통과

Once the plan is approved, exit Plan Mode and proceed step-by-step as shown below.

# 1단계만 먼저 진행하는 프롬프트
@plan.md의 1단계에 따라 auth/ 함수 테스트를 먼저 작성해줘.
테스트가 모두 통과하면 알려줘. 2단계 코드 추출은 아직 시작하지 마.

Example 4: CI/Automation Environment — Fixing Effort Level

# 환경변수로 effort 레벨 고정 (CI 파이프라인, 자동화 스크립트)
export CLAUDE_CODE_EFFORT_LEVEL=max

⚠️ CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 is an environment variable reported in the community, but it is a setting not verified in the official documentation. Before using it, it is recommended that you first check the official documentation for your current version of Claude Code.

Example 5 [Preview]: Team Collaboration — Using Ultraplan (v2.1.91+)

⚠️ Ultraplan is currently in Preview status (April 2026). Claude Code v2.1.91 or higher and a GitHub repository connection are required. As Preview features are subject to change before the official release, caution is advised regarding dependencies in production environments.

When you enable Ultraplan in the Claude Code web interface, you can freely use the terminal while planning takes place in the background. As team members review and approve the plan in a browser with inline comments and emoji reactions, you can choose one of the following in your local environment.

The exact UI flow (notification method, form of approval dialog, etc.) may vary depending on the Claude Code version and execution environment (local terminal vs. web interface).

Pros and Cons Analysis

Advantages

When actually applying this workflow, the first change you notice is that there is "no opportunity to make mistakes." During the auth module extraction task spanning dozens of files, not a single unintended file change occurred while maintaining Plan Mode. Dependencies missed by Claude during the analysis phase were supplemented three times using inline comments, and this process prevented import path conflicts during the implementation phase.

Disadvantages and Precautions

**Context compaction is a behavior in which Claude Code automatically summarizes and compresses past messages when the conversation history approaches the context limit. Since detailed analysis may be lost during this process, it is safe to save important plans externally as plan.md files.

The Most Common Mistakes in Practice

1. Starting Plan Mode without CLAUDE.md — If project conventions, architectural principles, and forbidden patterns are not specified, Claude generates plans that are technically correct but do not align with team standards. It is recommended to organize CLAUDE.md before entering Plan Mode.
2. Not including verification criteria in the plan — Instead of vague steps like "auth/ extraction complete," specific verification criteria like "pnpm test auth/ All passed" must be specified to detect plan drift early.
3. Maintaining /effort max throughout the session — It is cost-effective to apply max only during the planning phase and lower it to medium/high during the routine implementation phase. Selectively elevating only key turns using the ultrathink keyword is also a good alternative.

In Conclusion

The combination of Plan Mode and /effort max is a workflow that creates a structure allowing humans to review the plan more deeply, rather than a tool for AI to change code faster. This philosophy works particularly powerfully in large-scale refactoring where safety is more important than speed. In fact, when using this workflow for a refactoring involving dozens of files and three modules, we were able to complete all steps in sequence without deviating from the plan.

3 Steps to Start Right Now:

1. If there is no CLAUDE.md file in the root of the project being refactored, it is a good idea to create one first. You can start by briefly noting down project conventions, architectural principles, and patterns that should never be changed.
2. Open Claude Code, enter /effort max, and then press Shift+Tab twice to enter Plan Mode. You can select one of the oldest tech debts and use the prompt below as is.

ultrathink. [대상]의 영향 범위와 단계별 계획을 수립해줘.
각 단계에 검증 기준을 포함하고, 코드는 건드리지 마.

3. It is recommended to save the plan created by Claude as plan.md and review it directly in the editor, adding comments to any questionable parts. You should get into the habit of exiting Plan Mode and starting implementation only after a satisfactory plan is complete.

Next Part of This Series: CLAUDE.md Writing Guide — How to Structure Instruction Files So AI Coding Agents Correctly Understand Project Context

Reference Materials

• Common Workflows | Claude Code Official Documentation
• Ultraplan | Claude Code Official Documentation
• Model Configuration | Claude Code Official Documentation
• Effort | Claude API Official Documentation
• Adaptive Thinking | Claude API Official Documentation
• 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