7.6 KiB
7.6 KiB
Claude Code 프롬프트 워크플로우 공유
목적: 팀 내 Claude Code 사용 방식 공유 및 개선 논의 작성일: 2025-12-23 작성자: hskwon
📋 현재 사용 중인 워크플로우
1. Code-Workflow 스킬 (5단계 강제 프로세스)
코드 수정 시 체계적인 프로세스를 강제하는 커스텀 스킬입니다.
분석 → 수정 → 검증 → 정리 → 커밋
왜 사용하는가?
| 문제 | 해결책 |
|---|---|
| Claude가 분석 없이 바로 수정 시작 | 1단계에서 분석 후 승인 강제 |
| 여러 파일 동시 수정 → 롤백 어려움 | 한 번에 하나씩 순차 수정 |
| 수정 후 검증 생략 | 3단계 검증 필수 |
| 커밋 메시지 대충 작성 | 4단계에서 변경 내용 정리 문서화 |
| 자동 커밋으로 실수 | 5단계에서 커밋 전 승인 강제 |
핵심 규칙
🔴 필수 규칙 (반드시 준수)
1. 분석 후 승인 필수
- 분석 결과 + 일정 산정 제시
- AskUserQuestion으로 승인 요청
- 승인 없이 수정 진행 금지
2. 커밋 전 승인 필수
- 변경 내용 요약 제시
- 승인 없이 커밋 금지
- 승인 후 → 요약 MD 작성 → 커밋
스킬 호출 방법
/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 진행 중 |
실제 사용 예시 (견적 프로젝트)
# 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단계(커밋) 완료 후 삭제
내용
# 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 |
프로젝트별 마스터 플랜 |
📝 스킬 전문 (참고용)
code-workflow 스킬 전체 내용 (클릭해서 펼치기)
# 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 삭제