07. 계획(Plan)과 실행

🎯 이 장의 목표

Plan Mode가 무엇이고 왜 강력한지 이해한다
언제 계획을 세우고, 언제 건너뛰어야 하는지 판단한다(한 문장 규칙)
계획 → 실행 전환에서 Claude가 "탈선"하지 않게 하는 법을 안다
계획 파일을 어디에 저장하고 어떻게 활용하는지 안다

Plan Mode란

Plan Mode는 Claude Code의 읽기 전용 운영 모드입니다. 이 모드에서 Claude는 코드베이스 전체를 분석하고, 명확히 할 점을 묻고, 상세한 구현 계획을 세울 수 있지만 — 파일을 수정하거나 명령을 실행하지는 못합니다.

비유하자면, 외과의가 수술 전에 영상을 보고 절개 계획을 세우는 단계입니다. 칼을 대기 전에 "어디를, 어떻게, 어떤 순서로"를 정하는 것이죠.

stateDiagram-v2
    [*] --> Plan: Shift+Tab 또는 /plan
    Plan: Plan Mode (읽기 전용)
    Plan --> Plan: 코드 분석·질문·계획 수립
    Plan --> Execute: 계획 승인
    Execute: 실행 모드 (수정 가능)
    Execute --> Plan: Shift+Tab / 다시 계획
    Execute --> [*]: 작업 완료

    note right of Plan
        파일 수정·명령 실행 불가
        오직 탐색과 계획만
    end note

왜 계획이 중요한가

Anthropic과 숙련 사용자들이 입을 모으는 베스트 프랙티스 1순위가 "구현 전 계획" 입니다. AI를 무작정 달리게 두면 엉뚱한 방향으로 질주하기 쉽습니다. 계획은 이 역학을 뒤집습니다.

한 사용자의 경험담: 계획을 건너뛰면 작업을 처음부터 다시 하는 비율이 약 40%, 즉 시간·토큰·집중력·인내심의 낭비였다고 합니다. 계획을 먼저 세우면 이 낭비가 크게 줄어듭니다.

📌 핵심: Plan Mode는 "탐색 → 계획 → 검토 → 구현" 흐름을 강제합니다. 검토 단계에서 오해를 일찍 잡아내는 것이 가장 큰 가치입니다.

언제 계획하고, 언제 건너뛸까: 한 문장 규칙

"diff(변경 내용)를 한 문장으로 정확히 묘사할 수 있으면 계획을 건너뛴다. 못 하면 계획부터 한다."

이 규칙은 Anthropic 공식 베스트 프랙티스와도 통합니다. 계획이 가장 유용한 경우:

계획이 유용한 상황	계획이 과한 상황
접근법이 불확실할 때	"오타 하나 고쳐줘"
여러 파일을 건드리는 변경	한 줄 추가
아키텍처 선택이 필요할 때	명백한 단순 작업
요구사항이 모호해 탐색이 필요할 때	이미 방법이 분명한 작업

⚠️ 과잉 계획도 낭비입니다. 단순 작업까지 매번 계획하면 시간만 잡아먹습니다. 한 문장 규칙으로 판단하세요.

모드 전환하는 법

Plan Mode는 채팅으로 "계획 모드로 바꿔줘"라고 부탁하는 게 아니라 정해진 조작으로 켭니다.

세션 중 Shift+Tab 으로 모드를 순환: default → acceptEdits → plan
또는 다음 프롬프트 앞에 /plan 을 붙이기
현재 모드는 상태 표시줄에 나타납니다

프로젝트 기본 모드를 plan으로 두려면 .claude/settings.json에 defaultMode를 설정합니다(→ 10장, 부록 B).

계획 → 실행 전환: 탈선 막기

계획을 승인하면 Plan Mode를 빠져나와 실행 모드로 전환되고, Claude가 편집을 시작합니다. 그런데 종종 "계획엔 없던 파일·패턴을 추가" 하는 탈선이 일어납니다. 보통 계획이 너무 모호했거나, 실행 프롬프트가 계획을 참조하지 않았을 때 생깁니다.

대응책:

CODE

✅  실행 전환 후 명시적으로:
    "계획대로 정확히 구현해. 계획에 없는 건 추가하지 마."

✅  모드 전환 전 Ctrl+G 로 계획을 에디터에서 열어
    제약을 직접 명확히 적어두기

💡 팁

컴팩션이 계획 맥락을 날릴까 걱정되면, /compact 상품 필터링 계획과 구현 결정에 집중 처럼 무엇을 보존할지 알려주세요(→ 4장).

계획 파일 관리

기본적으로 계획 파일은 ~/.claude/plans/에 jaunty-petting-nebula.md 같은 자동 생성 이름으로 저장됩니다 — 세션이 끝나면 찾기 어렵죠. 개선법:

.claude/settings.json(프로젝트 단위)에 plansDirectory를 ./docs/plans 같은 프로젝트 내 경로로 지정
생성된 계획을 2026-02-25-add-filtering.md처럼 의미 있는 이름으로 변경

💡 팁

계획 = PR 설명: 큰 기능이라면 계획 내용을 그대로 PR 본문에 붙이세요. 리뷰어가 "계획한 것 vs 실제 만든 것"을 한눈에 비교할 수 있습니다. 반대로 빠른 작업은 계획을 저장조차 안 해도 됩니다 — 세션 중 역할만 하면 충분합니다.

정말 큰 작업이라면

여러 바운디드 컨텍스트에 걸치거나 병렬 작업 스트림이 필요한 거대 기능은 단일 Plan Mode 세션으로 부족합니다. 그럴 땐 여러 Claude 인스턴스가 공유 작업 목록으로 협업하는 에이전트 팀(Agent Teams) 으로 넘어갑니다(→ 13장).

이 장에서 배운 것

Plan Mode는 읽기 전용 모드로, 파일을 건드리기 전에 탐색·질문·계획만 한다.
베스트 프랙티스 1순위는 구현 전 계획. 검토 단계에서 오해를 일찍 잡는 게 핵심 가치다.
한 문장 규칙: diff를 한 문장으로 묘사 가능하면 계획 생략, 아니면 계획부터.
모드는 Shift+Tab 순환 또는 /plan 으로 켜고, 채팅 부탁이 아니라 조작으로 바꾼다.
실행 전환 시 "계획대로만"을 명시하고, 계획 파일은 plansDirectory로 프로젝트에 보관한다.

✍️ 확인 문제

Plan Mode에서 Claude가 할 수 없는 일은 무엇인가요?
계획을 세울지 말지 판단하는 "한 문장 규칙"을 설명해 보세요.
계획 승인 후 Claude가 계획에 없던 변경을 추가하는 "탈선"을 막는 방법 두 가지는?

다음 장: 08. 권한과 승인 모델 — Claude가 무엇을 묻고 무엇을 알아서 할지 통제합니다.

← 이전06. 코드베이스 탐색과 파일 작업다음 →08. 권한과 승인 모델