kent
2d9b02f74e
- INDEX.md: TODO.md 링크 추가 - TODO.md: 프로젝트 할일 목록 신규 생성 - plans/flow-tests/: Flow Tester 테스트 시나리오 JSON 추가 - auth-api-flow.json: 인증 API 플로우 테스트 - pricing-validation-test.json: 가격 검증 테스트 - projects/api-integration/: 마이그레이션 계획 문서 - MASTER_PLAN.md: 전체 마이그레이션 전략 - PROGRESS.md: 진행 상황 추적 - WORKFLOW.md: 작업 워크플로우 - phase-1 ~ phase-4: 단계별 상세 계획 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
260 lines
5.5 KiB
Markdown
260 lines
5.5 KiB
Markdown
# API Integration Workflow
|
|
|
|
> 작업 프로세스 정의 및 간소화 가이드
|
|
|
|
---
|
|
|
|
## 1. 작업 유형별 프로세스
|
|
|
|
### 1.1 단일 작업 (code-workflow 5단계)
|
|
**적용**: 1-2개 파일 수정, 중요 변경
|
|
|
|
```
|
|
분석 → 수정 → 검증 → 정리 → 커밋
|
|
```
|
|
|
|
1. **분석**: 변경 대상 파일 확인, 영향 범위 파악
|
|
2. **수정**: 코드 변경 실행
|
|
3. **검증**: 린트, 타입체크, 테스트
|
|
4. **정리**: 코드 정리, 임시 파일 제거
|
|
5. **커밋**: 변경사항 커밋 (승인 후)
|
|
|
|
### 1.2 배치 작업 (간소화 프로세스)
|
|
**적용**: 여러 파일 유사 수정, 대량 작업
|
|
|
|
```
|
|
배치 분석 → 배치 계획 승인 → 순차 수정 → 전체 검증 → 배치 커밋
|
|
```
|
|
|
|
1. **배치 분석**: 여러 파일 한번에 분석
|
|
2. **배치 계획 승인**: 전체 계획 한번만 승인
|
|
3. **순차 수정**: 개별 파일 수정 (개별 승인 생략)
|
|
4. **전체 검증**: 모든 수정 완료 후 검증
|
|
5. **배치 커밋**: 기능 단위로 커밋
|
|
|
|
### 1.3 반복 작업 (템플릿 프로세스)
|
|
**적용**: 동일 패턴 다수 적용
|
|
|
|
```
|
|
패턴 정의 → 승인 → 일괄 적용 → 검증 → 커밋
|
|
```
|
|
|
|
1. **패턴 정의**: 변경 패턴 정의 (예: API URL 교체)
|
|
2. **승인**: 패턴 적용 승인
|
|
3. **일괄 적용**: 모든 대상에 패턴 적용
|
|
4. **검증**: 결과 확인
|
|
5. **커밋**: 변경사항 커밋
|
|
|
|
---
|
|
|
|
## 2. 승인 필요 지점
|
|
|
|
### 반드시 승인 필요
|
|
| 작업 | 승인 시점 |
|
|
|------|----------|
|
|
| 파일 생성/삭제 | 작업 전 |
|
|
| API 엔드포인트 수정 | 계획 단계 |
|
|
| 테이블 구조 변경 | 계획 단계 |
|
|
| 커밋 | 커밋 직전 |
|
|
|
|
### 승인 생략 가능
|
|
| 작업 | 조건 |
|
|
|------|------|
|
|
| 배치 수정 내 개별 파일 | 배치 계획 승인 후 |
|
|
| 문서 업데이트 | PROGRESS.md, 로그 등 |
|
|
| 린트/포맷팅 | 자동 수정 |
|
|
|
|
---
|
|
|
|
## 3. 세션 라이프사이클
|
|
|
|
### 세션 시작
|
|
```bash
|
|
# 1. Serena 메모리 확인
|
|
serena.list_memories()
|
|
serena.read_memory("api-integration-state")
|
|
|
|
# 2. PROGRESS.md 확인
|
|
# 3. "다음 액션"부터 재개
|
|
```
|
|
|
|
### 작업 중
|
|
```bash
|
|
# 마일스톤마다 업데이트
|
|
- PROGRESS.md 체크리스트 업데이트
|
|
- 중요 결정사항 기록
|
|
- serena.write_memory() (선택)
|
|
```
|
|
|
|
### 세션 종료 전
|
|
```bash
|
|
# 1. PROGRESS.md 최종 업데이트
|
|
# 2. Serena 메모리 저장
|
|
serena.write_memory("api-integration-state", {
|
|
current_phase: "phase-3",
|
|
current_task: "매핑 매트릭스 작성",
|
|
next_action: "거래처 API 매핑",
|
|
last_updated: "2025-12-20 15:30"
|
|
})
|
|
|
|
# 3. /clear 또는 세션 종료
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 연동 작업 상세 프로세스
|
|
|
|
### 4.1 API 매핑 작업
|
|
```
|
|
1. React 페이지 확인
|
|
└── 어떤 데이터가 필요한지 파악
|
|
|
|
2. API 엔드포인트 검색
|
|
└── 기존 API 중 맞는 것 찾기
|
|
|
|
3. 매핑 결정
|
|
├── 완벽 일치 → 바로 연동
|
|
├── 부분 일치 → API 수정 필요
|
|
└── 없음 → 신규 개발 필요
|
|
|
|
4. 문서화
|
|
└── mapping-matrix.md 업데이트
|
|
```
|
|
|
|
### 4.2 연동 작업
|
|
```
|
|
1. React 코드 확인
|
|
└── API 호출 위치, 데이터 구조
|
|
|
|
2. API 응답 확인
|
|
└── Swagger 또는 실제 호출
|
|
|
|
3. 불일치 해결
|
|
├── React 수정 (API 구조가 맞는 경우)
|
|
└── API 수정 (React 요구사항 우선)
|
|
|
|
4. 테스트
|
|
└── 화면에서 동작 확인
|
|
|
|
5. 로깅
|
|
└── integration-log.md 업데이트
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 이슈 처리 프로세스
|
|
|
|
### 이슈 발견 시
|
|
```
|
|
1. 이슈 문서 생성
|
|
└── phase-4-integration/issues/ISSUE-XXX.md
|
|
|
|
2. 이슈 분류
|
|
├── 🔴 Critical: 기능 작동 불가
|
|
├── 🟡 Major: 기능 일부 제한
|
|
└── 🟢 Minor: 개선 사항
|
|
|
|
3. 해결 및 기록
|
|
└── 해결 방법, 변경 파일 기록
|
|
```
|
|
|
|
### 이슈 문서 템플릿
|
|
```markdown
|
|
# ISSUE-XXX: [이슈 제목]
|
|
|
|
## 상태: 🔴 Open / 🟢 Resolved
|
|
|
|
## 설명
|
|
[이슈 상세 설명]
|
|
|
|
## 재현 방법
|
|
1. ...
|
|
2. ...
|
|
|
|
## 원인
|
|
[원인 분석]
|
|
|
|
## 해결 방법
|
|
[해결 방법]
|
|
|
|
## 변경 파일
|
|
- [ ] file1.ts
|
|
- [ ] file2.php
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 커밋 메시지 규칙
|
|
|
|
### 형식
|
|
```
|
|
[프로젝트] 타입: 제목
|
|
|
|
본문 (선택)
|
|
|
|
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
|
|
|
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
|
```
|
|
|
|
### 타입
|
|
| 타입 | 설명 |
|
|
|------|------|
|
|
| feat | 새 기능 |
|
|
| fix | 버그 수정 |
|
|
| refactor | 리팩토링 |
|
|
| docs | 문서 |
|
|
| chore | 기타 |
|
|
|
|
### 예시
|
|
```
|
|
[API] feat: items API 응답에 category 정보 추가
|
|
|
|
- ItemService에서 category eager loading
|
|
- ItemResource에 category 필드 추가
|
|
|
|
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
|
|
|
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 도구 활용
|
|
|
|
### MCP 서버
|
|
| 서버 | 용도 |
|
|
|------|------|
|
|
| Sequential Thinking | 복잡한 분석, 설계 |
|
|
| Serena | 메모리, 심볼 검색 |
|
|
| Context7 | 공식 문서 참조 |
|
|
|
|
### SuperClaude 페르소나
|
|
| 페르소나 | 용도 |
|
|
|----------|------|
|
|
| backend-architect | API 설계, 구현 |
|
|
| frontend-architect | React 구조 |
|
|
| quality-engineer | 테스트, 검증 |
|
|
|
|
---
|
|
|
|
## 8. 체크리스트
|
|
|
|
### 작업 시작 전
|
|
- [ ] PROGRESS.md 확인
|
|
- [ ] 현재 Phase 파악
|
|
- [ ] 다음 액션 확인
|
|
|
|
### 작업 중
|
|
- [ ] 체크리스트 업데이트
|
|
- [ ] 이슈 발생 시 문서화
|
|
- [ ] 변경사항 로깅
|
|
|
|
### 작업 완료 후
|
|
- [ ] PROGRESS.md 업데이트
|
|
- [ ] Serena 메모리 저장
|
|
- [ ] 커밋 (승인 후)
|
|
|
|
---
|
|
|
|
*이 문서는 작업 효율성을 위해 필요 시 업데이트됩니다.* |