# Claude Code 프롬프트 워크플로우 공유

> **목적:** 팀 내 Claude Code 사용 방식 공유 및 개선 논의
> **작성일:** 2025-12-23
> **작성자:** hskwon

---

## 📋 현재 사용 중인 워크플로우

### 1. Code-Workflow 스킬 (5단계 강제 프로세스)

코드 수정 시 체계적인 프로세스를 **강제**하는 커스텀 스킬입니다.

```
분석 → 수정 → 검증 → 정리 → 커밋
```

#### 왜 사용하는가?

| 문제 | 해결책 |
|------|--------|
| Claude가 분석 없이 바로 수정 시작 | 1단계에서 **분석 후 승인** 강제 |
| 여러 파일 동시 수정 → 롤백 어려움 | 한 번에 하나씩 순차 수정 |
| 수정 후 검증 생략 | 3단계 검증 필수 |
| 커밋 메시지 대충 작성 | 4단계에서 변경 내용 정리 문서화 |
| 자동 커밋으로 실수 | 5단계에서 **커밋 전 승인** 강제 |

#### 핵심 규칙

```markdown
🔴 필수 규칙 (반드시 준수)

1. 분석 후 승인 필수
   - 분석 결과 + 일정 산정 제시
   - AskUserQuestion으로 승인 요청
   - 승인 없이 수정 진행 금지

2. 커밋 전 승인 필수
   - 변경 내용 요약 제시
   - 승인 없이 커밋 금지
   - 승인 후 → 요약 MD 작성 → 커밋
```

#### 스킬 호출 방법

```bash
/code-workflow   # 또는 Claude가 코드 수정 요청 시 자동 활성화
```

---

### 2. 프로젝트 문서 기반 진행 관리

#### 문서 구조

```
docs/projects/{프로젝트명}/
├── MASTER_PLAN.md      # 마스터 플랜 (전체 로드맵)
├── PROGRESS.md         # 진행 현황 (실시간 업데이트)
├── screenshots/        # 참조 이미지
├── phase-1-xxx/        # Phase별 상세 문서
│   ├── README.md       # Phase 체크리스트 및 요약
│   └── *.md            # 분석/구현 문서
├── phase-2-xxx/
└── phase-3-xxx/
```

#### 핵심 문서 역할

| 문서 | 역할 | 업데이트 주기 |
|------|------|---------------|
| `MASTER_PLAN.md` | 전체 방향, Phase 정의, 핵심 원칙 | 큰 변경 시 |
| `PROGRESS.md` | 현재 진행률, 완료 작업, 다음 작업 | **매 작업 완료 시** |
| `phase-*/README.md` | 각 Phase 체크리스트 | Phase 진행 중 |

#### 실제 사용 예시 (견적 프로젝트)

```markdown
# PROGRESS.md 예시

## 전체 진행률

| Phase | 상태 | 진행률 | 시작일 | 완료일 |
|-------|------|--------|--------|--------|
| Phase 1: 5130 분석 | ✅ 완료 | 100% | 2025-12-19 | 2025-12-19 |
| Phase 2: mng 분석 | ✅ 완료 | 100% | 2025-12-19 | 2025-12-19 |
| Phase 3: 구현 | ✅ 완료 | 100% | 2025-12-19 | 2025-12-19 |
| Phase 4: API 개발 | 🔄 진행 | 60% | 2025-12-19 | - |

## 🔄 현재 작업

**현재 Phase:** Phase 4 진행 중
**완료된 작업:** mng 패턴 적용 - DB 기반 견적 산출 서비스 재작성
**다음 작업:** 견적 API 통합 테스트 및 Swagger 문서화
```

---

### 3. WORKFLOW_STATE.md (작업 중 상태 추적)

코드 수정 중 **중단 후 재개**를 위한 임시 상태 파일입니다.

#### 생성 시점
- code-workflow 2단계(순차 수정) 시작 시 생성
- 5단계(커밋) 완료 후 삭제

#### 내용

```markdown
# Workflow 진행 상태

## 현재 단계: 2단계 (순차 수정)

## 전체 작업 목록
- [x] 1단계: 분석 완료
- [ ] 2단계: 순차 수정 (3/7 완료)
- [ ] 3단계: 검증 대기
- [ ] 4단계: 문서 정리 대기
- [ ] 5단계: 커밋 대기

## 순차 수정 상세 (2단계)
- [x] 수정 1/7: tenants 마이그레이션 생성
- [x] 수정 2/7: folders 마이그레이션 생성
- [x] 수정 3/7: files 마이그레이션 확장
- [ ] 수정 4/7: FileStorageService 구현  ← 현재 진행 중
- [ ] 수정 5/7: Tenant 모델 확장
- [ ] 수정 6/7: File 모델 확장
- [ ] 수정 7/7: Folder 모델 생성
```

#### 재개 시

```
사용자: "어디까지 진행했지?"

Claude: [WORKFLOW_STATE.md 확인]

📋 작업 진행 현황
- 현재 단계: 2단계 (순차 수정)
- 전체 진행률: 43% (3/7 완료)
- 마지막 완료: files 마이그레이션 확장

계속 진행할까요? (y/n)
```

---

### 4. 도구 사용 기록

모든 단계에서 **사용된 도구를 명시적으로 기록**합니다.

#### Footer 형식

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔧 사용된 도구
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📦 MCP 서버
- Sequential Thinking: 복잡한 의존성 분석
- Context7: Laravel Storage 공식 문서 조회

🧠 SuperClaude 페르소나
- backend-architect: 파일 저장 시스템 아키텍처 설계
- security-engineer: 파일 업로드 보안 검토

🛠️ 네이티브 도구
- Read: 5회 (File.php, Tenant.php 등)
- Glob: 3회
- Grep: 2회

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## 💡 이 방식의 장점

### 1. 세션 중단에 강함
- `PROGRESS.md` + `WORKFLOW_STATE.md`로 언제든 이어서 작업 가능
- Claude 컨텍스트가 끊겨도 문서만 읽으면 상태 파악

### 2. 실수 방지
- 분석 → 승인 → 수정 순서 강제
- 커밋 전 승인 강제
- 여러 파일 동시 수정 금지

### 3. 문서화 자동화
- 변경 내용이 자동으로 `docs/changes/` 에 기록
- 나중에 "왜 이렇게 바꿨지?" 추적 가능

### 4. 복잡한 프로젝트 관리
- Phase별 분리로 큰 프로젝트도 관리 가능
- 체크리스트 기반으로 누락 방지

---

## ⚠️ 이 방식의 단점

### 1. 초기 설정 비용
- 스킬 파일, CLAUDE.md 설정 필요
- 프로젝트별 문서 구조 생성 필요

### 2. 간단한 작업에는 과함
- 오타 수정 같은 건 5단계가 불필요
- 예외 처리 규칙 필요 (hotfix 모드 등)

### 3. Claude 의존
- Claude가 규칙을 "잊어버리면" 무용지물
- 가끔 리마인드 필요

---

## 🤔 논의 포인트

### 1. 다른 분들은 어떻게 사용하고 계신가요?

- 프로젝트 문서 구조는?
- 코드 수정 시 어떤 프로세스?
- 세션 중단 후 재개 방법?
- 커밋 관리 방식?

### 2. 개선 아이디어

- 현재 방식에서 불편한 점?
- 더 좋은 문서 구조?
- 더 나은 진행 상태 추적 방법?

### 3. 공통화 가능한 부분

- 팀 공통 CLAUDE.md?
- 공통 스킬 라이브러리?
- 프로젝트 템플릿?

---

## 📁 관련 파일

| 파일 | 설명 |
|------|------|
| `.claude/skills/code-workflow/SKILL.md` | code-workflow 스킬 정의 |
| `CLAUDE.md` | 프로젝트 지시사항 |
| `docs/projects/*/PROGRESS.md` | 프로젝트별 진행 현황 |
| `docs/projects/*/MASTER_PLAN.md` | 프로젝트별 마스터 플랜 |

---

## 📝 스킬 전문 (참고용)

<details>
<summary>code-workflow 스킬 전체 내용 (클릭해서 펼치기)</summary>

```markdown
# 5단계 워크플로우 요약

## 1단계: 분석 (ANALYZE)
- SAM 프로젝트 컨텍스트 로드
- MCP로 관련 파일 검색 및 의존성 분석
- 영향받는 파일 식별
- 예상 부작용/리스크 파악
- **사용자 확인 후 다음 단계로**

## 2단계: 순차 수정 (MODIFY)
- WORKFLOW_STATE.md 생성
- 한 번에 하나씩 수정
- 각 수정 완료 후 상태 업데이트
- 이전 코드 주석 처리 (삭제 금지)

## 3단계: 검증 (VERIFY)
- 문법 오류 확인 (Pint)
- 로직 검증
- 기존 기능 유지 확인
- 보안/성능 체크

## 4단계: 변경 내용 정리 (SUMMARY)
- docs/changes/YYYYMMDD_HHMM_feature_name.md 생성
- CURRENT_WORKS.md 업데이트

## 5단계: Git 커밋 (COMMIT)
- 변경 파일 확인
- 커밋 메시지 제안
- **사용자 확인 후 커밋**
- WORKFLOW_STATE.md 삭제
```

</details>