# /plan - 계획 수립 (Shovel v2 + 7 Theories)

> **적용된 이론**
> 1. **Tree of Thoughts**: 여러 구현 경로 탐색
> 2. **Self-Consistency**: 다중 계획 투표
> 3. **Chain of Verification**: 계획 검증
> 4. **LLM-as-Judge**: 계획 품질 평가
> 5. **ReAct**: 계획-검증-수정 루프
> 6. **Reflexion**: 이전 실패에서 학습
> 7. **DeepSeek-R1**: Self-Reflection

> **핵심 원칙**
> - **PRD가 법이다** - PRD에 없으면 BACKLOG로
> - **PLAN.md가 계약이다** - 승인 후 변경 불가
> - **범위는 잠긴다** - 중간 추가 = BACKLOG
> - **룰 안에서 자유** - 방법은 자유, 범위는 엄격

---

## 사용법

```bash
# 자동 모드 (AI가 계획 생성)
/plan 로그인 기능 구현

# 커스텀 모드 (상세 인터뷰)
/plan --custom 로그인 기능

# 확장 모드 (기존 계획에 추가)
/plan --extend 소셜 로그인 추가
```

---

## 모드 선택

```
/plan [태스크]
    │
    ├── 🤖 자동 모드 (기본)
    │   └── AI가 7가지 이론으로 최적 계획 생성
    │
    ├── 💬 커스텀 모드 (--custom)
    │   └── 상세 인터뷰 → 사용자와 함께 계획 수립
    │
    └── ➕ 확장 모드 (--extend)
        └── 기존 PLAN.md에 추가 (범위 검증 후)
```

---

# 🤖 자동 모드 (7 Theories)

## 전체 플로우

```
/plan [태스크]
    │
    ├── Phase 1: PRD 확인 (SSOT)
    │
    ├── Phase 2: Tree of Thoughts
    │   └── 3가지 구현 경로 탐색
    │
    ├── Phase 3: Self-Consistency
    │   └── 각 경로 평가 → 투표
    │
    ├── Phase 4: 계획 생성 (ReAct)
    │   └── Thought → Plan → Verify 루프
    │
    ├── Phase 5: Chain of Verification
    │   └── 4단계 계획 검증
    │
    ├── Phase 6: LLM-as-Judge
    │   └── 계획 품질 평가
    │
    └── Phase 7: 저장 + 잠금
        └── PLAN.md 생성, 범위 잠금
```

---

## Phase 1: PRD 확인 (SSOT 강제)

```bash
# PRD 존재 확인
test -f docs/PRD.md || test -f PRD.md

# 태스크 키워드 검색
grep -i "{태스크}" docs/PRD.md
```

### PRD에 없으면 → 즉시 BACKLOG

```markdown
## 🚫 SSOT 위반

**"{태스크}"**는 PRD.md에 없습니다.

**PRD가 법입니다.**

### 자동 조치
→ `docs/BACKLOG.md`에 추가됨

```markdown
### [2026-01-10] {태스크}
- 요청자: 사용자
- 상태: 대기 (PRD 반영 필요)
- 우선순위: 미정
```

### 다음 단계
1. PRD.md에 기능 추가
2. `/plan {태스크}` 다시 실행

**현재 계획은 중단됩니다.**
```

---

## Phase 2: Tree of Thoughts - 구현 경로 탐색

```
┌─────────────────────────────────────────────────────┐
│         Tree of Thoughts: 구현 경로                  │
└─────────────────────────────────────────────────────┘

                 [태스크: 인증 구현]
                        │
         ┌──────────────┼──────────────┐
         ↓              ↓              ↓
    [경로 A]       [경로 B]       [경로 C]
   NextAuth.js    Custom JWT    Supabase Auth
         │              │              │
    ┌────┴────┐    ┌───┴───┐    ┌────┴────┐
    ↓         ↓    ↓       ↓    ↓         ↓
 [장점]    [단점]  ...     ...  ...      ...
 빠른구현  제한적
    │
   점수: 85
```

### ToT 평가 기준

| 기준 | 가중치 | 설명 |
|------|--------|------|
| PRD 적합성 | 30% | PRD 요구사항 충족도 |
| 기존 스택 호환 | 25% | 현재 기술 스택과의 호환 |
| 구현 복잡도 | 20% | 낮을수록 좋음 |
| 유지보수성 | 15% | 장기적 관리 용이성 |
| 시간 효율 | 10% | 구현 예상 시간 |

### ToT 결과

```markdown
## 🌳 구현 경로 분석

| 경로 | 점수 | 장점 | 단점 |
|------|------|------|------|
| A: NextAuth.js | 85 | 빠른 구현, 검증됨 | Provider 제한 |
| B: Custom JWT | 70 | 완전한 제어 | 시간 소요 |
| C: Supabase | 60 | 쉬움 | 벤더 종속 |

**ToT 선택**: 경로 A (NextAuth.js)
```

---

## Phase 3: Self-Consistency - 다중 관점 투표

```
┌─────────────────────────────────────────────────────┐
│       Self-Consistency: 3가지 관점 투표              │
└─────────────────────────────────────────────────────┘

관점 1: 기술적 최적
  → NextAuth.js (검증된 솔루션)

관점 2: 비즈니스 요구사항
  → NextAuth.js (PRD 요구사항 충족)

관점 3: 시간/리소스
  → NextAuth.js (가장 빠른 구현)

투표: NextAuth.js (3/3) ✅
```

---

## Phase 4: 계획 생성 (ReAct 루프)

```
[Thought 1]
NextAuth.js로 인증 구현. 먼저 설치가 필요함.

[Plan 1]
Step 1: NextAuth 설치 및 설정

[Verify 1]
✅ package.json에 추가 가능
✅ 기존 구조와 충돌 없음

[Thought 2]
Provider 설정 필요. PRD에 Google, GitHub 명시됨.

[Plan 2]
Step 2: OAuth Provider 설정

[Verify 2]
✅ PRD 요구사항 일치
⚠️ 환경변수 설정 필요 → Step에 포함

[Thought 3]
세션 관리와 미들웨어 필요.

[Plan 3]
Step 3: 세션 및 미들웨어

[Verify 3]
✅ app/api/auth 경로 가능
```

---

## Phase 5: Chain of Verification - 계획 검증

```
┌─────────────────────────────────────────────────────┐
│      Chain of Verification: 계획 검증                │
└─────────────────────────────────────────────────────┘

Step 1: 계획 초안
────────────────────
"5단계로 NextAuth.js 인증 구현"

Step 2: 검증 질문 생성
────────────────────
Q1: 모든 Step이 PRD 요구사항을 충족하는가?
Q2: Step 간 의존성이 올바른가?
Q3: 각 Step에 검증 방법이 있는가?
Q4: 예상 시간이 현실적인가?
Q5: 누락된 작업이 있는가?

Step 3: 독립 검증 (초안 안 보고)
────────────────────
A1: ✅ PRD의 "소셜 로그인" 요구사항 충족
A2: ✅ 설치 → 설정 → 구현 → 테스트 순서 적절
A3: ✅ 모든 Step에 `pnpm` 명령어로 검증
A4: ⚠️ Step 3 예상 시간 조정 필요 (30min → 45min)
A5: ✅ 누락 없음

Step 4: 계획 수정
────────────────────
- Step 3 시간 조정: 30min → 45min
```

---

## Phase 6: LLM-as-Judge - 계획 품질 평가

```markdown
## ⚖️ 계획 품질 평가

### 평가 항목

| 항목 | 점수 | 기준 |
|------|------|------|
| PRD 적합성 | 95% | 요구사항 충족 |
| Step 분해 | 90% | 30분 이내 단위 |
| 검증 방법 | 100% | 모든 Step 검증 가능 |
| 의존성 순서 | 95% | 올바른 순서 |
| 위험 식별 | 85% | 환경변수 의존성 식별 |

### 종합 점수: 93%

### 판정: ✅ PASS

| 점수 | 판정 |
|------|------|
| 90%+ | ✅ PASS - 실행 가능 |
| 70-89% | ⚠️ REVIEW - 수정 권장 |
| <70% | ❌ RETRY - 재계획 필요 |
```

---

## Phase 7: 저장 + 범위 잠금 🔒

### 계획 저장

```bash
# PLAN.md 생성
cat > docs/PLAN.md << 'EOF'
# 현재 계획

## 메타데이터
- 생성: 2026-01-10T12:00:00Z
- 태스크: {태스크명}
- 상태: 🔒 LOCKED
- ToT 점수: 85
- Judge 점수: 93%

## 범위 정의 (변경 불가)
{PRD에서 추출한 범위}

## Step 목록
{생성된 Step들}

## 범위 잠금 해시
SHA256: {계획 내용 해시}
EOF
```

### 🔒 범위 잠금 규칙

```markdown
## 🔒 범위 잠금 활성화

이 계획은 **잠겼습니다**.

### 잠금 규칙

1. **Step 내용 수정**: ✅ 가능 (방법은 자유)
2. **Step 순서 변경**: ⚠️ 의존성 확인 후 가능
3. **Step 추가**: 🚫 BACKLOG로
4. **범위 확장**: 🚫 새 /plan 필요
5. **기능 추가 요청**: 🚫 자동 BACKLOG

### 중간에 추가 요청이 오면

```
사용자: "여기에 이메일 인증도 추가해줘"

Claude: 🚫 범위 잠금 위반

"이메일 인증"은 현재 PLAN.md 범위에 없습니다.

자동 조치:
→ BACKLOG.md에 추가됨

현재 계획을 먼저 완료하세요.
완료 후 `/plan 이메일 인증` 실행 가능.
```

### 룰 안에서의 자유

| 자유 | 제한 |
|------|------|
| ✅ 구현 방식 선택 | 🚫 범위 확장 |
| ✅ 코드 스타일 | 🚫 기능 추가 |
| ✅ 리팩토링 | 🚫 스펙 변경 |
| ✅ Step 내 세부 조정 | 🚫 Step 추가 |
```

---

# 💬 커스텀 모드 (상세 인터뷰)

## 사용법

```bash
/plan --custom 인증 기능
```

## 인터뷰 플로우

```
/plan --custom [태스크]
    │
    ├── Q1: 기본 정보 (필수)
    ├── Q2: 기술 선택 (모르면 추천)
    ├── Q3: 세부 요구사항 (모르면 기본값)
    ├── Q4: 제약 조건 (있으면)
    ├── Q5: 우선순위 (선택)
    │
    ├── 중간 검증 (CoVe)
    │
    ├── Q6-N: 추가 질문 (필요시)
    │
    └── 최종 계획 생성 + 확인
```

---

## 인터뷰 시작

```markdown
## 💬 커스텀 플랜 모드

**태스크**: {입력된 태스크}

상세한 계획을 함께 만들어봅시다.
모르는 것은 **"모름"**이라고 하면 제가 추천해드릴게요.

---

### Q1. 이 기능의 핵심 목표는 무엇인가요?

예시:
- "사용자가 소셜 계정으로 로그인할 수 있게"
- "관리자만 특정 페이지 접근 가능하게"

> 답변: ___
```

---

## Q2: 기술 선택 (모르면 추천)

```markdown
### Q2. 어떤 기술/방식으로 구현하고 싶으세요?

**현재 프로젝트 스택**: Next.js 15, TypeScript, Prisma

**선택지**:
| 옵션 | 설명 | 추천도 |
|------|------|--------|
| (a) NextAuth.js | 검증된 인증 라이브러리 | ⭐⭐⭐ |
| (b) Custom JWT | 직접 구현 | ⭐⭐ |
| (c) Supabase Auth | 백엔드 서비스 | ⭐ |
| (?) 모름 | 제가 추천해드릴게요 | - |

> 선택: ___
```

### 모름 선택 시

```markdown
### 🤖 기술 추천

프로젝트 분석 결과:
- Next.js 15 App Router 사용 중
- 이미 Prisma로 DB 연결됨
- PRD에 "소셜 로그인" 명시

**추천: NextAuth.js**

이유:
1. Next.js와 완벽 통합
2. Prisma Adapter 지원
3. 소셜 로그인 쉽게 구현
4. 세션 관리 자동화

이걸로 진행할까요?
> **(y)** 네, NextAuth.js로
> **(n)** 아니요, 다른 걸로
> **(?)** 더 자세히 설명해주세요
```

---

## Q3: 세부 요구사항 (모르면 기본값)

```markdown
### Q3. 세부 요구사항을 알려주세요.

**3-1. 로그인 Provider는?**
| 옵션 | 선택 |
|------|------|
| Google | [ ] |
| GitHub | [ ] |
| Email/Password | [ ] |
| 카카오 | [ ] |
| 네이버 | [ ] |
| (?) 모름 | [ ] |

**3-2. 세션 유지 기간은?**
| 옵션 | 설명 |
|------|------|
| (a) 1일 | 보안 중요 |
| (b) 7일 | 일반적 (기본값) |
| (c) 30일 | 편의성 중요 |
| (?) 모름 | 기본값 적용 |

**3-3. 권한 관리 필요한가요?**
| 옵션 | 설명 |
|------|------|
| (a) 단순 | 로그인/비로그인만 |
| (b) 역할 기반 | admin, user 등 |
| (c) 복잡 | 세밀한 권한 |
| (?) 모름 | 나중에 결정 |
```

### 모름 선택 시

```markdown
### 🤖 기본값 적용

**3-1. Provider**: Google, GitHub (가장 보편적)
**3-2. 세션**: 7일 (보안/편의 균형)
**3-3. 권한**: 단순 (필요시 확장 가능)

이 기본값으로 진행할까요?
> **(y)** 네
> **(n)** 수정하고 싶어요
```

---

## Q4: 제약 조건

```markdown
### Q4. 특별한 제약 조건이 있나요?

예시:
- "기존 users 테이블 사용해야 함"
- "특정 라이브러리는 피해야 함"
- "마감 기한: 3일 내"

> 답변 (없으면 "없음"): ___
```

---

## Q5: 우선순위

```markdown
### Q5. 이 기능의 우선순위는?

| 우선순위 | 의미 |
|----------|------|
| (1) 크리티컬 | 이거 없으면 출시 불가 |
| (2) 높음 | 핵심 기능 |
| (3) 보통 | 있으면 좋음 |
| (4) 낮음 | 나중에 해도 됨 |

> 선택: ___
```

---

## 중간 검증 (CoVe)

```markdown
## 🔍 중간 검증

지금까지 정리된 내용:

| 항목 | 값 |
|------|-----|
| 태스크 | 인증 기능 |
| 기술 | NextAuth.js |
| Provider | Google, GitHub |
| 세션 | 7일 |
| 권한 | 단순 |
| 제약 | 없음 |
| 우선순위 | 높음 |

### 검증 질문

Q1: PRD에 이 기능이 있나요?
→ ✅ "소셜 로그인" 섹션 확인

Q2: 기존 스택과 호환되나요?
→ ✅ Next.js + NextAuth 호환

Q3: 누락된 정보가 있나요?
→ ⚠️ 콜백 URL 설정 필요

### 추가 질문 필요

```
Q6. OAuth 콜백 URL을 알고 있나요?
(예: https://myapp.com/api/auth/callback/google)

> **(y)** 네, 알아요
> **(n)** 모름 (기본값 사용)
> **(?)** 이게 뭔가요?
```
```

---

## "이게 뭔가요?" 응답

```markdown
### 📚 콜백 URL 설명

**OAuth 콜백 URL**이란?

사용자가 Google/GitHub 로그인 후 돌아올 주소입니다.

```
1. 사용자 → "Google로 로그인" 클릭
2. Google 로그인 페이지로 이동
3. 로그인 성공
4. **콜백 URL**로 돌아옴 ← 여기!
5. 우리 앱에서 세션 생성
```

**기본값**: `/api/auth/callback/[provider]`
- Google: `/api/auth/callback/google`
- GitHub: `/api/auth/callback/github`

NextAuth.js가 자동으로 처리하므로 기본값 사용 권장.

> **(y)** 이해했어요, 기본값 사용
> **(?)** 더 자세히
```

---

## 최종 계획 생성

```markdown
## 📋 최종 계획

### 인터뷰 요약

| 항목 | 값 |
|------|-----|
| 태스크 | 인증 기능 |
| 기술 | NextAuth.js |
| Provider | Google, GitHub |
| 세션 | 7일 |
| 권한 | 단순 (로그인/비로그인) |
| 콜백 | 기본값 사용 |

### 생성된 Step

#### Step 1: NextAuth.js 설치 (15min)
- `pnpm add next-auth @auth/prisma-adapter`
- 검증: `pnpm list next-auth`

#### Step 2: 환경변수 설정 (10min)
- `.env.local`에 OAuth 키 추가
- 검증: 환경변수 존재 확인

#### Step 3: NextAuth 설정 파일 (30min)
- `app/api/auth/[...nextauth]/route.ts` 생성
- Provider 설정
- 검증: `pnpm typecheck`

#### Step 4: Prisma Adapter 연결 (20min)
- `prisma/schema.prisma` 수정
- `pnpm prisma db push`
- 검증: DB 테이블 확인

#### Step 5: 세션 Provider 추가 (15min)
- `app/providers.tsx` 생성
- 검증: `pnpm lint`

#### Step 6: 테스트 (30min)
- 로그인 플로우 테스트
- 검증: `pnpm test`

#### Step 7: Gate 검증 (5min)
- 검증: `pnpm gate`

### 총 예상 시간: 2시간 5분

---

### 확인

이 계획으로 진행할까요?

> **(y)** 승인 → PLAN.md 저장 + 잠금
> **(n)** 수정 → 어떤 부분?
> **(r)** 처음부터 다시
```

---

## 수정 요청 시

```markdown
### 수정 모드

어떤 부분을 수정할까요?

> **(1)** 기술 변경 (NextAuth → 다른 것)
> **(2)** Step 수정 (내용/시간)
> **(3)** 요구사항 추가
> **(4)** 요구사항 삭제

선택: ___

---

⚠️ **주의**: 요구사항 추가는 PRD 확인이 필요합니다.
PRD에 없는 기능은 BACKLOG로 이동됩니다.
```

---

# ➕ 확장 모드 (기존 계획에 추가)

## 사용법

```bash
/plan --extend 소셜 로그인에 카카오 추가
```

## 확장 검증

```markdown
## ➕ 확장 모드

**현재 PLAN.md**: 인증 기능 (NextAuth.js)
**확장 요청**: 카카오 Provider 추가

### 범위 검증

Q1: 현재 PLAN 범위 내인가?
→ 분석 중...

**현재 범위**: 
- Google OAuth ✅
- GitHub OAuth ✅
- 세션 관리 ✅

**요청 범위**:
- 카카오 OAuth ← 새로운 것

### 판정

⚠️ **범위 확장 감지**

카카오 OAuth는 현재 PLAN.md에 없습니다.

### 옵션

> **(b)** BACKLOG에 추가 (권장)
>     → 현재 계획 완료 후 진행
>
> **(p)** PRD에 있다면 새 PLAN 생성
>     → PRD 확인 후 별도 /plan 실행
>
> **(f)** 강제 확장 (비권장)
>     → SSOT 위반 경고 표시됨

선택: ___
```

---

# 🚨 범위 침범 감지

## 작업 중 추가 요청 감지

```markdown
## 🚨 범위 침범 감지

**현재 작업**: Step 3 (NextAuth 설정)
**감지된 요청**: "여기에 비밀번호 찾기도 추가해줘"

### 분석

| 항목 | 현재 PLAN | 요청 |
|------|-----------|------|
| 인증 방식 | OAuth만 | + 비밀번호 |
| 비밀번호 찾기 | ❌ 없음 | 추가 요청 |

### 판정: 🚫 범위 밖

**"비밀번호 찾기"**는 현재 계획에 없습니다.

### 자동 조치

```markdown
# BACKLOG.md에 추가됨

### [2026-01-10] 비밀번호 찾기 기능
- 요청 시점: Step 3 진행 중
- 상태: 대기
- 선행 조건: 현재 PLAN 완료
- PRD 반영: 필요
```

### 현재 작업 계속

Step 3 (NextAuth 설정)을 계속 진행합니다.

**팁**: 현재 계획 완료 후:
1. PRD에 "비밀번호 찾기" 추가
2. `/plan 비밀번호 찾기` 실행
```

---

# 📊 범위 추적 대시보드

## 현재 상태

```markdown
## 📊 계획 상태

### PLAN.md
```
상태: 🔒 LOCKED
진행: Step 3/7 (43%)
범위: 고정됨
```

### 범위 변경 이력

| 시점 | 요청 | 조치 |
|------|------|------|
| Step 2 | "이메일 인증 추가" | → BACKLOG |
| Step 3 | "비밀번호 찾기" | → BACKLOG |

### BACKLOG.md 대기열

| 순서 | 기능 | PRD 상태 |
|------|------|----------|
| 1 | 이메일 인증 | 미반영 |
| 2 | 비밀번호 찾기 | 미반영 |

### 경고

⚠️ 2개의 기능이 BACKLOG에서 PRD 반영을 기다리고 있습니다.
현재 PLAN 완료 후 PRD 업데이트를 권장합니다.
```

---

# 요약: 룰과 자유

## 🔒 잠긴 것 (변경 불가)

| 항목 | 상태 |
|------|------|
| 범위 (Scope) | 🔒 |
| PRD 요구사항 | 🔒 |
| Step 수 | 🔒 |
| 기능 목록 | 🔒 |

## 🔓 자유로운 것

| 항목 | 상태 |
|------|------|
| 구현 방식 | ✅ 자유 |
| 코드 스타일 | ✅ 자유 |
| 파일 구조 | ✅ 자유 |
| Step 내 세부 작업 | ✅ 자유 |
| 리팩토링 | ✅ 자유 |
| 변수명, 함수명 | ✅ 자유 |

## 핵심 원칙

```
"범위는 감옥, 방법은 자유"

PLAN.md가 정한 범위 안에서는
어떻게 구현하든 자유입니다.

하지만 범위를 넘으면
즉시 BACKLOG로 갑니다.
```
