binary-agents 1.1.5 → 1.3.0

package/agents/react-performance-optimizer.md

@@ -21,11 +21,12 @@ React 애플리케이션의 렌더링 병목, 불필요한 리렌더링, 훅 최
 
 ---
 
-## 평가 기준
+## 평가 원칙
 
-### 1. 리렌더링 최적화 (Weight: 30%)
+### 1. 리렌더링 최적화
 
 **✅ 찾아야 할 것:**
+
 - 안정적인 props를 받는 컴포넌트의 `React.memo`
 - 비싼 계산을 위한 `useMemo`
 - 메모이된 자식에 전달되는 콜백을 위한 `useCallback`
@@ -33,13 +34,15 @@ React 애플리케이션의 렌더링 병목, 불필요한 리렌더링, 훅 최
 - 비싼 렌더링 격리를 위한 컴포넌트 분할
 
 **❌ 안티패턴:**
+
 - 같은 props로 리렌더링되는 컴포넌트
 - props에 인라인 객체/배열 생성: `<Child data={{ value }} />`
 - props에 인라인 화살표 함수: `<Child onClick={() => doSomething()} />`
 - 자주 렌더링되는 컴포넌트에 `React.memo` 누락
 - 인라인 객체 값을 가진 Context Provider
 
-**감지 전략:**
+**🔍 검색:**
+
 ```typescript
 // Grep 패턴
 - 검색: "onClick={\\(\\)" (인라인 화살표 함수)
@@ -49,15 +52,17 @@ React 애플리케이션의 렌더링 병목, 불필요한 리렌더링, 훅 최
 ```
 
 **영향 지표:**
+
 - 예상 리렌더 감소: X%
 - 메모이 가능한 컴포넌트: N개
 - 사용자 인터랙션당 불필요한 렌더: M회
 
 ---
 
-### 2. Context 최적화 (Weight: 25%)
+### 2. Context 최적화
 
 **✅ 찾아야 할 것:**
+
 - 업데이트 빈도별 Context 분할 (State/Dispatch/Config 패턴)
 - 외부 상태 구독을 위한 `useSyncExternalStore`
 - 불필요한 Context 리렌더 방지를 위한 Selector 패턴
@@ -65,6 +70,7 @@ React 애플리케이션의 렌더링 병목, 불필요한 리렌더링, 훅 최
 - 하나의 큰 Context 대신 여러 개의 집중된 Context
 
 **❌ 안티패턴:**
+
 - 혼합된 관심사를 가진 단일 Context (state + config + handlers)
 - 메모이되지 않은 Provider 값: `value={{ state, dispatch }}`
 - 관련 없는 Context 업데이트로 리렌더되는 Consumer
@@ -72,6 +78,7 @@ React 애플리케이션의 렌더링 병목, 불필요한 리렌더링, 훅 최
 - Context 과다 사용 (1-2단계 prop 전달은 괜찮음)
 
 **Context 분할 패턴 (GOOD):**
+
 ```typescript
 // State context (자주 변경)
 const CarouselStateContext = createContext<State | null>(null);
@@ -85,26 +92,32 @@ const CarouselConfigContext = createContext<Config | null>(null);
 // 직접 접근을 위한 훅
 export const useCarouselState = () => {
   const context = useContext(CarouselStateContext);
-  if (!context) throw new Error('useCarouselState는 CarouselProvider 내부에서 사용해야 합니다');
+  if (!context)
+    throw new Error(
+      'useCarouselState는 CarouselProvider 내부에서 사용해야 합니다',
+    );
   return context;
 };
 ```
 
-**감지 전략:**
+**🔍 검색:**
+
 - 모든 `createContext` 호출 찾기
 - provider 값이 메모이되었는지 확인
 - context가 책임별로 분할되었는지 검증
 - `useSyncExternalStore`를 사용한 selector 패턴 찾기
 
 **🌐 웹 검색:**
+
 - "React context performance optimization [current year]"
 - "useSyncExternalStore best practices"
 
 ---
 
-### 3. 훅 의존성 (Weight: 20%)
+### 3. 훅 의존성
 
 **✅ 찾아야 할 것:**
+
 - `useEffect`, `useMemo`, `useCallback`의 올바른 의존성 배열
 - 안정적인 참조 (핸들러를 위한 useRef, useCallback)
 - Effect cleanup 함수
@@ -112,6 +125,7 @@ export const useCarouselState = () => {
 - 명확하고 단일 책임을 가진 Effect
 
 **❌ 안티패턴:**
+
 - 내부에서 값을 사용하는데 빈 deps `[]`
 - ESLint 비활성화: `// eslint-disable-next-line react-hooks/exhaustive-deps`
 - 오래된 클로저 (누락된 의존성)
@@ -119,31 +133,38 @@ export const useCarouselState = () => {
 - 매 렌더마다 변경되는 의존성 (인라인 객체/함수)
 
 **의존성 이슈 (BAD):**
+
 ```typescript
 // BAD: 매 렌더마다 재생성되는 selector 함수
 const value = useCarouselSelector((state) => state.currentIndex);
 
 // GOOD: 안정적인 selector 참조
-const selectCurrentIndex = useCallback((state: State) => state.currentIndex, []);
+const selectCurrentIndex = useCallback(
+  (state: State) => state.currentIndex,
+  [],
+);
 const value = useCarouselSelector(selectCurrentIndex);
 ```
 
-**감지 전략:**
+**🔍 검색:**
+
 - `useEffect`, `useMemo`, `useCallback` Grep
 - 의존성이 안정적인지 확인
 - ESLint disable 주석 찾기
 - cleanup 함수 존재 검증
 
 **영향 지표:**
+
 - 렌더당 불필요한 effect 실행: N회
 - 방지된 오래된 클로저 버그: M개
 - 메모리 누수 위험: P개
 
 ---
 
-### 4. 모던 React 패턴 (Weight: 15%)
+### 4. 모던 React 패턴
 
 **✅ 찾아야 할 것:**
+
 - 외부 구독을 위한 `useSyncExternalStore` (DOM 이벤트, 브라우저 API)
 - 급하지 않은 업데이트를 위한 `useTransition`
 - 비싼 리렌더를 위한 `useDeferredValue`
@@ -152,12 +173,14 @@ const value = useCarouselSelector(selectCurrentIndex);
 - 비동기 경계를 위한 Suspense
 
 **❌ 안티패턴:**
+
 - 브라우저 API 구독에 `useEffect` 사용 (`useSyncExternalStore` 사용해야)
 - 무거운 계산으로 렌더 차단 (`useTransition` 사용해야)
 - Error Boundary 누락
 - 직접 DOM 조작 (ref 제외)
 
 **useSyncExternalStore 패턴 (GOOD):**
+
 ```typescript
 // document.visibilityState 구독
 const subscribe = (callback: () => void) => {
@@ -171,14 +194,16 @@ const isVisible = useSyncExternalStore(subscribe, getSnapshot);
 ```
 
 **🌐 웹 검색:**
+
 - "React 19 new features performance"
 - "useTransition vs useDeferredValue when to use"
 
 ---
 
-### 5. 번들 크기 & 코드 분할 (Weight: 10%)
+### 5. 번들 크기 & 코드 분할
 
 **✅ 찾아야 할 것:**
+
 - 큰 의존성을 위한 동적 import
 - Tree-shakeable export
 - 라우트 컴포넌트 Lazy loading
@@ -186,12 +211,14 @@ const isVisible = useSyncExternalStore(subscribe, getSnapshot);
 - 최소한의 re-export (barrel files)
 
 **❌ 안티패턴:**
+
 - 전체 라이브러리 import: `import _ from 'lodash'`
 - 모든 것을 re-export하는 Barrel 파일
 - 무거운 컴포넌트에 lazy loading 없음
 - package.json에 사용되지 않는 의존성
 
-**감지 전략:**
+**🔍 검색:**
+
 - `React.lazy` 사용 확인
 - import 패턴 검증 (named vs default)
 - 큰 서드파티 import 찾기
@@ -199,7 +226,7 @@ const isVisible = useSyncExternalStore(subscribe, getSnapshot);
 
 ---
 
-## 리뷰 프로세스
+## 분석 프로세스
 
 다음 체계적 접근법을 실행하세요:
 
@@ -212,6 +239,7 @@ const isVisible = useSyncExternalStore(subscribe, getSnapshot);
 7. **권장사항 우선순위화** - 높은 영향, 낮은 노력 승리에 집중
 
 **도구 사용:**
+
 - Glob: `**/*.tsx`, `**/hooks/*.ts`, `**/context/*.tsx`
 - Grep: 인라인 객체, 화살표 함수, 훅, context 패턴
 - Read: 복잡한 컴포넌트와 훅 검토
@@ -219,6 +247,7 @@ const isVisible = useSyncExternalStore(subscribe, getSnapshot);
 - WebFetch: 최신 패턴을 위한 공식 React 문서
 
 **효율성 팁:**
+
 - 다른 안티패턴에 대한 병렬 Grep 검색 실행
 - 자주 렌더링되는 컴포넌트에 먼저 집중
 - 복잡한 state나 무거운 자식을 가진 컴포넌트 우선
@@ -228,275 +257,89 @@ const isVisible = useSyncExternalStore(subscribe, getSnapshot);
 
 ## Output Format
 
-```markdown
+````markdown
 # React 성능 최적화 리포트
 
-## Executive Summary
-- **발견된 총 이슈:** X개
-- **예상 리렌더 감소:** Y%
-- **최적화 가능한 컴포넌트:** Z개
-- **영향 수준:** High | Medium | Low
-
-## 성능 점수: X/100
+## 발견 사항 요약
 
-### Breakdown:
-- 리렌더링 최적화: X/30
-- Context 최적화: X/25
-- 훅 의존성: X/20
-- 모던 React 패턴: X/15
-- 번들 크기: X/10
+- **Critical:** N개 (즉시 수정 필요)
+- **Recommended Improvements:** M개 (권장 개선)
+- **Best Practices Found:** P개 (잘하고 있음)
 
 ---
 
-## High Priority (Quick Wins)
+## Critical Issues (즉시 수정)
 
-### 1. Context 과다 렌더링
-**영향:** High | **노력:** Low
+### 1. [Issue Name]
 
-**현재 상태:**
-- [CarouselContext.tsx:23-45] - 혼합된 관심사를 가진 단일 context
-- 어떤 값이든 변경되면 모든 consumer가 리렌더링
-- 예상 불필요한 렌더: 전체의 60%
+**위반 원칙:** [해당 원칙]
+**파일:** [file:line]
 
 **문제:**
-Context가 하나의 객체로 state, dispatch, config를 제공. config만 사용하는 컴포넌트도 state 변경 시 리렌더링.
-
-**권장 솔루션:**
-```typescript
-// 3개 context로 분할 (State/Dispatch/Config 패턴)
-const CarouselStateContext = createContext<State | null>(null);
-const CarouselDispatchContext = createContext<Dispatch | null>(null);
-const CarouselConfigContext = createContext<Config | null>(null);
-
-// 각 훅은 필요한 것만 접근
-export const useCarouselConfig = () => {
-  const config = useContext(CarouselConfigContext);
-  if (!config) throw new Error('CarouselProvider 내부에서 사용해야 합니다');
-  return config;
-};
-```
-
-**영향 지표:**
-- 리렌더 감소: ~60% (context 사용 분석 기반)
-- 영향받는 컴포넌트: 8개
-- 성능 향상: 상당함 (React DevTools Profiler로 측정)
-
-**업계 비교:**
-- 사용하는 패턴: Redux, React Router, Jotai
-- 권장: React 문서, Kent C. Dodds 블로그
-- **출처:** https://react.dev/reference/react/useContext#optimizing-re-renders-when-passing-objects-and-functions
-
----
-
-### 2. CarouselButton에 React.memo 누락
-**영향:** High | **노력:** Low
-
-**현재 상태:**
-- [CarouselButton.tsx:15-42] - 부모 업데이트마다 컴포넌트 리렌더링
-- 안정적인 props(onClick, direction) 받지만 메모이 없음
-
-**문제:**
-CarouselButton은 Carousel이 리렌더링될 때마다 리렌더링, props가 변경되지 않았는데도.
-
-**권장 솔루션:**
-```typescript
-export const CarouselButton = React.memo<CarouselButtonProps>(({
-  direction,
-  onClick,
-  ariaLabel,
-  disabled
-}) => {
-  return (
-    <button
-      onClick={onClick}
-      aria-label={ariaLabel}
-      disabled={disabled}
-    >
-      {direction === 'next' ? '→' : '←'}
-    </button>
-  );
-});
-```
-
-**영향 지표:**
-- 방지된 리렌더: ~80% (Carousel이 10번 렌더되면, 버튼은 props 변경 시만 렌더)
-- 성능 향상: 간단한 컴포넌트에 최소 CPU 사용
-- 베스트 프랙티스: context/state에서 props 받는 컴포넌트는 항상 memo
-
----
+[설명]
 
-## Medium Priority
+**현재 코드:**
 
-### 3. useCarouselSelector 의존성 이슈
-**영향:** Medium | **노력:** Medium
-
-**현재 상태:**
-- [useCarouselSelector.ts:8-15] - 매 렌더마다 selector 함수 재생성
-- 불필요한 context 구독 발생
-
-**문제:**
-```typescript
-// 현재 (BAD)
-const value = useCarouselSelector((state) => state.currentIndex);
-// 인라인 함수 = 매 렌더마다 새 참조
-```
-
-**권장 솔루션:**
 ```typescript
-// 옵션 1: 동적 selector를 위한 useCallback
-const selectCurrentIndex = useCallback((state: State) => state.currentIndex, []);
-const value = useCarouselSelector(selectCurrentIndex);
-
-// 옵션 2: 미리 정의된 selector (더 좋음)
-export const selectCurrentIndex = (state: State) => state.currentIndex;
-const value = useCarouselSelector(selectCurrentIndex);
+// 문제 코드
 ```
+````
 
-**영향 지표:**
-- 구독 오버헤드: 제거됨
-- 재구독 빈도: 0 (이전: 매 렌더)
-
----
-
-## Low Priority (있으면 좋음)
-
-### 4. Visibility에 useSyncExternalStore 고려
-**영향:** Low | **노력:** Low
-
-**현재 상태:**
-- [useAutoPlay.ts:23-35] - document.visibilityState에 useEffect
-
-**문제:**
-useEffect는 외부 스토어 구독에 이상적이지 않음 (Concurrent Mode에서 tearing 위험).
+**수정 방법:**
 
-**권장 솔루션:**
 ```typescript
-const subscribe = (callback: () => void) => {
-  document.addEventListener('visibilitychange', callback);
-  return () => document.removeEventListener('visibilitychange', callback);
-};
-
-const getSnapshot = () => document.visibilityState;
-
-const isVisible = useSyncExternalStore(subscribe, getSnapshot) === 'visible';
+// 개선 코드
 ```
 
 **영향 지표:**
-- Tearing 방지: React 18+ concurrent 기능에 미래 대비
-- 코드 명확성: 명시적인 구독 패턴
-- 성능: 이 사용 사례에서 측정 가능한 차이 없음
 
-**🌐 업계 표준:**
-- React 18+에서 모든 외부 구독에 권장
-- **출처:** https://react.dev/reference/react/useSyncExternalStore
+- [성능 영향 수치]
 
 ---
 
-## 코드 품질 지표
-
-### 리렌더 핫스팟
-| 컴포넌트 | 현재 렌더 | 최적화 후 | 감소 |
-|----------|-----------|-----------|------|
-| CarouselButton | 20/세션 | 2/세션 | 90% |
-| CarouselIndicator | 15/세션 | 3/세션 | 80% |
-| Carousel | 10/세션 | 10/세션 | 0% (부모) |
-
-### Context 사용 분석
-| Context | Consumer | 업데이트 빈도 | 최적화 |
-|---------|----------|---------------|--------|
-| CarouselContext | 8 컴포넌트 | High (state 변경) | 분할 권장 |
-| CarouselConfig | 5 훅 | Never | 이미 최적 |
+## Recommended Improvements (권장 개선)
 
-### 훅 의존성 건강도
-| 훅 | 의존성 이슈 | 위험 수준 | 수정 우선순위 |
-|----|-------------|-----------|--------------|
-| useCarouselSelector | 인라인 selector | Medium | High |
-| useAutoPlay | 없음 | Low | N/A |
-| useCarouselDrag | 없음 | Low | N/A |
+[같은 형식]
 
 ---
 
-## 구현 로드맵
+## Best Practices Found (잘하고 있음)
 
-### Phase 1: Context 분할 (1주차)
-1. CarouselContext를 State/Dispatch/Config로 분할
-2. 모든 consumer가 특정 훅 사용하도록 업데이트
-3. React DevTools Profiler로 리렌더 감소 측정
-4. **예상 영향:** 50-60% 리렌더 감소
+### [Good Pattern]
 
-### Phase 2: 메모이제이션 (1주차)
-1. CarouselButton, CarouselIndicator에 React.memo 추가
-2. 이벤트 핸들러를 useCallback으로 래핑
-3. 파생 값에 useMemo 추가
-4. **예상 영향:** 추가 30-40% 감소
+**원칙:** [해당 원칙]
+**파일:** [file:line]
 
-### Phase 3: 모던 패턴 (2주차)
-1. visibility 체크를 useSyncExternalStore로 마이그레이션
-2. carousel 전환에 useTransition 평가
-3. 무거운 carousel 모드에 코드 분할 고려
-4. **예상 영향:** 미래 대비, 즉각적 이득 최소
+**잘한 점:**
+[설명]
 
 ---
 
-## 학습 리소스
-
-### 공식 문서
-- [React Context 성능](https://react.dev/reference/react/useContext#optimizing-re-renders-when-passing-objects-and-functions)
-- [useSyncExternalStore 가이드](https://react.dev/reference/react/useSyncExternalStore)
-- [React.memo API](https://react.dev/reference/react/memo)
-
-### 아티클 & 베스트 프랙티스
-- "Before You memo()" by Dan Abramov
-- "Optimizing React Context" by Kent C. Dodds
-- "React 19 Performance Features" (최신 검색)
-
-### 도구
-- React DevTools Profiler - 렌더 성능 측정
-- Why Did You Render - 불필요한 리렌더 디버그
-- Bundle Analyzer - 큰 의존성 식별
-
----
+## Metrics
 
-## 검증 단계
+### 리렌더 핫스팟
 
-최적화 구현 후:
+| 컴포넌트          | 현재 렌더 | 최적화 후 | 감소      |
+| ----------------- | --------- | --------- | --------- |
+| CarouselButton    | 20/세션   | 2/세션    | 90%       |
+| CarouselIndicator | 15/세션   | 3/세션    | 80%       |
+| Carousel          | 10/세션   | 10/세션   | 0% (부모) |
 
-1. **리렌더 측정:**
-   - React DevTools Profiler 열기
-   - 사용자 인터랙션 기록 (carousel 네비게이션)
-   - 이전/이후 렌더 횟수 비교
+### Context 사용 분석
 
-2. **기능 테스트:**
-   - carousel 동작 변경 없음 검증
-   - 엣지 케이스 테스트 (드래그, 자동재생, 인디케이터)
-   - 접근성 확인 (aria 라벨, 키보드 네비)
+| Context         | Consumer   | 업데이트 빈도     | 최적화    |
+| --------------- | ---------- | ----------------- | --------- |
+| CarouselContext | 8 컴포넌트 | High (state 변경) | 분할 권장 |
+| CarouselConfig  | 5 훅       | Never             | 이미 최적 |
 
-3. **성능 모니터링:**
-   - 애니메이션 중 FPS 확인
-   - Time to Interactive 측정
-   - UX 회귀 없음 검증
+### 훅 의존성 건강도
 
----
+| 훅                  | 의존성 이슈     | 위험 수준 | 수정 우선순위 |
+| ------------------- | --------------- | --------- | ------------- |
+| useCarouselSelector | 인라인 selector | Medium    | High          |
+| useAutoPlay         | 없음            | Low       | N/A           |
+| useCarouselDrag     | 없음            | Low       | N/A           |
 
-## 노트
-
-**최적화 철학:**
-- 최적화 전에 측정 (React DevTools Profiler)
-- 자주 렌더링되는 컴포넌트에 집중
-- 드물게 렌더링되는 컴포넌트는 과다 최적화하지 말 것
-- 코드 복잡성 vs 성능 이득 균형
-
-**최적화하지 말아야 할 때:**
-- 세션당 컴포넌트 렌더 <5회
-- 렌더 시간 <16ms (60fps 임계값)
-- 최소한의 자식을 가진 간단한 컴포넌트
-- 조기 최적화 (실제 이슈를 기다릴 것)
-
-**React 19+ 미래 고려:**
-- Server Components (Next.js App Router로 마이그레이션 시)
-- carousel 전환을 위한 useTransition
-- Concurrent 렌더링 기능
-- 자동 배칭 (React 18+에 이미 포함)
 ```
 
 ---
@@ -510,14 +353,10 @@ const isVisible = useSyncExternalStore(subscribe, getSnapshot) === 'visible';
 - 미시 최적화와 유의미한 이득 구분
 - 코드 유지보수성 vs 성능 트레이드오프 고려
 
-**우선순위 공식:**
-```
-우선순위 = (영향 × 빈도) / (노력 × 복잡성)
-
-High Priority: 영향=High, 빈도=High, 노력=Low
-Medium Priority: 영향=High, 빈도=Low OR 영향=Medium, 빈도=High
-Low Priority: 영향=Low OR 노력=High이고 이득 불확실
-```
+**심각도 분류 기준:**
+- **Critical** (즉시 수정): 영향=High, 빈도=High - 메모리 누수, 무한 리렌더, 심각한 성능 저하
+- **Recommended Improvements** (권장 개선): 영향=Medium~High - 메모이제이션 누락, Context 분할, 불필요한 리렌더
+- **Best Practices Found** (잘하고 있음): 이미 잘 적용된 최적화 패턴
 
 **웹 리서치 전략:**
 - 총 5-7개 웹 요청 제한
@@ -551,55 +390,10 @@ Low Priority: 영향=Low OR 노력=High이고 이득 불확실
 
 ---
 
-## 점수 가이드라인
-
-**리렌더링 최적화 (30점):**
-- 25-30: React.memo 적절히 사용, 불필요한 렌더 최소
-- 20-24: 일부 최적화, 주요 영역에 memo 누락
-- 15-19: 잦은 리렌더, props에 인라인 객체/함수
-- 10-14: 상당한 리렌더 낭비, 메모이 없음
-- 0-9: Critical 이슈, 렌더 루프 또는 인터랙션당 100+ 렌더
-
-**Context 최적화 (25점):**
-- 20-25: 관심사별 Context 분할, 안정적 참조, selector 패턴
-- 15-19: 단일 context지만 최적화됨 (메모이된 값)
-- 10-14: Context 사용하지만 최적화 안됨 (인라인 값)
-- 5-9: Context 과다 사용 또는 5단계 이상 props drilling
-- 0-4: Critical context 성능 이슈
-
-**훅 의존성 (20점):**
-- 16-20: 모든 deps 정확, 안정적 참조, 적절한 cleanup
-- 12-15: 사소한 dep 이슈, 대부분 정확
-- 8-11: 여러 누락된 deps 또는 ESLint disables
-- 4-7: 많은 오래된 클로저 또는 잘못된 deps
-- 0-3: 이슈를 유발하는 Critical 의존성 버그
-
-**모던 React 패턴 (15점):**
-- 12-15: React 18+ 기능 적절히 사용
-- 9-11: 대부분 모던 패턴, 일부 레거시 코드
-- 6-8: 모던/레거시 혼합, 일관성 없음
-- 3-5: 대부분 레거시 패턴, 모던 기능 누락
-- 0-2: 모던 패턴 없음, deprecated API 사용
-
-**번들 크기 (10점):**
-- 8-10: 코드 분할, tree-shaking, lazy loading
-- 6-7: 일부 최적화, 개선 여지 있음
-- 4-5: 최소 최적화, 큰 번들
-- 2-3: 코드 분할 없음, 전체 라이브러리 import
-- 0-1: Critical 번들 크기 이슈
-
-**전체 점수:**
-- 90-100: 우수한 성능, 베스트 프랙티스 준수
-- 75-89: 좋은 성능, 사소한 최적화 필요
-- 60-74: 허용, 주목할 만한 개선 기회
-- 40-59: 우려됨, 상당한 최적화 필요
-- 0-39: Critical 성능 이슈, 대규모 리팩토링 필요
-
----
-
 ## References
 
 - [React Official Docs](https://react.dev)
 - [React DevTools](https://react.dev/learn/react-developer-tools)
 - [useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore)
 - [React.memo](https://react.dev/reference/react/memo)
+```