Plan Mode: 코드 작성 전에 1분만 더 쓰는 시간

빠른 구현이 항상 빠른 결과는 아니다

Cursor Agent의 장점은 빠르다는 것이다. 요청을 쓰면 파일을 찾고, 코드를 고치고, 테스트까지 실행한다. 문제는 그 속도 때문에 잘못된 방향으로도 빠르게 간다는 점이다.

'설정 화면에 팀 초대 기능 추가해 줘'라고만 말하면 Agent는 나름대로 추측한다. 어떤 사용자가 초대할 수 있는지, 이미 초대된 이메일은 어떻게 처리하는지, 무료 플랜에서도 가능한지, 초대 메일은 실제로 보내야 하는지, 테스트는 어디에 추가해야 하는지 빈칸을 채운다. 운이 좋으면 그럴듯한 코드가 나온다. 운이 나쁘면 세 파일만 고치면 될 일을 열 파일로 넓히고, 기존 권한 모델과 다른 새 로직을 만든다.

Plan Mode는 이 문제를 줄이기 위한 장치다. 코드를 쓰기 전에 한 번 멈추고, Agent에게 먼저 코드베이스를 읽고 구현 계획을 만들게 한다. 이 1분은 속도를 늦추는 시간이 아니다. 나중에 되돌릴 시간을 줄이는 시간이다.

Plan Mode의 핵심은 간단하다. 실행 전 계약서를 만드는 것이다. 무엇을 바꿀지, 무엇은 바꾸지 않을지, 어떤 파일을 건드릴지, 어떤 테스트로 확인할지 먼저 합의한다. 합의가 끝난 뒤에야 Agent에게 구현을 맡긴다.

AI 생성 이미지

Shift+Tab으로 '읽기 전용 전략가'를 만든다

Agent 입력창에서 Shift+Tab으로 Plan Mode를 켠다. 이때 중요한 것은 모드를 켜는 것보다 첫 지시문이다. Agent에게 지금의 역할이 '구현자'가 아니라 '읽기 전용 전략가'라는 점을 분명히 알려야 한다.

다음 프롬프트를 기본형으로 사용할 수 있다.

Plan Mode로 진행해 줘.
너는 지금 구현자가 아니라 읽기 전용 전략가야.
아직 코드를 수정하지 말고, 상태를 바꾸는 터미널 명령도 실행하지 마.

목표:
- [만들거나 고칠 기능을 한 문장으로 설명]

먼저 할 일:
1. 관련 파일과 기존 구현 패턴을 찾아줘.
2. 데이터 흐름, 타입, API, 테스트 위치를 확인해 줘.
3. 영향 범위와 위험한 변경 지점을 정리해 줘.
4. 요구사항이 불명확하면 추측하지 말고 최대 3개의 확인 질문을 해줘.
5. 그다음 Markdown 형식의 구현 계획을 작성해 줘.

플랜에는 반드시 다음을 포함해 줘:
- Context Summary
- 변경할 파일과 변경하지 않을 파일
- 단계별 구현 순서
- 리스크와 대응 방법
- 테스트 및 검증 방법
- 내가 승인해야 할 결정 사항

이 프롬프트의 목적은 Agent의 기본 습관을 바꾸는 것이다. 보통 Agent는 '요청을 받으면 해결한다'고 생각한다. Plan Mode에서는 '요청을 받으면 먼저 확인한다'로 바꿔야 한다. 특히 코드 수정 금지, 상태 변경 명령 금지, 추측 금지를 명시해야 한다.

읽기 전용이라고 해서 아무것도 하지 말라는 뜻은 아니다. 파일을 읽고, 검색하고, 기존 패턴을 비교하고, 테스트 구조를 확인하라는 뜻이다. 단, 패키지를 설치하거나 마이그레이션을 실행하거나 파일을 고치는 일은 아직 하지 않는다.

계획 전에 먼저 탐색하게 하라

좋은 플랜은 좋은 탐색에서 나온다. 코드베이스를 제대로 보지 않은 플랜은 겉으로는 정돈되어 보여도 실제 구현 단계에서 자주 무너진다.

Agent에게 바로 '계획 써 줘'라고 하지 말고, 다음 순서로 탐색하게 한다.

첫째, 요구사항을 다시 말하게 한다. Agent가 이해한 목표가 내 의도와 같은지 확인해야 한다. 예를 들어 '팀 초대 기능'이 초대 링크 생성인지, 이메일 초대인지, 조직 멤버 권한 관리인지 먼저 구분해야 한다.

둘째, 관련 파일을 찾게 한다. 페이지 컴포넌트, API 라우트, 서버 액션, 데이터 모델, 권한 체크, 테스트 파일을 함께 보게 한다. 구현 파일 하나만 보면 주변 제약을 놓친다.

셋째, 기존 패턴을 찾게 한다. 이미 비슷한 기능이 있다면 새로 만들지 않는 편이 낫다. 예를 들어 '프로젝트 초대' 기능이 있다면 '팀 초대'도 같은 이메일 검증, 토스트 메시지, 권한 체크, 테스트 방식을 따라야 한다.

넷째, 의존성과 영향 범위를 확인하게 한다. 여기서 영향 범위, 즉 blast radius는 한 변경이 어디까지 흔들 수 있는지를 뜻한다. 데이터 모델 변경은 API, UI, 테스트, 배포, 운영 데이터까지 영향을 줄 수 있다. 반면 버튼 문구 수정은 영향 범위가 작다.

다섯째, 불확실한 점을 질문으로 돌려받게 한다. 좋은 Agent는 모르는 것을 그럴듯하게 채우지 않는다. '초대 메일은 실제 발송까지 구현하나요, 아니면 초대 레코드 생성까지만 하나요?' 같은 질문은 귀찮은 방해가 아니라 사고를 막는 안전장치다.

Cursor 작업 모드 관점에서도 이 흐름은 자연스럽다. 작은 변경은 바로 Agent로 진행할 수 있지만, 여러 파일을 건드리는 기능이나 리팩터링은 먼저 탐색과 계획을 거치는 편이 안전하다.¹

Markdown 플랜은 작업 계약서다

Plan Mode의 결과물은 예쁜 문서가 아니라 실행 가능한 작업 계약서여야 한다. 계약서가 모호하면 구현도 모호해진다.

좋은 플랜에는 최소한 다음 항목이 들어간다.

## Context Summary
- 확인한 파일:
- 확인한 기존 패턴:
- 현재 데이터 흐름:
- 관련 타입/API/테스트:
- 아직 불확실한 점:

## Goal
- 이번 작업의 목표:

## Non-goals
- 이번 작업에서 하지 않을 것:

## Files to Change
- `path/to/file.ts`: 바꿀 내용과 이유

## Files to Read Only
- `path/to/important.ts`: 참고만 하고 수정하지 않을 이유

## Implementation Steps
1. ...
2. ...
3. ...

## Risks
- 위험:
- 대응:

## Verification
- 실행할 테스트:
- 타입체크:
- 수동 확인 시나리오:

## Approval Needed
- 사용자가 결정해야 할 사항:

특히 Context Summary는 중요하다. Agent가 어떤 파일을 읽었고, 무엇을 근거로 계획을 세웠는지 드러나야 한다. 그래야 사용자가 '이 파일도 봐야 한다', '그 패턴은 오래된 방식이다', '이 테스트는 지금 신뢰할 수 없다'처럼 수정할 수 있다.

플랜을 검토할 때는 다음 질문을 던진다.

• 파일 경로가 구체적인가?

• '로직 수정' 같은 모호한 표현이 실제 함수나 컴포넌트 단위로 내려왔는가?

• 변경하지 말아야 할 영역이 적혀 있는가?

• 새 의존성을 추가하려는 이유가 충분한가?

• 테스트가 '나중에 확인'이 아니라 구체적인 명령과 시나리오로 적혀 있는가?

• 실패했을 때 되돌릴 수 있는 단위로 나뉘어 있는가?

이 중 하나라도 비어 있으면 바로 구현하지 않는다. 플랜을 고친 뒤 진행한다. Plan Mode에서의 수정은 싸다. 구현 후 되돌리기는 비싸다.

승인한 플랜은 저장하고 재사용한다

좋은 플랜은 한 번 쓰고 버릴 자료가 아니다. 중간에 작업을 멈췄다가 다시 시작할 때, 또는 다른 Agent 실행에 넘길 때 가장 좋은 컨텍스트가 된다.

실전에서는 다음처럼 저장해 둔다.

.cursor/plans/2026-05-22-team-invite.md

플랜 파일에는 작성 날짜, 목표, 승인된 범위, 남은 TODO를 함께 적는다. 구현을 시작할 때는 Agent에게 이렇게 지시한다.

@.cursor/plans/2026-05-22-team-invite.md 를 기준으로 진행해.
먼저 1단계만 구현하고 멈춰.
완료 후 변경 파일, 테스트 결과, 플랜과 달라진 점을 요약해 줘.

중요한 점은 '한 번 승인한 플랜을 절대 바꾸지 않는다'가 아니다. 구현 중 새 사실을 발견하면 플랜을 갱신해야 한다. 예를 들어 기존 권한 체크 함수가 예상과 다르거나, 테스트 유틸이 오래되어 사용할 수 없다면 Agent에게 멈추게 하고 플랜을 수정하게 한다.

이 과정을 생략하면 컨텍스트 드리프트가 생긴다. 컨텍스트 드리프트는 처음 목표와 현재 작업이 조금씩 어긋나는 현상이다. 처음에는 '팀 초대 버튼 추가'였는데 어느새 '권한 시스템 리팩터링'이 되어 있는 식이다. 플랜을 갱신하면 작업이 어디서 왜 바뀌었는지 기록으로 남는다.

Plan Mode를 설계할 때는 '탐색 → 요약 → 계획 → 필요 시 재탐색 → 실행 인계'의 흐름을 유지하는 것이 좋다. 계획 전에 근거를 먼저 문서화하고, 빈칸이 남으면 짧은 확인 질문으로 되돌리는 방식은 복잡한 작업에서 특히 효과적이다.²

언제 바로 맡기고, 언제 계획할까

모든 작업에 Plan Mode를 쓰면 오히려 느려진다. 기준은 변경의 크기와 되돌리기 비용이다.

바로 Agent나 Cmd+K에 맡겨도 되는 작업은 다음과 같다.

• 단일 파일 안의 작은 문구 수정

• 명확한 타입 오류 하나 수정

• 테스트 이름 변경

• 이미 위치를 아는 작은 조건문 추가

• 스타일 클래스 한두 개 조정

반대로 Plan Mode를 먼저 거쳐야 하는 작업은 다음과 같다.

• 3~10개 파일에 걸친 새 기능

• 데이터 모델, 권한, 결제, 인증이 관련된 변경

• 기존 구조를 바꾸는 리팩터링

• 테스트를 대량으로 생성하거나 재구성하는 작업

• 어디를 고쳐야 할지 아직 모르는 버그

• 여러 접근 방식이 가능해 선택이 필요한 작업

판단이 애매하면 이렇게 생각하면 된다.

'실패했을 때 git diff를 보고 5분 안에 되돌릴 수 있는가?'

그렇다면 바로 진행해도 된다. 아니라면 Plan Mode를 켠다.

Plan Mode 이후의 구현 지시

플랜을 승인했다면 이제 Agent에게 구현을 맡긴다. 단, 전체 플랜을 한 번에 던지지 않는 것이 좋다. 첫 단계만 실행하게 하고, 결과를 확인한 뒤 다음 단계로 넘어간다.

승인한 플랜에 따라 1단계만 구현해 줘.
범위를 벗어난 파일은 수정하지 마.
새 의존성은 추가하지 마.
완료 후 다음을 보고해 줘:
- 변경한 파일
- 플랜과 달라진 점
- 실행한 테스트와 결과
- 다음 단계로 넘어가기 전에 확인할 사항

이 방식은 Agent를 믿지 못해서가 아니다. 작은 단위로 맡겨야 Agent가 더 잘 일한다. 사람도 한 번에 많은 요구를 받으면 중요한 제약을 놓친다. Agent도 마찬가지다.

Plan Mode는 Cursor를 '코드 자동 생성기'에서 '작업 시스템'으로 바꾸는 습관이다. PRD가 무엇을 만들지 정하는 문서라면, Plan Mode는 어떻게 만들지 합의하는 문서다. 이 둘 사이가 연결될 때 Agent는 단순히 빠른 손이 아니라 예측 가능한 협업자가 된다.

코드를 쓰기 전에 1분만 더 쓴다. 그 1분이 오늘의 롤백을 줄이고, 내일의 유지보수를 쉽게 만든다.

참고

¹Agent Modes Deep Dive

²gather-plan cursor custom mode