342 lines
12 KiB
Markdown
342 lines
12 KiB
Markdown
---
|
||
trigger: manual
|
||
---
|
||
|
||
# 🎯 Anti-Gravity 통합 작업 지침서
|
||
|
||
이 문서는 `.agent/rules/`의 커스텀 룰과 `.agent/skills/`의 Skill들을 **상황별로 자동 조합**하여 최적의 결과를 도출하기 위한 마스터 가이드입니다.
|
||
주식 예제는 공식 한국투자증권에서 제공하는 예제를 항상 이용해서 파이선 예제 코드를 참고하여 작성합니다.
|
||
공식예제경로: .tmp\open-trading-api
|
||
공식 사이트 무조건참고해서 수정해 공식사이트는 여기야 'https://github.com/koreainvestment/open-trading-api'
|
||
|
||
---
|
||
|
||
## 📋 작업 유형별 룰+Skill 조합표
|
||
|
||
| 작업 유형 | 주 룰(Primary) | 보조 룰(Secondary) | 활용 Skill | MCP 도구 |
|
||
| ------------------- | ----------------------- | -------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------- |
|
||
| **새 기능 개발** | `builder-rule.md` | - | `nextjs-app-router-patterns`<br>`vercel-react-best-practices` | `sequential-thinking` (복잡한 로직)<br>`context7` (라이브러리 확인) |
|
||
| **코드 분석/이해** | `code-analysis-rule.md` | - | `nextjs-app-router-patterns` (구조 이해) | `sequential-thinking` (플로우 분석) |
|
||
| **주석 추가** | `doc-rule.md` | `code-analysis-rule.md` | - | - |
|
||
| **리팩토링** | `refactoring-rule.md` | `builder-rule.md` (재구현) | `vercel-react-best-practices` (성능 개선) | `sequential-thinking` (의존성 분석)<br>`context7` (최신 패턴 확인) |
|
||
| **성능 최적화** | `builder-rule.md` | `refactoring-rule.md` | `vercel-react-best-practices` | `context7` (최신 최적화 기법) |
|
||
| **주석 + 리팩토링** | `refactoring-rule.md` | `doc-rule.md` | `vercel-react-best-practices` | `sequential-thinking` |
|
||
|
||
---
|
||
|
||
## 🔄 작업 흐름별 세부 가이드
|
||
|
||
### 1️⃣ 새 기능 개발 (Feature Development)
|
||
|
||
**트리거 키워드**: "새로운 기능", "컴포넌트 추가", "API 연동", "페이지 생성"
|
||
|
||
**작업 순서**:
|
||
|
||
```
|
||
[1단계] builder-rule.md 기준으로 구조 설계
|
||
↓
|
||
[2단계] nextjs-app-router-patterns로 Next.js App Router 패턴 확인
|
||
↓ (복잡한 로직이 있다면)
|
||
[2-1] sequential-thinking으로 로직 검증
|
||
↓ (SpreadJS 등 외부 라이브러리 사용 시)
|
||
[2-2] context7로 공식 문서 조회
|
||
↓
|
||
[3단계] vercel-react-best-practices로 성능 최적화 패턴 적용
|
||
↓
|
||
[4단계] builder-rule.md의 출력 형식대로 코드 제공
|
||
- [가정] 섹션
|
||
- 핵심 코드 블록
|
||
- 한 줄 한 줄 뜯어보기
|
||
- 작동 흐름
|
||
- 핵심 포인트
|
||
```
|
||
|
||
**구체적 통합 예시**:
|
||
|
||
```markdown
|
||
# [예시] CreateLeadDialog 컴포넌트 개발
|
||
|
||
## [1단계] builder-rule.md 적용
|
||
|
||
- Tech Stack 확인: Next.js 15.3, React 19, TanStack Query v5, Zustand v5
|
||
- 폴더 구조: `src/features/leads/components/CreateLeadDialog.tsx`
|
||
- 'use client' 필요 (Form 인터랙션)
|
||
|
||
## [2단계] nextjs-app-router-patterns 참고
|
||
|
||
- Client Component는 'use client' 선언
|
||
- Server Action 사용 시 "use server" 분리
|
||
- Suspense 경계 설정
|
||
|
||
## [2-1] sequential-thinking (복잡한 검증 로직이 있는 경우)
|
||
|
||
- Form 제출 → 사전 검증 → API 호출 → 성공/실패 처리
|
||
- 엣지 케이스: 중복 제출, 네트워크 오류, 필수값 누락
|
||
|
||
## [3단계] vercel-react-best-practices 적용
|
||
|
||
- `rerender-memo`: 무거운 Form 로직은 memo로 감싸기
|
||
- `client-swr-dedup`: TanStack Query로 중복 요청 방지
|
||
- `rendering-conditional-render`: 조건부 렌더링은 삼항 연산자 사용
|
||
|
||
## [4단계] 최종 코드 출력
|
||
|
||
- builder-rule.md의 출력 형식 준수
|
||
- 주석은 한글로, 작성자 'jihoon87.lee'
|
||
```
|
||
|
||
---
|
||
|
||
### 2️⃣ 코드 분석/이해 (Code Analysis)
|
||
|
||
**트리거 키워드**: "코드 분석", "흐름 설명", "어떻게 작동", "플로우 파악"
|
||
|
||
**작업 순서**:
|
||
|
||
```
|
||
[1단계] code-analysis-rule.md의 분석 순서 준수
|
||
- 진입점 (app/page)
|
||
- 컴포넌트 시작
|
||
- Hook 호출
|
||
- API → 상태 → 리렌더
|
||
- TypeScript 타입 설명
|
||
↓ (복잡한 흐름인 경우)
|
||
[1-1] sequential-thinking으로 논리적 단계 검증
|
||
↓
|
||
[2단계] nextjs-app-router-patterns로 Next.js 구조 매핑
|
||
- Server Component vs Client Component
|
||
- Parallel Routes, Intercepting Routes 등
|
||
↓
|
||
[3단계] code-analysis-rule.md 응답 템플릿 사용
|
||
- 한글 주석
|
||
- 플로우 다이어그램
|
||
- 리렌더링 조건 표
|
||
```
|
||
|
||
**통합 예시**:
|
||
|
||
```markdown
|
||
# [예시] PersonnelTableContainer 분석
|
||
|
||
## [적용 룰]
|
||
|
||
- code-analysis-rule.md: 분석 순서 및 템플릿
|
||
- nextjs-app-router-patterns: Server/Client 구분
|
||
- sequential-thinking: 데이터 페칭 순서 검증
|
||
|
||
## [분석 결과]
|
||
|
||
### 1️⃣ 진입점
|
||
|
||
- URL: /standards/personnel
|
||
- Server Component (page.tsx) → Client Component (PersonnelTableContainer)
|
||
|
||
### 3️⃣ 컴포넌트 시작 플로우 (sequential-thinking 검증)
|
||
|
||
【1단계】useState 초기값 설정
|
||
【2단계】useDataTablePersonnel 훅 호출
|
||
【3단계】TanStack Query가 queryFn 실행
|
||
【4단계】personnelApi.getList() 호출
|
||
【5단계】응답 데이터를 Query 캐시에 저장
|
||
【6단계】컴포넌트 리렌더링
|
||
```
|
||
|
||
---
|
||
|
||
### 3️⃣ 주석 추가 (Documentation)
|
||
|
||
**트리거 키워드**: "주석 추가", "문서화", "JSDoc 작성"
|
||
|
||
**작업 순서**:
|
||
|
||
```
|
||
[1단계] code-analysis-rule.md로 코드 흐름 파악
|
||
↓
|
||
[2단계] doc-rule.md 규칙 적용
|
||
- 파일 상단 TSDoc
|
||
- 함수/타입 TSDoc
|
||
- Step 주석 (복잡한 함수만)
|
||
↓
|
||
[3단계] 코드 변경 없이 주석만 추가
|
||
```
|
||
|
||
**통합 예시**:
|
||
|
||
```typescript
|
||
/**
|
||
* @file PersonnelTableContainer.tsx
|
||
* @description 인사 기준정보 목록 조회 및 관리 컨테이너
|
||
* @author jihoon87.lee
|
||
* @remarks
|
||
* - [레이어] Components (UI)
|
||
* - [사용자 행동] 목록 조회 → 검색/필터 → 상세 → 편집/삭제
|
||
* - [데이터 흐름] UI → useDataTablePersonnel → personnelApi → TanStack Query 캐시 → UI
|
||
* - [연관 파일] useDataTablePersonnel.ts, personnelApi.ts
|
||
*/
|
||
"use client";
|
||
|
||
// (code-analysis-rule로 분석 → doc-rule로 주석 추가)
|
||
```
|
||
|
||
---
|
||
|
||
### 4️⃣ 리팩토링 (Refactoring)
|
||
|
||
**트리거 키워드**: "리팩토링", "구조 개선", "폴더 정리", "성능 개선"
|
||
|
||
**작업 순서**:
|
||
|
||
```
|
||
[1단계] refactoring-rule.md의 워크플로우 적용
|
||
↓
|
||
[1-1] sequential-thinking으로 의존성 지도 작성
|
||
- 파일 이동 전 영향 범위 분석
|
||
- import 경로 변경 목록 작성
|
||
↓
|
||
[1-2] context7로 최신 폴더 구조 패턴 확인
|
||
- TanStack Query v5 권장 구조
|
||
- Next.js 15 App Router 최적화
|
||
↓
|
||
[2단계] refactoring-rule.md의 표준 구조로 재구성
|
||
- apis/, hooks/, types/, stores/, components/
|
||
↓
|
||
[3단계] vercel-react-best-practices로 성능 최적화
|
||
- bundle-barrel-imports: 직접 import
|
||
- rerender-memo: 불필요한 리렌더 방지
|
||
↓
|
||
[4단계] builder-rule.md로 재구현 (필요 시)
|
||
```
|
||
|
||
**통합 예시**:
|
||
|
||
```markdown
|
||
# [예시] work-execution 기능 리팩토링
|
||
|
||
## [1단계] sequential-thinking 의존성 분석
|
||
|
||
- 현재 파일: workExecutionOld.tsx (800줄, 단일 파일)
|
||
- 의존하는 외부 파일: app/standards/work-execution/page.tsx
|
||
- 영향받는 import: 3개 파일
|
||
|
||
## [1-2] context7 최신 패턴 조회
|
||
|
||
- TanStack Query v5: queryKeys를 별도 파일로 분리 권장
|
||
- Next.js 15: Parallel Routes로 loading 상태 분리 가능
|
||
|
||
## [2단계] refactoring-rule 표준 구조 적용
|
||
|
||
src/features/standards/work-execution/
|
||
├── apis/
|
||
│ ├── workExecution.api.ts
|
||
│ └── workExecutionForm.adapter.ts
|
||
├── hooks/
|
||
│ ├── queryKeys.ts
|
||
│ └── useWorkExecutionList.ts
|
||
├── types/
|
||
│ └── workExecution.types.ts
|
||
├── stores/
|
||
│ └── workExecutionStore.ts
|
||
└── components/
|
||
├── WorkExecutionContainer.tsx
|
||
└── WorkExecutionModal.tsx
|
||
|
||
## [3단계] vercel-react-best-practices 적용
|
||
|
||
- bundle-barrel-imports: index.ts 제거, 직접 경로 사용
|
||
- rerender-memo: WorkExecutionModal을 React.memo로 감싸기
|
||
- async-parallel: API 호출을 Promise.all로 병렬화
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ MCP 도구 활용 가이드
|
||
|
||
### Sequential Thinking 사용 시점
|
||
|
||
1. **복잡한 비즈니스 로직 구현 전**
|
||
- 예: 다단계 Form 검증, 복잡한 상태 머신
|
||
- 목적: 엣지 케이스 사전 도출
|
||
|
||
2. **리팩토링 시 의존성 분석**
|
||
- 예: 파일 이동 시 영향 범위 파악
|
||
- 목적: Broken Import 방지
|
||
|
||
3. **코드 분석 시 데이터 플로우 검증**
|
||
- 예: 브라우저 렌더링 단계, 데이터 페칭 순서
|
||
- 목적: 논리적 흐름 명확화
|
||
|
||
### Context7 사용 시점
|
||
|
||
1. **외부 라이브러리 최신 API 확인**
|
||
- 예: SpreadJS v18, TanStack Query v5
|
||
- 목적: 공식 문서 기반 정확한 구현
|
||
|
||
2. **리팩토링 시 최신 패턴 확인**
|
||
- 예: Next.js 15 App Router 권장 구조
|
||
- 목적: 최신 표준과 프로젝트 룰 결합
|
||
|
||
3. **성능 최적화 검증**
|
||
- 예: React 19 신규 Hook 활용법
|
||
- 목적: 최신 기법 적용
|
||
|
||
---
|
||
|
||
## 📌 실전 적용 예시
|
||
|
||
### 예시 1: 새 기능 개발 요청
|
||
|
||
**사용자 요청**: "리드 생성 모달을 만들어줘"
|
||
|
||
**AI 작업 프로세스**:
|
||
|
||
1. `builder-rule.md` 로드 → Tech Stack 확인
|
||
2. `nextjs-app-router-patterns` 참고 → Client Component 패턴 확인
|
||
3. `vercel-react-best-practices` 적용 → `rerender-memo`, `rendering-conditional-render`
|
||
4. `builder-rule.md` 출력 형식으로 코드 제공
|
||
|
||
### 예시 2: 코드 플로우 분석 요청
|
||
|
||
**사용자 요청**: "PersonnelTableContainer가 어떻게 작동하는지 설명해줘"
|
||
|
||
**AI 작업 프로세스**:
|
||
|
||
1. `code-analysis-rule.md` 로드 → 분석 순서 준수
|
||
2. `sequential-thinking` 사용 → 데이터 페칭 순서 검증
|
||
3. `nextjs-app-router-patterns` 참고 → Server/Client 구분 설명
|
||
4. `code-analysis-rule.md` 템플릿으로 결과 출력
|
||
|
||
### 예시 3: 리팩토링 요청
|
||
|
||
**사용자 요청**: "work-execution 폴더를 정리해줘"
|
||
|
||
**AI 작업 프로세스**:
|
||
|
||
1. `refactoring-rule.md` 로드 → 워크플로우 확인
|
||
2. `sequential-thinking` 사용 → 의존성 지도 작성
|
||
3. `context7` 조회 → TanStack Query v5 권장 구조 확인
|
||
4. `refactoring-rule.md` 표준 구조로 재구성
|
||
5. `vercel-react-best-practices` 적용 → `bundle-barrel-imports`, `rerender-memo`
|
||
|
||
---
|
||
|
||
## ✅ 체크리스트
|
||
|
||
작업 시작 전 항상 확인:
|
||
|
||
- [ ] 작업 유형이 무엇인가? (개발/분석/주석/리팩토링)
|
||
- [ ] 주 룰(Primary)과 보조 룰(Secondary)은?
|
||
- [ ] 어떤 Skill을 참고해야 하는가?
|
||
- [ ] MCP 도구(sequential-thinking, context7)가 필요한가?
|
||
- [ ] 출력 형식은 어떤 룰을 따르는가?
|
||
|
||
---
|
||
|
||
## 🎓 학습 자료
|
||
|
||
- **builder-rule.md**: Tech Stack, 코딩 원칙, 출력 형식
|
||
- **code-analysis-rule.md**: 분석 순서, TypeScript 타입 설명
|
||
- **doc-rule.md**: TSDoc 형식, Step 주석 규칙
|
||
- **refactoring-rule.md**: 폴더 구조, 워크플로우
|
||
- **nextjs-app-router-patterns**: Next.js 패턴, Server/Client 구분
|
||
- **vercel-react-best-practices**: 성능 최적화 57개 룰
|