Plan Mode와 '탐색→계획→실행' 루틴

AI 코딩 에이전트는 성실합니다. 문제는 그 성실함이 종종 "너무 빠른 손"으로 나타난다는 점입니다. 특히 다중 파일 변경, 큰 리팩터링, 요구사항이 덜 정리된 작업에서는 한 번의 성급한 실행이 연쇄 수정(나비효과)으로 이어집니다. 한 파일을 고치자마자 다른 파일이 깨지고, 그걸 고치자 설정이 흔들리고, 결국 "어디서부터 틀어진 건지"를 되짚느라 시간을 잃습니다.

Plan Mode는 이 흐름을 끊기 위한 안전장치입니다. 핵심은 기능이 아니라 습관입니다. 복잡한 작업일수록 '코드부터'가 아니라 지도부터입니다.

Plan Mode란 무엇인가

Plan Mode는 Claude Code의 권한 모드 중 하나로, 에이전트가 프로젝트를 읽고·찾고·분석하고·질문하고·계획을 쓰는 것까지만 허용하고, 실제 변경(파일 수정/명령 실행 같은 부작용)은 막아 둔 상태입니다.

이 제약이 중요한 이유는 단순합니다. 사람이든 에이전트든 "손이 먼저 움직이면" 머리는 뒤늦게 합리화를 시작합니다. Plan Mode는 아예 손을 묶어 두고, 머리로 먼저 정렬하게 만듭니다.

다음 표처럼 이해하면 쉽습니다.

UI 조작(단축키/슬래시 커맨드) 자체는 4장에서 다뤘습니다. 이 장에서는 "왜, 언제, 어떻게" Plan Mode를 루틴으로 굳히는지에 집중합니다.

언제 Plan Mode를 "무조건" 켜야 하나

아래에 해당하면, 거의 예외 없이 Plan Mode가 이득입니다.

• 10개 이상 파일이 연쇄로 바뀔 가능성이 있을 때

• 리팩터링/마이그레이션처럼 되돌리기 비용이 큰 변화일 때

• 문제 원인이 불명확한 버그처럼 탐색 자체가 작업의 절반일 때

• 레거시/합류 초기처럼 코드베이스 지형을 모를 때

반대로 한 줄 수정, 명확한 단일 파일 변경처럼 "내가 원하는 diff를 한 문장으로 정확히 말할 수 있는" 작업은 Plan Mode 없이도 빠르게 끝납니다.

여기서 실전 규칙 하나만 기억하면 됩니다.

"내가 한 문장으로 정확한 diff를 말할 수 없으면, 먼저 Plan Mode."

이 규칙이 리워크를 가장 크게 줄입니다.

'탐색→계획→실행' 루틴의 설계

Plan Mode를 잘 쓰는 사람의 공통점은, 계획을 '문서'로 끝내지 않고 실행 가능한 순서로 바꾼다는 점입니다. 이 장에서는 다음 3단계를 기본 루틴으로 제안합니다.

탐색(Explore): 지도를 그리는 시간

탐색 단계의 목표는 "정답을 내기"가 아니라 지형을 확보하는 것입니다. 에이전트에게 다음을 하게 만드세요.

• 엔트리포인트(요청이 들어오는 지점)와 종료점(결과가 소비되는 지점)

• 관련 모듈의 경계(어떤 폴더/레이어가 책임을 갖는지)

• 호출 관계(누가 누구를 부르는지)와 데이터 흐름(값이 어떻게 이동하는지)

탐색 프롬프트는 길 필요가 없습니다. 대신 산출물을 고정하세요.

예시:

(Plan Mode) 이 기능과 관련된 코드 경로를 파일 목록 + 한 줄 설명으로 정리해줘. 특히 "진입점/핵심 도메인/영향받는 외부(DB, API, 큐, 캐시)"를 구분해줘.

이 단계에서 에이전트가 먼저 질문을 던지도록 유도하는 것도 중요합니다. 모호한 요구사항을 탐색 단계에서 드러내면, 실행 단계의 수정 횟수가 급감합니다.

계획(Plan): '승인 가능한 문서' 만들기

좋은 계획은 "무엇을 할지"뿐 아니라 "무엇을 하지 않을지"를 포함합니다. 계획 문서는 최소한 다음 네 가지를 갖춰야 합니다.

첫째, 변경 범위입니다. 어떤 파일이 바뀌는지, 새로 생기는 파일이 있는지, 변경이 퍼질 수 있는 곳(공용 타입, 공용 유틸, 설정)을 표시해야 합니다.

둘째, 변경 순서입니다. 다중 파일 작업은 순서가 품질입니다. 먼저 바꿔야 하는 것(타입/인터페이스)과 나중에 따라오는 것(호출부/테스트)을 뒤집으면, 중간 상태가 불안정해집니다.

셋째, 리스크와 대안입니다. 이 작업이 깨기 쉬운 포인트(호환성, 마이그레이션, 롤백)를 계획에 적어두면, 실행 중 "예상 밖의 깨짐"이 "예상된 깨짐"으로 바뀝니다.

넷째, 검증 절차(How to verify) 입니다. 빌드/테스트/린트/타입체크 중 무엇을 어떤 순서로 돌릴지, 그리고 성공 기준이 무엇인지가 계획에 포함되어야 합니다.

계획을 요청할 때는 형식을 강제하는 편이 좋습니다.

예시:

(Plan Mode) 다음 형식으로 계획을 써줘.

1. 목표(한 문장)

2. 영향 범위(바뀌는 파일/추가 파일/건드리지 않을 영역)

3. 구현 순서(단계별)

4. 위험 요소와 대응(롤백 포함)

5. 검증 절차(실행할 명령과 기대 결과)

추가 조건: 새 라이브러리 도입 금지, 기존 패턴/폴더 구조 준수.

그리고 계획은 "한 번에 완벽"할 필요가 없습니다. 오히려 Plan Mode의 진짜 가치가 여기서 나옵니다.

계획을 읽고, 틀린 가정을 찾아내고, 질문을 되돌려서, 계획을 다시 받는 반복이 실행 단계의 재시도를 없애 줍니다.

실행(Implement): 계획대로 '작게' 전진하기

계획이 승인되면 실행 단계로 넘어갑니다. 이때 중요한 포인트는 "에이전트가 똑똑하니 맡기자"가 아니라, 승인된 계획의 경계를 유지한 채 속도를 내자입니다.

실행 단계에서 가장 효과적인 운영 방식은 다음과 같습니다.

• 큰 작업을 단계(Phase) 로 쪼개고, 각 단계마다 빌드/테스트를 돌린다.

• 한 단계가 끝나면 "무엇을 바꿨는지"를 요약 + 파일 목록으로 보고받는다.

• 예상과 다른 변경이 나오면 즉시 멈추고, Plan Mode로 돌아가 계획을 수정한다.

다중 파일/리팩터링에서는 특히 "중간 상태가 오래 유지되는 것"이 위험합니다. 작은 단위로 자주 검증하면, 문제가 생겨도 원인이 가까운 곳에 있습니다.

Plan Mode가 리워크를 줄이는 방식(나비효과 차단)

나비효과는 대개 세 가지 경로로 커집니다.

첫째, 에이전트가 코드베이스의 관례를 모르고 새로운 패턴을 섞어 넣을 때입니다. Plan Mode의 탐색은 "우리 프로젝트는 원래 이렇게 한다"를 먼저 확인하게 만듭니다.

둘째, 변경이 경계(모듈/레이어) 를 넘어가며 확산될 때입니다. 계획 단계에서 '영향 범위'를 파일 단위로 명시하면, 확산이 눈에 보이기 시작합니다.

셋째, 검증 없이 진행해 오류가 뒤늦게 누적될 때입니다. 계획에 검증 절차를 먼저 박아두면, 실행 단계가 "수정 → 확인 → 다음"으로 리듬을 갖습니다.

즉 Plan Mode는 "코딩을 잘하게"가 아니라, 실패 비용을 싸게 만듭니다.

실전 템플릿: 다중 파일 리팩터링 계획 받기

리팩터링은 '기능 추가'보다 계획이 더 중요합니다. 왜냐하면 바뀌는 게 기능이 아니라 관계이기 때문입니다.

아래 템플릿은 특히 효과가 좋습니다.

(Plan Mode) 리팩터링 목표: A 모듈을 B/C/D로 분리한다.

제약:

• 공개 API(함수 시그니처/엔드포인트/이벤트 스키마)는 바꾸지 않는다.

• 새 의존성 추가 금지.

• 테스트는 기존 프레임워크/스타일을 따른다.

계획 산출물:

• 이동/분리 기준(어떤 책임이 어디로 가는지)

• 업데이트가 필요한 import/call site의 범위

• 단계별 실행 순서(각 단계의 검증 포함)

• 롤백 전략(되돌리기 지점)

이 템플릿의 핵심은 "어떻게"를 지시하는 게 아니라, 깨지면 안 되는 것과 계획이 포함해야 할 항목을 못 박는 것입니다.

계획 품질 체크리스트(승인 전에 이것만 본다)

계획을 승인하기 전에, 아래 질문에 "예"라고 말할 수 있어야 합니다.

• 바뀌는 파일이 대략적으로라도 목록화되어 있는가?

• 작업이 단계로 쪼개져 있고, 단계 간 의존이 자연스러운가?

• 각 단계마다 검증 방법이 있으며, 성공/실패 기준이 명확한가?

• "이 계획이 틀렸을 때"를 대비한 롤백/중단 지점이 있는가?

승인은 '동의'가 아니라 책임의 시작입니다. 계획이 빈약한데 실행을 승인하면, 결국 사람이 나중에 책임을 떠안게 됩니다.

흔한 실수와 교정

실수 1: Plan Mode에서 "그럼 실행해"라고 말하고 멈춰 있기

Plan Mode는 실제 변경이 막혀 있습니다. 승인 문장을 쳤는데도 아무 일이 안 일어나면, 대개 아직 Plan Mode에 남아 있는 상태입니다. 이때는 실행 모드로 전환한 뒤, "승인한 계획의 1단계부터 수행해라"처럼 범위를 다시 고정해 주세요.

실수 2: 계획이 너무 거대해서 검증이 뒤로 밀림

"한 번에 다 바꾸고 마지막에 테스트"는 사람도 위험하고, 에이전트는 더 위험합니다. 계획 단계에서부터 검증을 끼워 넣는 구조로 바꿔야 합니다. 예를 들어 "타입 변경 → 타입체크" 같은 짧은 사이클을 단계로 포함시키세요.

실수 3: 계획은 승인했는데 실행이 슬쩍 다른 길로 샘

실행 중 에이전트가 예상 밖의 파일까지 바꾸려 한다면, 그건 대개 계획이 충분히 구체적이지 않았거나(경계가 없음), 탐색이 부족해서(숨은 의존을 놓침) 실행 단계에서 뒤늦게 발견된 것입니다. 이런 경우는 멈추고 Plan Mode로 돌아가 영향 범위와 순서를 업데이트하는 게 가장 싸게 끝납니다.

오늘부터 쓰는 10분 루틴

복잡한 작업을 시작할 때마다, 아래 3문장을 몸에 붙이세요.

첫째, "먼저 탐색해서 관련 파일 지도를 그려줘."

둘째, "그 지도를 바탕으로, 변경 범위/순서/리스크/검증을 포함한 계획을 써줘."

셋째, "계획의 1단계만 실행하고, 검증 결과와 바뀐 파일 목록을 보고해줘."

이 루틴은 결국 '탐색→계획→실행'이 아니라, 실제 현장에서는 탐색→계획→(1단계 실행→검증)×N 입니다. 이 반복이 리워크를 줄이고, 다중 파일 작업에서 가장 무서운 나비효과를 통제 가능한 비용으로 바꿉니다.