287 lines
7.6 KiB
Markdown
287 lines
7.6 KiB
Markdown
|
# 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>
|