---
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개 룰