---
description: "기능 개발 단계별 가이드 - 요구사항 분석, 아키텍처 설계, 코드 구현, 검증"
alwaysApply: true
---
# 기능 개발 가이드 프롬프트 템플릿
이 템플릿은 새로운 기능을 개발할 때 따라야 할 단계별 가이드를 제공합니다.
## 개발 전 준비 단계
### 1. 요구사항 분석
- [ ] 기능 요구사항이 명확히 정의되었는가?
- [ ] 비즈니스 로직이 명확한가?
- [ ] UI/UX 요구사항이 정의되었는가?
- [ ] API 스펙이 정의되었는가?
### 2. 영향도 분석
- [ ] 기존 기능에 영향을 주는가?
- [ ] 다른 feature와의 연관성이 있는가?
- [ ] 전역 상태 변경이 필요한가?
- [ ] 데이터베이스 스키마 변경이 필요한가?
### 3. 아키텍처 설계
- [ ] Feature-based 구조에 맞게 설계되었는가?
- [ ] MVVM 패턴을 준수하는가?
- [ ] 디렉토리 구조가 적절한가?
```
src/features/[feature-name]/
├── api/ # API 호출
├── hooks/ # ViewModel (비즈니스 로직)
├── components/ # Feature 전용 컴포넌트
├── store.ts # Feature 전용 Zustand store
└── types.ts # Feature 타입 정의
```
## 개발 단계
### 1. 사이드이펙트 점검
**절대 사이드이펙트가 발생해서는 안되며 다른 개발에 영향이 있어서도 안됩니다.**
- [ ] 기존 코드와의 충돌 가능성 확인
- [ ] 전역 상태 변경 영향도 확인
- [ ] API 호출 패턴 변경 영향도 확인
- [ ] 캐시 정책 변경 영향도 확인
### 2. MCP 및 Context7 활용
- [ ] MCP 도구를 활용하여 개발
- [ ] Context7을 이용해서 공식문서에서 제공하는 방식으로 구현
- [ ] Sequential thinking을 통해 단계적 의사코드를 작성하고 개선
### 3. 코드 구현
#### TypeScript 타입 정의
- [ ] 필요한 타입을 `src/features/[feature]/types.ts`에 정의
- [ ] 공용 타입은 `src/types/index.ts`에 정의
- [ ] `any` 타입 사용 최소화
#### API 서비스 구현
- [ ] `src/features/[feature]/api/`에 API 호출 함수 구현
- Query/Mutation 함수 정의
- Query Key 규칙 준수: `['domain','resource',params]`
- [ ] `src/services/[feature]APIService.ts`에 서비스 함수 추가
- HTTP 호출만 담당 (비즈니스 로직 없음)
- 에러 처리 및 로깅 구현
- [ ] 로깅 규칙 준수
- 성공: `console.log('✅ [API명] API 호출 성공: [URL] → [데이터개수]개 데이터 로드')`
- 실패: `console.error('❌ [API명] API 호출 실패 → [에러메시지]')`
#### ViewModel (Hooks) 구현
- [ ] `src/features/[feature]/hooks/`에 ViewModel 구현
- 파일명: `use[Feature]ViewModel.ts` 또는 `use[Feature]Screen.ts`
- [ ] TanStack Query를 사용한 서버 상태 관리
- Query Key 규칙 준수: `['domain','resource',params]`
- useQuery, useMutation 적절히 활용
- [ ] Zustand를 사용한 로컬 UI 상태 관리
- Feature별 store: `src/features/[feature]/store.ts`
- 전역 store는 `src/stores/`에만 배치
- [ ] 비즈니스 로직은 ViewModel에만 포함
- Screen 컴포넌트는 ViewModel만 구독
- 서비스 함수 직접 호출 금지
#### 컴포넌트 구현
- [ ] `src/features/[feature]/components/`에 Feature 전용 컴포넌트
- [ ] 공용 컴포넌트는 `src/components/`에 배치
- [ ] Screen 컴포넌트는 ViewModel 하나만 구독
- [ ] 서비스 함수를 직접 호출하지 않음
#### 스타일링
- [ ] StyleSheet.create() 사용
- [ ] 일관된 색상과 스페이싱 활용
- [ ] 반응형 디자인 고려
### 4. 데이터 관리
#### API 데이터 처리 (CRITICAL)
- [ ] **절대 하드코딩된 데이터 배열/객체 사용 금지**
- [ ] **기본 데이터, 예시 데이터, 더미 데이터 사용 금지**
- [ ] **모든 서버 데이터는 API를 통해서만 처리**
- [ ] API 서버 연결 실패 시 에러 상태 유지
- [ ] 사용자에게 서버 연결 상태 명확히 표시
#### 로컬 저장소
- [ ] AsyncStorage는 사용자 데이터만 저장
- [ ] 서버 데이터는 API에서만 가져오기
- [ ] StorageService 클래스 활용
### 5. 에러 처리 및 로깅
#### 에러 처리
- [ ] try-catch 블록으로 모든 비동기 작업 감싸기
- [ ] 사용자 친화적인 에러 메시지
- [ ] ERROR_MESSAGES 상수 활용
#### 로깅 규칙
- 성공: `console.log('✅ [기능명] 성공 → [결과정보]')`
- 실패: `console.error('❌ [기능명] 실패 → [에러정보]')`
- 경고: `console.warn('⚠️ [기능명] 경고 → [경고정보]')`
- 정보: `console.info('ℹ️ [기능명] 정보 → [상세정보]')`
## 개발 후 검증 단계
### 1. 코드 리뷰
- [ ] `@.cursor/rules/code-review-template.mdc` 참고하여 자체 리뷰
- [ ] 사이드이펙트 재확인
- [ ] 타입 안전성 확인
- [ ] 아키텍처 패턴 준수 확인
### 2. 테스트
- [ ] 주요 기능 동작 확인
- [ ] 에러 케이스 테스트
- [ ] 엣지 케이스 테스트
- [ ] 성능 테스트 (필요시)
### 3. QA 체크리스트
- [ ] 인증 상태 동기화 확인 (필요시)
- [ ] Screen이 ViewModel 하나만 구독하는지 확인
- [ ] 이미지/음성 캐시 정책 확인 (필요시)
- [ ] Query Key 규칙 일관성 확인
## 개발 우선순위
### 높음 (High Priority)
1. 사이드이펙트 제거
2. 타입 안전성 보장
3. API 데이터 처리 규칙 준수
4. 아키텍처 패턴 준수
### 중간 (Medium Priority)
5. 코드 스타일 일관성
6. 에러 처리 완성도
7. 성능 최적화
8. 주석 및 문서화
### 낮음 (Low Priority)
9. 테스트 코드 추가
10. 추가 최적화
11. 코드 리팩토링
## 개발 워크플로우
```
[요구사항 분석]
↓
[영향도 분석]
↓
[아키텍처 설계]
↓
[사이드이펙트 점검]
↓
[코드 구현]
├── 타입 정의
├── API 서비스
├── ViewModel
├── 컴포넌트
└── 스타일링
↓
[데이터 관리 구현]
↓
[에러 처리 및 로깅]
↓
[코드 리뷰]
↓
[테스트]
↓
[QA 검증]
↓
[완료]
```
## 주의사항
### 절대 금지 사항
- ❌ 하드코딩된 서버 데이터 사용
- ❌ 기본 데이터, 예시 데이터, 더미 데이터 사용
- ❌ 사이드이펙트 발생
- ❌ Screen에서 서비스 함수 직접 호출
- ❌ `any` 타입 남용
### 필수 준수 사항
- ✅ MVVM 패턴 준수
- ✅ Feature-based 구조 준수
- ✅ TypeScript 타입 안전성
- ✅ API 전용 데이터 처리
- ✅ 에러 처리 및 로깅
## 도구 활용
### MCP 도구
- Context7: 공식 문서 기반 검증
- Sequential thinking: 단계적 의사코드 작성
### 개발 도구
- React Native Debugger: 디버깅
- `yarn debugger:check`: 연결 진단
- `rndebugger://set-debugger-loc?host=localhost&port=8081`
- Reactotron: 로깅 및 상태 모니터링
- 모든 Zustand store는 Redux DevTools와 자동 연동
- React Query Devtools: 캐시 모니터링
- `ReactQueryDevtoolsBridge` 활용
- 캐시 스냅샷 확인
## 참고 자료
- 프로젝트 규칙: `.cursor/rules/nubble-rules.mdc`
- 코드 리뷰 템플릿: `.cursor/rules/code-review-template.mdc`
- 아키텍처 개요: `docs/refactor/architecture-overview.md`
