Claude Code /plan: AI가 코드 건드리기 전에 '계획부터' 받기

AI한테 코딩을 시킬 때 제일 무서운 게 뭘까요? 바로 시키지도 않은 걸 막 고쳐버리는 것입니다. 한 줄만 바꾸랬더니 파일 열 개를 건드려 놓는 거죠. Claude Code의 /plan은 이 사고를 막는 안전벨트예요. "일단 손대지 말고, 어떻게 할 건지 말로 먼저 설명해봐"라고 시키는 명령입니다.

/plan이 뭐냐면

실행은 멈추고 계획부터 세우는 모드입니다. Claude가 바로 손대지 않고 "이렇게 하겠습니다"라는 계획서를 먼저 보여주고, 여러분이 승인하면 그때 실행해요.

작동 원리는 간단합니다. plan 모드(계획 모드 — 코드를 분석만 하고 수정은 막아두는 상태)에 들어가면 Claude는 '읽기'만 하고 '쓰기'는 잠급니다. 코드를 살펴보고 계획서를 내놓을 뿐, 여러분이 "OK" 하기 전까진 한 글자도 안 바꿔요. 마치 공사 들어가기 전에 도면부터 검토받는 것과 같습니다.

어떻게 쓰나 (난이도별)

plan 모드는 어떻게 들어가고 나오나

먼저 가장 헷갈리는 부분부터 짚을게요. plan 모드에 들어가는 방법은 두 가지입니다.

1. 명령어로: 입력창에 /plan을 치고 엔터 — 바로 계획 모드로 전환됩니다.

2. 단축키로: 대화 도중 Shift+Tab(Shift 키를 누른 채 Tab 키)을 누르면 모드가 순환합니다. 누를 때마다 화면 하단 입력창 근처에 현재 모드(예: plan mode on)가 표시돼요. 다시 누르면 일반 실행 모드로 돌아옵니다.

명령어 한 번 칠 필요 없이 Shift+Tab만 톡톡 누르면 모드를 오갈 수 있어서, 익숙해지면 이 방법이 더 빠릅니다.

명령을 친 뒤 화면이 어떻게 되나

/plan으로 작업을 시키면 Claude가 코드를 곧장 고치지 않고 번호가 매겨진 계획서를 출력합니다. "1. 이 파일을 읽는다 → 2. 여기에 함수를 추가한다 → 3. 테스트를 돌린다" 같은 식이에요. 계획서 끝에는 보통 승인을 묻는 안내가 뜹니다. 여기서 여러분이 할 일은 둘 중 하나예요.

• 마음에 들면: 승인(보통 엔터 또는 표시된 선택지에서 "예" 선택) → 그제야 Claude가 실제로 코드를 고치기 시작합니다.

• 고칠 게 있으면: 승인하지 말고 그냥 말로 "3번 단계는 빼줘"처럼 수정 요청 → Claude가 계획을 다시 짜줍니다.

핵심은 내가 OK 하기 전엔 아무 일도 안 일어난다는 것. 그래서 마음 놓고 계획을 뜯어볼 수 있어요.

기초 — 계획 모드 진입

/plan

실행을 멈추고 계획 모드로 들어갑니다. 이후 시키는 작업은 전부 "먼저 계획서로" 받게 돼요.

응용 — 작업과 함께

/plan 로그인 버그 고쳐줘

고치기 전에 단계별 계획을 먼저 제시합니다. 모드 진입과 작업 지시를 한 번에 하는 셈이에요.

심화 — 대규모 설계

/plan 결제 모듈을 토스페이먼츠로 교체

범위가 큰 작업일수록 곧바로 손대면 위험합니다. 이런 건 계획·검토를 거친 뒤 실행하는 게 안전해요.

★ 흔한 함정 — 계획을 안 읽고 바로 승인

입문자가 제일 많이 하는 실수가 이겁니다. 급한 마음에 계획서가 뜨자마자 내용은 안 읽고 엔터부터 눌러버리는 거예요. 그러면 /plan을 쓰는 의미가 통째로 사라집니다. 계획 없이 그냥 시킨 거랑 똑같아지니까요.

/plan의 진짜 가치는 계획서를 읽다가 "어, 이 파일은 왜 건드리지?" 하는 한 줄을 잡아내는 데 있습니다. 예를 들어 "로그인 버그 고쳐줘"라고 했는데 계획에 결제 관련 파일을 수정한다는 단계가 끼어 있다면, 그건 승인 전에 막아야 할 신호예요.

습관 하나만 들이세요: 계획서는 5초라도 끝까지 읽고 승인. 5초 읽고 5분(혹은 그 이상)을 아끼는 겁니다.

실전 사례

중요한 결제 코드를 건드리기 전에 /plan으로 계획만 먼저 받았습니다. 계획서를 읽어보니 결제 실패 시 예외 처리(에러가 났을 때 어떻게 대응할지 정해두는 코드)가 빠져 있더군요. 그래서 승인하지 않고 "결제 실패 케이스 예외 처리도 추가해줘"라고 보완을 요청한 뒤 실행시켰습니다. 만약 계획을 안 보고 그냥 돌렸다면 결제 사고로 이어질 수도 있었던 거죠. 계획서 한 번 읽은 덕에 사고를 미리 막은 셈입니다.

이렇게 더 씁니다

• 계획 → 구현 → 리뷰 3단 콤보: /plan으로 설계를 승인받아 실행하고, 끝나면 /code-review(코드 점검 명령)로 검토. 큰 기능을 안전하게 마무리하는 기본 파이프라인입니다.

• 계획서를 문서로 남기기: "이 계획을 plan.md로 저장해줘"라고 하면 파일로 남겨 팀과 공유하거나 나중에 다시 쓸 수 있습니다.

• 여러 안 비교: "A안(빠른 방법)과 B안(정석)을 각각 계획해줘"처럼 시키면, 두 설계를 나란히 비교한 뒤 고를 수 있습니다.

• 계획 자체를 수정: 승인하기 전에 "3번 단계는 빼고, Redis 대신 메모리 캐시로 바꿔"처럼 계획을 다듬으면 결과 정확도가 크게 올라갑니다. 계획서는 고정된 게 아니라 협의 대상이에요.

• 더 큰 공사는 /ultraplan으로: 코드베이스 전체에 걸친 대규모 설계는 /ultraplan으로 클라우드에서 계획을 짜고 브라우저로 검토할 수 있습니다.

직접 해보기

아무 프로젝트나 열고 이렇게 쳐보세요.

/plan 이 프로젝트에 다크모드 추가해줘

Claude가 코드를 곧바로 고치지 않고 계획만 쭉 뽑아낸다면 성공입니다. 그다음 계획을 읽다가 마음에 안 드는 부분을 한 군데 골라 "이 단계는 이렇게 바꿔줘"라고 요청해보세요. 계획이 다시 짜이는 걸 보면 "아, 승인 전엔 내가 핸들을 쥐고 있구나" 하는 감이 옵니다.

다른 사람들은 이렇게 씁니다 (웹 사례)

• 기존 Google OAuth 옆에 GitHub SSO를 붙일 때, Claude가 기존 패턴을 분석해 완전한 구현 계획을 먼저 제시했다. — Claude Code, Real Workflows: Plan Mode & Specs (Medium)

• "계획을 검토·승인하기 전엔 코드를 못 쓰게 한다"는 원칙으로 토큰을 아끼고 품질을 높였다. — How I Use Claude Code (Boris Tane)

• 코드를 쓰기 전에 생각부터 — plan 모드로 설계를 먼저 잡는 워크플로. — 클로드 코드 계획 모드 (Dale Seo)

정리

중요한 작업일수록 plan 먼저입니다. 진입은 /plan 또는 Shift+Tab, 계획서가 뜨면 끝까지 읽고 승인 — 이 순서만 몸에 익히면 됩니다. 함정 하나만 기억하세요: 계획을 안 읽고 바로 승인하면 plan을 쓰는 의미가 없습니다. 5초 읽고 5분 아끼는 습관, 오늘부터 들여보세요.

기준: Claude Code v2.1.154