auto-trade/.agent/rules/master-integration.md

trigger

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 vercel-react-best-practices	sequential-thinking (복잡한 로직) 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 (의존성 분석) 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의 출력 형식대로 코드 제공
  - [가정] 섹션
  - 핵심 코드 블록
  - 한 줄 한 줄 뜯어보기
  - 작동 흐름
  - 핵심 포인트

구체적 통합 예시:

# [예시] 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 응답 템플릿 사용
  - 한글 주석
  - 플로우 다이어그램
  - 리렌더링 조건 표

통합 예시:

# [예시] 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단계] 코드 변경 없이 주석만 추가

통합 예시:

/**
 * @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로 재구현 (필요 시)

통합 예시:

# [예시] 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개 룰