# `/plan` 커스텀 스킬 vs 내장 PlanMode 비교 가이드

> Claude Code에는 두 가지 "계획" 기능이 있습니다. 이 문서는 두 가지의 차이를 명확히 설명하고, 상황별 선택 가이드를 제공합니다.

## TL;DR

**내장 PlanMode는 "운전 모드 전환 (D→P)"**이고, **`/plan`은 "내비게이션이 경로를 짜주는 것"**입니다.
하나는 상태 전환이고, 다른 하나는 산출물 생성입니다.

---

## 개요

| 구분 | 내장 PlanMode (`EnterPlanMode`) | `/plan` 커스텀 스킬 |
|------|------|------|
| **정체** | Claude Code의 **시스템 레벨 상태 전환** | `planner` 에이전트를 호출하는 **커스텀 명령어** |
| **누가 계획하나** | **메인 Claude** 자체가 탐색 + 계획 | **별도 서브에이전트(planner)** 가 계획 |
| **산출물** | `.claude/plans/xxx.md` 파일에 계획 작성 | 대화 내 마크다운으로 계획 출력 |
| **도구 제한** | 읽기 전용 (Read, Grep, Glob만 가능, **Edit/Write 차단**) | 서브에이전트가 Read, Grep, Glob 사용 |
| **승인 흐름** | `ExitPlanMode` → 사용자 승인 → 구현 시작 | 에이전트가 "WAITING FOR CONFIRMATION" 출력 → 사용자 응답 → 구현 |
| **컨텍스트** | 메인 컨텍스트 **그대로 사용** (계획 후 즉시 구현 가능) | 서브에이전트의 **별도 컨텍스트** (결과만 반환) |
| **권한 관리** | `allowedPrompts`로 구현 단계 권한 사전 설정 가능 | 없음 |

---

## 작동 메커니즘

### 내장 PlanMode

```
사용자 요청 → EnterPlanMode 호출 → [상태 전환]
→ Claude가 코드베이스 탐색 (Read/Grep/Glob만 허용)
→ .claude/plans/xxx.md에 계획 작성
→ ExitPlanMode 호출 → 사용자 승인 대기
→ 승인 → 코드 작성 시작 (Edit/Write 사용 가능)
```

**핵심 특징:**
- Claude 자체가 "계획 모드"에 진입합니다
- Write/Edit 도구가 **시스템 레벨에서 차단**되어 실수로 코드를 작성할 수 없습니다
- 계획 파일이 `~/.claude/plans/`에 영구 저장됩니다
- `ExitPlanMode`에서 `allowedPrompts`를 지정하면 구현 시 필요한 Bash 권한을 미리 설정할 수 있습니다

### `/plan` 커스텀 스킬

```
/plan [요청] → planner 에이전트 생성 (서브에이전트)
→ 에이전트가 코드베이스 탐색 + 요구사항 인터뷰
→ 구조화된 계획서 출력 (마크다운)
→ "계획 확정?" → 사용자 확인
→ 메인 Claude가 계획을 받아 구현
```

**핵심 특징:**
- `planner.md`에 정의된 전문 에이전트가 별도 컨텍스트에서 실행됩니다
- Investigation Protocol이 내장되어 있어서 의도 분류 → 탐색 → 인터뷰(한 번에 한 질문) → 계획 생성의 **체계적 워크플로우**를 따릅니다
- Self-Evolution 프로토콜로 패턴을 `~/.claude/agent-memory/planner/`에 학습합니다

---

## 상황별 선택 가이드

| 상황 | 추천 | 이유 |
|------|------|------|
| 아키텍처 변경, 다중 파일 수정 | **내장 PlanMode** | Write/Edit 차단으로 실수 방지 + 계획 파일 영구 보존 |
| 복잡한 기능 구현, 요구사항이 불명확 | **`/plan`** | 인터뷰 프로토콜로 요구사항을 체계적으로 수집 |
| 빠르게 방향 확인만 | **내장 PlanMode** | 서브에이전트 오버헤드 없이 즉시 계획 |
| 팀 워크플로우 (`/tdd`, `/auto`와 연계) | **`/plan`** | 계획 후 `/tdd`나 `/auto`로 자연스럽게 이어짐 |
| 컨텍스트 절약이 중요할 때 | **`/plan`** | 서브에이전트가 별도 윈도우 사용, 메인 컨텍스트 보존 |
| 계획을 나중에 다시 참조 | **내장 PlanMode** | `.claude/plans/`에 파일로 자동 저장 |

---

## 장단점 정리

### 내장 PlanMode

| 장점 | 단점 |
|------|------|
| 시스템 레벨 안전장치 (도구 차단) | 메인 컨텍스트 소비 |
| 계획 파일 영구 보존 | 인터뷰 프로토콜 없음 |
| 권한 사전 설정 (`allowedPrompts`) | 계획 품질이 프롬프트에 의존 |
| 오버헤드 없음 (즉시 시작) | - |

### `/plan` (planner 에이전트)

| 장점 | 단점 |
|------|------|
| 전문화된 계획 에이전트 (Investigation Protocol) | 서브에이전트 호출 비용 (토큰) |
| 메인 컨텍스트 보존 | 계획이 대화 내에서만 존재 (파일 미저장) |
| 자동 학습 (Self-Evolution) | 시스템 레벨 도구 차단 없음 |
| 다른 스킬과 연계 (`/tdd`, `/auto`) | - |

---

## 함께 사용하기

두 가지는 **보완적**입니다. 내장 PlanMode가 "안전한 사고 공간"을 제공한다면, `/plan`은 "전문 기획자를 고용하는 것"입니다.

### 추천 워크플로우

**간단한 경우:**
```
내장 PlanMode → 빠른 계획 → 승인 → 구현
```

**복잡한 경우:**
```
/plan → 체계적 인터뷰 → 구조화된 계획서 → /tdd → 구현 → /code-review
```

**최대 안전 모드:**
```
/plan → 계획서 확정 → 내장 PlanMode에서 계획 검증 → 구현
```

---

## 참고

- 내장 PlanMode: Claude Code에 기본 포함 (별도 설치 불필요)
- `/plan` 스킬: Claude Forge의 `commands/plan.md` + `agents/planner.md`로 구성
- HARD-GATE 규칙: 3파일 이상 변경 시 어떤 방식이든 **계획 먼저** (Golden Principles 참조)
