클로드 코드 Plan 모드: 코드를 쓰기 전에 생각부터

클로드 코드에게 “인증 시스템을 추가해줘”라고 요청하면 어떻게 될까요? Claude는 곧바로 파일을 수정하기 시작합니다. DB 스키마를 만들고 미들웨어를 작성하고 라우트를 추가하죠. 그런데 작업이 절반쯤 진행된 시점에 “아, JWT 대신 세션 기반으로 가고 싶었는데…”라는 생각이 든다면? 이미 수정된 파일들을 되돌려야 하는 번거로운 상황이 벌어집니다. 😅

이런 문제를 피하려면 코딩에 들어가기 전에 먼저 설계를 검토하는 단계가 필요합니다. 실제 개발에서도 PR을 올리기 전에 설계 문서를 작성하거나 팀원과 접근 방식을 논의하잖아요. Claude Code의 Plan 모드가 바로 이 역할을 합니다.

Plan 모드란?

Plan 모드는 Claude Code의 읽기 전용 분석 모드입니다. 이 모드에서 Claude는 코드베이스를 탐색하고 요청을 분석한 뒤 구체적인 구현 계획을 만들어 보여주는데요. 파일을 수정하거나 명령어를 실행하는 건 일절 하지 않습니다. 계획이 마음에 들면 승인해서 실행하고 마음에 안 들면 수정을 요청하면 됩니다.

Plan 모드에서 Claude가 할 수 있는 건 파일 읽기, 코드 검색(Grep, Glob), 웹 리서치 정도입니다. 반대로 파일 생성이나 수정, 셸 명령어 실행은 전부 막혀 있어요. 유일한 예외가 플랜 파일 자체인데 이건 뒤에서 다시 설명하겠습니다.

어떻게 활성화하나요?

Plan 모드를 켜는 방법은 여러 가지입니다.

가장 빠른 건 Shift+Tab을 두 번 누르는 겁니다. 입력창 옆에 모드 표시가 바뀌면서 Plan 모드로 전환되죠. 한 번 더 누르면 원래 모드로 돌아옵니다.

슬래시 명령어를 쓸 수도 있습니다.

/plan 인증 시스템을 JWT 기반으로 설계해줘

아니면 프롬프트에 자연어로 써도 됩니다. “먼저 plan 모드로 들어가서 분석해줘”라고 말하면 Claude가 EnterPlanMode 도구를 호출해서 Plan 모드에 진입합니다.

CLI에서 세션을 시작할 때부터 Plan 모드로 열 수도 있어요.

claude --permission-mode plan

5단계 워크플로우

Plan 모드에 들어가면 Claude는 내부적으로 5단계 워크플로우를 따릅니다. 이 과정을 이해하면 Claude가 왜 특정 순서로 작업하는지 감이 올 겁니다.

1단계: 코드베이스 파악. Claude가 최대 3개의 Explore 서브 에이전트를 병렬로 띄워서 프로젝트 구조와 기존 패턴을 파악합니다. Explore 에이전트는 Haiku 모델을 써서 빠르고 읽기 전용이라 코드가 바뀔 걱정이 없죠.

2단계: 설계. 1단계 결과를 바탕으로 Plan 서브 에이전트가 구현 방식을 설계합니다. 복잡한 작업이면 여러 Plan 에이전트를 띄워서 다른 접근 방식을 비교하기도 해요.

3단계: 검토. Claude가 핵심 파일을 직접 읽으면서 설계가 원래 요청과 맞는지 확인합니다. 불확실한 부분이 있으면 사용자에게 질문을 던져요.

4단계: 플랜 작성. 최종 계획을 마크다운 파일로 정리합니다. 추천 접근 방식, 수정할 파일 목록, 검증 방법(테스트 전략)이 포함되죠.

5단계: 제시. ExitPlanMode을 호출해서 계획을 사용자에게 보여줍니다. 이 시점에서 계획을 승인하면 Claude가 실행에 들어갑니다.

정리하면 탐색 → 설계 → 검토 → 작성 → 제시의 흐름인데요. 각 단계에서 서브 에이전트를 활용하기 때문에 메인 컨텍스트 윈도우를 절약하면서도 꼼꼼한 분석이 가능합니다.

플랜 파일

Plan 모드에서 만들어진 계획은 ~/.claude/plans/ 디렉토리에 마크다운 파일로 저장됩니다. 파일명은 quizzical-conjuring-whistle.md 같은 형태로 자동 생성되고요.

플랜 파일의 구조는 대략 이렇습니다.

# 인증 시스템 구현 계획

## 프로젝트 컨텍스트
Express + TypeScript 기반 REST API 서버

## 추천 접근 방식
JWT 기반 인증 + 리프레시 토큰 회전

### 구현 순서
1. User 모델에 password 필드 추가 (prisma/schema.prisma)
2. auth.service.ts 작성 - JWT 발급/검증 로직
3. auth.middleware.ts 작성 - 라우트 보호
4. auth.routes.ts 작성 - login/register/refresh 엔드포인트
5. 기존 라우트에 미들웨어 적용

## 수정 대상 파일
- prisma/schema.prisma
- src/services/auth.service.ts (신규)
- src/middleware/auth.middleware.ts (신규)
- src/routes/auth.routes.ts (신규)
- src/routes/index.ts (수정)

## 검증 방법
- 단위 테스트: JWT 발급/검증 로직
- 통합 테스트: 로그인 → 토큰 발급 → 보호된 라우트 접근

플랜 파일이 파일 시스템에 남기 때문에 세션이 끝나도 나중에 다시 참고할 수 있습니다. 컨텍스트 윈도우가 컴팩션될 때도 플랜 파일은 디스크에 보존되어서 Claude가 방향을 잃지 않는 데 도움이 됩니다.

저장 경로를 바꾸고 싶다면 settings.json에서 plansDirectory를 설정하면 됩니다.

{
  "plansDirectory": "./plans"
}

상대 경로를 쓰면 워크스페이스 루트 기준으로 잡히고 디렉토리가 없으면 자동으로 만들어줍니다. 프로젝트 디렉토리에 저장하면 Git으로 버전 관리를 하거나 팀원과 공유하기 편하죠.

언제 쓰면 좋을까?

Plan 모드는 작업의 방향이 불확실할 때 가장 유용합니다.

예를 들어 CommonJS에서 ES 모듈로 전환하는 리팩토링을 생각해보세요. 어떤 파일을 먼저 바꿔야 하는지, 순환 참조는 없는지, 테스트는 어떻게 돌려야 하는지 미리 파악해야 하거든요. Plan 모드에서 Claude가 의존성 그래프를 분석하고 마이그레이션 순서를 잡아주면 실행 단계에서 시행착오를 줄일 수 있습니다.

처음 보는 코드베이스에서도 쓸만합니다. “이 프로젝트의 아키텍처를 분석해줘”라고 Plan 모드에서 요청하면 Claude가 코드를 쭉 훑어본 뒤 구조를 정리해주거든요. 코드가 바뀔 걱정 없이 탐색할 수 있어서 온보딩할 때 좋습니다.

“캐싱을 추가하고 싶은데 Redis가 좋을까 인메모리가 좋을까?”처럼 여러 접근 방식 중 골라야 하는 상황에도 잘 맞습니다. Plan 모드에서 각 방안의 장단점을 비교해달라고 하면 코드베이스 맥락을 반영한 구체적인 분석을 받을 수 있어요.

반대로 Plan 모드를 건너뛰어도 되는 경우가 있습니다. 한두 줄 수정하면 되는 간단한 버그 픽스, 기존 패턴을 따르는 테스트 추가, 문서 업데이트 같은 작업은 곧바로 실행하는 게 빠릅니다.

더 깊은 분석이 필요할 때

Plan 모드에서 Claude에게 더 깊이 생각하라고 유도할 수 있습니다. “think hard”, “think harder”, “ultrathink” 같은 키워드를 프롬프트에 넣으면 Claude가 확장 사고(extended thinking)를 활성화해서 더 꼼꼼하게 분석합니다.

plan 모드로 들어가서 이 모듈의 성능 병목을 분석해줘. think harder.

복잡한 아키텍처 결정이나 성능 최적화처럼 깊은 추론이 필요한 작업에서 특히 유용합니다.

실전 팁

Plan 모드를 쓰면서 알게 된 것들을 정리합니다.

계획을 승인하기 전에 수정할 파일 목록을 꼭 확인하세요. Claude가 예상보다 넓은 범위를 건드리려 할 때가 있는데 Plan 모드에서 미리 범위를 좁혀두면 실행 단계에서의 사고를 막을 수 있습니다. “auth 모듈만 건드리고 다른 파일은 수정하지 마”처럼 제약을 걸어도 되고요.

계획이 마음에 들지 않으면 부분적으로 수정할 수 있습니다. “2번 항목은 빼고 나머지를 진행해줘”나 “JWT 대신 세션 기반으로 바꿔서 다시 계획해줘”처럼 요청하면 Claude가 계획을 수정합니다. 처음부터 다시 만드는 것보다 기존 계획을 다듬는 게 효율적이에요.

복잡한 프로젝트에서는 Plan 모드에서 나온 계획을 Tasks로 변환하는 것도 좋은 패턴입니다. “이 계획을 태스크로 나눠줘”라고 하면 의존성까지 잡힌 태스크 리스트가 만들어지고 서브 에이전트에게 병렬로 실행을 맡길 수 있거든요.

마치며

Plan 모드는 “급하면 돌아가라”는 격언을 AI 코딩에 적용한 기능입니다. 곧바로 코드를 쓰기 시작하면 빠른 것 같지만 방향이 틀어졌을 때의 비용이 큽니다. 몇 분의 분석으로 수십 분의 삽질을 아낄 수 있다면 충분히 투자할 가치가 있죠.

특히 처음 접하는 코드베이스에서 작업하거나 여러 접근 방식 중 하나를 골라야 할 때 Plan 모드를 습관적으로 쓰면 작업 품질이 확 달라질 겁니다. Shift+Tab 두 번이면 되니까 한번 시도해보세요.

클로드 코드에 대해 더 알고 싶다면 소개 포스팅을 참고하세요. Plan 모드에서 활용되는 서브 에이전트가 궁금하다면 서브 에이전트 가이드를, 계획을 실행 가능한 태스크로 변환하는 방법은 Tasks 가이드에서 다루고 있습니다. 프로젝트별 환경 설정이 필요하다면 설정 가이드도 살펴보세요.