Claude Code Plan Mode 완벽 활용 가이드

일반 모드          Plan Mode
   ↓                 ↓
요청 → 즉시 실행    요청 → 계획 수립 → 승인 → 실행

예: 클래스 기반 컴포넌트를 함수형으로 전환
   → 여러 파일, 의존성 관리 필요

예: 인증 시스템 구축
   → 백엔드 API, 프론트엔드 UI, 상태 관리, 라우팅 등 다단계 작업

예: JavaScript → TypeScript 전환
   → 타입 정의, 설정 파일, 의존성 업데이트 등

예: Monolith → Microservices
   → 서비스 분리, API 설계, 배포 전략 등

예: 여러 모듈에 걸친 상태 동기화 이슈
   → 원인 분석 → 영향 범위 파악 → 단계적 수정

/plan

"먼저 계획을 세워줘"
"단계별로 어떻게 진행할지 알려줘"
"실행 계획을 먼저 보고 싶어"

"React 프로젝트에 다크모드를 추가해줘"

## 실행 계획

### 1단계: 현재 프로젝트 구조 분석

- 컴포넌트 파일 위치 확인
- 스타일링 방식 파악 (CSS/Styled-components/Tailwind)
- 상태 관리 라이브러리 확인

### 2단계: 테마 시스템 설계

- Context API로 테마 상태 관리
- 테마 타입 정의 (light/dark)
- LocalStorage에 사용자 선택 저장

### 3단계: 구현

- ThemeContext 생성
- ThemeProvider 컴포넌트 작성
- 다크모드 토글 버튼 추가
- CSS 변수로 색상 테마 정의

### 4단계: 기존 컴포넌트 업데이트

- App.js에 ThemeProvider 적용
- 주요 컴포넌트에 테마 적용
- 스타일 일관성 확인

### 5단계: 테스트

- 토글 동작 확인
- LocalStorage 저장/로드 확인
- 브라우저 호환성 테스트

"좋아, 이대로 진행해"
"계획대로 실행해줘"

"2단계에서 Redux를 사용하고 싶어"
"4단계를 먼저 하고 3단계를 나중에 해줘"
"1단계는 건너뛰고 바로 구현해줘"

Express 프로젝트를 NestJS로 마이그레이션해줘

## NestJS 마이그레이션 계획

### Phase 1: 분석 및 준비

1. 기존 Express 라우터 구조 분석
2. 미들웨어 목록 파악
3. 의존성 확인

### Phase 2: NestJS 프로젝트 설정

1. NestJS CLI 설치
2. 새 프로젝트 생성
3. 필요한 모듈 설치

### Phase 3: 코드 마이그레이션

1. 라우터 → 컨트롤러 변환
2. 미들웨어 → 가드/인터셉터 변환
3. 비즈니스 로직 → 서비스 분리

### Phase 4: 테스트 및 검증

1. 기존 테스트 케이스 실행
2. API 엔드포인트 검증
3. 성능 비교

### Phase 5: 배포 준비

1. 환경 변수 설정
2. Docker 설정 업데이트
3. CI/CD 파이프라인 수정

// Phase 3-1: Express 라우터를 NestJS 컨트롤러로 변환

// Before (Express)
app.get('/users/:id', async (req, res) => {
  const user = await getUserById(req.params.id);
  res.json(user);
});

// After (NestJS)
@Controller('users')
export class UsersController {
  @Get(':id')
  async getUser(@Param('id') id: string) {
    return this.usersService.getUserById(id);
  }
}

Dashboard.jsx가 너무 커서 유지보수가 힘들어.
기능별로 작은 컴포넌트로 분리해줘.

## 컴포넌트 리팩토링 계획

### 1단계: 현재 구조 분석

- Dashboard.jsx 코드 읽기 (1200 lines)
- 주요 기능 영역 식별:
  - 헤더 영역 (로고, 네비게이션, 프로필)
  - 사이드바 (메뉴, 필터)
  - 메인 콘텐츠 (차트, 테이블, 통계)
  - 모달/팝업

### 2단계: 컴포넌트 구조 설계

### 3단계: 상태 관리 재구성
- Props drilling 제거
- Context API 도입 (DashboardContext)
- 공유 상태 정의

### 4단계: 단계별 분리
1. Header 분리 및 테스트
2. Sidebar 분리 및 테스트
3. Content 영역 분리
4. Modal 분리

### 5단계: 통합 및 검증
- 분리된 컴포넌트 통합
- 기능 동작 확인
- 스타일 일관성 점검

// Before: Dashboard.jsx (1200 lines)
function Dashboard() {
  // 엄청나게 긴 코드...
  return (
    <div>
      {/* 헤더 */}
      {/* 사이드바 */}
      {/* 메인 콘텐츠 */}
      {/* 모달 */}
    </div>
  );
}

// After: Dashboard.jsx (50 lines)
function Dashboard() {
  return (
    <DashboardProvider>
      <DashboardHeader />
      <DashboardLayout>
        <DashboardSidebar />
        <DashboardContent />
      </DashboardLayout>
      <DashboardModals />
    </DashboardProvider>
  );
}

프로젝트 전체에 API 에러 처리가 중구난방이야.
통일된 에러 처리 시스템을 만들어줘.

## API 에러 처리 표준화 계획

### 1단계: 현재 상태 파악

- 모든 API 호출 위치 검색
- 에러 처리 패턴 분류
- 문제점 도출

### 2단계: 에러 처리 설계

- 에러 타입 정의 (Network, Auth, Validation, Server)
- 에러 코드 매핑
- 사용자 친화적 메시지 정의

### 3단계: 공통 모듈 구현

```typescript
// errorHandler.ts
// apiClient.ts (axios interceptor)
// ErrorBoundary.tsx
// useApiError.ts (custom hook)
```

**승인 후 실행:**

```typescript
// Before: 각 컴포넌트에서 제각각
async function fetchUser() {
  try {
    const response = await axios.get('/api/user');
    return response.data;
  } catch (error) {
    alert('에러 발생!'); // 😱
  }
}

// After: 표준화된 에러 처리
import { useApiError } from '@/hooks/useApiError';

function UserProfile() {
  const { handleError } = useApiError();

  async function fetchUser() {
    try {
      return await apiClient.get('/api/user');
    } catch (error) {
      handleError(error); // 자동으로 적절한 UI 표시
    }
  }
}

// apiClient.ts - 인터셉터로 중앙 집중식 처리
apiClient.interceptors.response.use(
  response => response,
  error => {
    if (error.response?.status === 401) {
      // 자동 로그아웃 및 리다이렉트
    } else if (error.response?.status === 500) {
      // 서버 에러 로깅 및 사용자 알림
    }
    return Promise.reject(error);
  }
);

"각 단계가 끝날 때마다 내가 확인하고 싶어"

### 2단계: ThemeContext 생성

- [ ] ThemeContext.js 작성
- [ ] 기본 테마 설정
      **→ 검증 포인트: 사용자 확인 필요**

### 3단계: UI 컴포넌트 작성

...

"각 단계마다 롤백 방법도 같이 알려줘"

### Phase 3: 데이터베이스 마이그레이션

**실행:**

- 새 스키마 적용
- 데이터 마이그레이션 스크립트 실행

**롤백 방법:**

```sql
-- migration_rollback.sql
DROP TABLE new_users;
ALTER TABLE users_backup RENAME TO users;
```

### 3. 병렬 작업 계획

**독립적인 작업을 병렬로 처리:**

**결과:**
```markdown
### Phase 2: 병렬 작업
**Task A (병렬):** 백엔드 API 개발
**Task B (병렬):** 프론트엔드 UI 개발
**Task C (병렬):** 테스트 케이스 작성

→ 모든 작업 완료 후 Phase 3로 진행

"가장 중요한 것부터 순서대로 해줘"

### 우선순위 P0 (긴급): 보안 취약점 수정

### 우선순위 P1 (중요): 성능 최적화

### 우선순위 P2 (개선): 코드 리팩토링

### 우선순위 P3 (선택): 문서 업데이트

→ 즉시 Login.jsx 파일 생성
→ 코드 작성 시작
→ 뭔가 빠진 것 같은데...?
→ "아, API도 필요하고 라우팅도 추가해야겠네"
→ 추가 작업...

→ 계획 수립:
  1. 현재 인증 방식 확인
  2. 로그인 UI 컴포넌트
  3. 인증 API 엔드포인트
  4. 상태 관리 (Context/Redux)
  5. 라우팅 설정
  6. 세션 관리
→ 사용자 승인
→ 체계적으로 실행

❌ 나쁜 예:
### 1단계: 파일 열기
### 2단계: 1번째 줄 수정
### 3단계: 2번째 줄 수정
...

✅ 좋은 예:
### 1단계: 컴포넌트 리팩토링
- Props 인터페이스 정의
- 렌더링 로직 분리
- 스타일 최적화

"2단계는 건너뛰고 3단계로 넘어가줘"
"지금 하는 방식 말고 다른 방법으로 해줘"

"다음 형식으로 계획을 세워줘:
1. 분석
2. 설계
3. 구현
4. 테스트
5. 배포"

"각 단계별 예상 시간도 알려줘"

→ 결과:
### 1단계: 프로젝트 분석 (~5분)
### 2단계: 설계 (~10분)
### 3단계: 구현 (~30분)

"단계 간 의존 관계를 그림으로 보여줘"

→ 결과:
```mermaid
graph TD
  A[1단계: 분석] --> B[2단계: 설계]
  B --> C[3단계: 백엔드]
  B --> D[3단계: 프론트엔드]
  C --> E[4단계: 통합]
  D --> E

**Tip 4: 진행 상황 추적**

**Tip 5: 계획과 실제 차이 리포트**

---

## 실전 워크플로우

### 완벽한 Plan Mode 활용 프로세스

```bash
# 1. Plan Mode 활성화
/plan

# 2. 작업 요청
"Next.js 12에서 14로 마이그레이션해줘"

# 3. 계획 검토 및 커스터마이징
"App Router 마이그레이션도 포함해줘"
"데이터 페칭 방식도 최신 패턴으로 변경해줘"

# 4. 계획 승인
"좋아, 시작해"

# 5. 단계별 모니터링
# Claude Code가 자동으로 진행하며 각 단계 완료 보고

# 6. 중간 점검
"현재 진행 상황 알려줘"

# 7. 최종 검증
"모든 단계가 완료됐는지 확인해줘"
"테스트 결과 보여줘"

# 8. Plan Mode 종료
/exit-plan  # 또는 자연어로 "plan mode 종료"

간단한 작업 (파일 하나 수정)
  → 일반 모드 ⚡

복잡한 작업 (여러 파일, 다단계)
  → Plan Mode 📋✨