plan

name	plan
description	새 기능 구현, 리팩토링, 개선, 버그 수정 작업을 시작하기 전에 계획서 파일을 생성한다. "기능 구현 계획해줘", "A 기능 계획 세워줘", "B 리팩토링 계획", "개선 계획 작성해줘", "#127 계획서 만들어줘"처럼 코딩 전 계획이 필요한 요청이 오면 반드시 이 스킬을 먼저 실행해라. 코드 작성 전 단계에서 사용한다.

사용자가 요청한 작업에 대한 계획서를 .claude/plans/ 폴더에 생성한다. 계획서는 작업 유형에 따라 다른 구조로 작성되며, 사용자가 컨텍스트를 입력한 뒤 구현을 시작하기 위한 문서다.

절차

1. 작업 파악 및 컨텍스트 수집

이슈 번호가 있는 경우 ($ARGUMENTS에 #숫자 패턴 포함):

• gh issue view <번호> 로 이슈 제목, 본문, 레이블을 읽는다
• 이슈 내용을 계획서 개요와 체크리스트에 반영한다
• 레이블(bug, enhancement, refactor 등)로 작업 유형을 파악한다

이슈 번호가 없는 경우:

• $ARGUMENTS 또는 직전 대화에서 작업 내용을 파악한다
• 불명확하면 한 문장으로 확인 질문 후 대기한다

CLAUDE.md를 읽어 아키텍처, 모듈 구조, 네이밍 컨벤션을 파악한다.

2. 작업 유형 판별

아래 중 하나로 분류한다. 이슈 레이블, 요청 키워드, 작업 내용을 종합해서 판단한다:

유형	키워드 예시	특징
feature	기능 추가, 신규, 개발, implement	UI/리소스/API 섹션 포함
improvement	개선, 최적화, UX 향상, 성능	현재 상태 vs 목표 비교
refactor	리팩토링, 구조 변경, 정리, 분리	변경 전후 구조 명시
bug	버그, 오류, 크래시, 안 됨, 수정	재현 단계, 원인 분석 포함
fix	핫픽스, 긴급, 빠른 수정	간소화된 구조, 빠른 실행

불명확하면 사용자에게 유형을 한 번만 확인한다.

3. .claude/plans/ 디렉토리 준비

• .claude/plans/ 폴더가 없으면 생성한다
• .gitignore에 .claude/plans/ 항목이 없으면 추가한다 (계획서는 Git에 포함되지 않음)

4. 계획서 생성

파일명: .claude/plans/[기능명-kebab-case].md
예: .claude/plans/home-refresh.md, .claude/plans/fix-crash-on-launch.md

체크리스트는 커밋 단위로 묶는다. 각 Commit N 블록은 독립적으로 빌드 가능한 범위여야 한다. 내용은 빈 템플릿이 아니라 프로젝트 구조와 요청 내용 기반으로 채워서 작성하고, 사용자 입력이 필요한 부분만 빈칸으로 남긴다.

---

유형별 계획서 구조

feature (기능 개발)

# [기능명] 구현 계획
> 작성일 / 상태: 🟡 계획 중 / 이슈: #번호 (있는 경우)

## 개요
**목적:** / **영향 범위:**

## 🎨 UI / 리소스
**디자인 시안:** (피그마 링크 또는 이미지 경로)
**필요한 아이콘 / 이미지:**
**새로운 컬러 / 타이포 토큰:**

## 📝 컨텍스트 (직접 입력)
**API 스펙 / 엔드포인트:** / **관련 이슈:** / **추가 전달 내용:**

## 📋 구현 체크리스트
### Commit 1: [단위]
- [ ] ...
### Commit 2: [단위]
- [ ] ...

## ⚠️ 유의사항
## 🤔 추가 검토 항목
## ✅ 완료 기준

improvement (개선)

# [기능명] 개선 계획
> 작성일 / 상태: 🟡 계획 중 / 이슈: #번호 (있는 경우)

## 개요
**목적:** / **영향 범위:**

## 현재 상태 vs 개선 목표
**현재:** [현재 동작/구조의 문제점]
**목표:** [개선 후 기대 결과]

## 📝 컨텍스트 (직접 입력)
**참고 자료 / 링크:** / **관련 이슈:** / **추가 전달 내용:**

## 📋 구현 체크리스트
### Commit 1: [단위]
- [ ] ...

## ⚠️ 유의사항
## 🤔 추가 검토 항목
## ✅ 완료 기준

refactor (리팩토링)

# [대상] 리팩토링 계획
> 작성일 / 상태: 🟡 계획 중 / 이슈: #번호 (있는 경우)

## 개요
**목적:** / **영향 범위:**

## 구조 변경
**변경 전:** [현재 구조 요약]
**변경 후:** [목표 구조 요약]

## 📝 컨텍스트 (직접 입력)
**관련 이슈:** / **추가 전달 내용:**

## 📋 구현 체크리스트
### Commit 1: [단위]
- [ ] ...

## ⚠️ 유의사항 (기존 동작 보존 필수 항목 포함)
## 🤔 추가 검토 항목
## ✅ 완료 기준 (기능 동작 변화 없음 포함)

bug (버그 수정)

# [버그 설명] 수정 계획
> 작성일 / 상태: 🟡 계획 중 / 이슈: #번호 (있는 경우)

## 버그 개요
**증상:** [사용자가 경험하는 문제]
**영향 범위:** [어떤 화면/기능에 영향]

## 재현 단계 (직접 입력)
1.
2.
3.

## 원인 분석
[코드 분석을 통해 파악한 원인. 아직 모르면 "조사 필요"로 표시]

## 📝 컨텍스트 (직접 입력)
**발생 환경 (OS, 앱 버전 등):** / **관련 이슈:** / **추가 전달 내용:**

## 📋 수정 체크리스트
### Commit 1: [단위]
- [ ] ...

## ⚠️ 유의사항 (사이드이펙트 주의 항목)
## ✅ 완료 기준

fix (핫픽스)

# [수정 내용] 핫픽스
> 작성일 / 상태: 🟡 계획 중 / 이슈: #번호 (있는 경우)

## 문제 요약
**증상:** / **원인:** / **영향 범위:**

## 📝 컨텍스트 (직접 입력)
**관련 이슈:** / **추가 전달 내용:**

## 📋 수정 체크리스트
### Commit 1: [단위]
- [ ] ...

## ✅ 완료 기준

---

5. 계획서 생성 완료 후 안내

.claude/plans/[파일명].md 계획서를 작성했어요. 📝 컨텍스트 및 🎨 UI / 리소스 (feature 유형) 섹션을 채워주세요. 모르는 항목은 비워둬도 괜찮아요. 입력이 끝나면 "계획서 작성 완료" 또는 "구현 시작해줘" 라고 알려주세요.

6. 구현 모드 선택 (사용자 입력 완료 후)

계획서를 다시 읽어 전체 컨텍스트를 파악한 뒤, 구현 전에 모드를 선택받는다:

구현 방식을 선택해주세요: A. 연속 구현 — 커밋 단위별로 멈추지 않고 끝까지 구현 B. 단계별 구현 — 각 커밋 완료 후 확인받고 다음으로 진행

7. 커밋 단위별 구현

각 Commit N 그룹을 순서대로 구현하며, 완료 시마다 반드시 아래 순서를 따른다:

1. 컴파일 확인 — ./gradlew compileDebugKotlin 실행. 에러 있으면 수정 후 재시도. 기능 검증은 하지 않는다. 코드가 빌드되면 충분하다.

2. 계획서 업데이트 — 완료된 항목을 - [x]로 체크.

3. 커밋

   git add <변경 파일>
   git commit -m "[TYPE] 커밋 메시지
   
   Co-Authored-By: Claude Code <[e-mail]>"
   

4. 모드별 분기

   • A (연속): 즉시 다음 커밋으로 진행
   • B (단계별): 완료 내용 보고 후 "다음 단계로 진행할까요?" 확인 후 대기

모든 커밋 완료 시 계획서 상태를 🟢 완료로 업데이트하고 최종 커밋한다.