들어가기 전

SKILL.md 내용을 파악하기 전에 알아둬야 할 핵심 개념을 정리한다.

Waterfall이란?

Waterfall(폭포수)은 비동기 작업들이 순차적으로 실행되어 발생하는 성능 병목 현상이다. 하나의 작업이 끝나야 다음 작업이 시작되는 구조로, 마치 폭포수가 위에서 아래로 떨어지는 모양과 같다.

❌ Waterfall (순차 실행)
A ─────────▶
            B ─────────▶
                        C ─────────▶
총 시간: A + B + C = 3초

✅ Parallel (병렬 실행)
A ─────────▶
B ─────────▶
C ─────────▶
총 시간: max(A, B, C) = 1초

예를 들어, 사용자 정보 / 주문 내역 / 알림 목록을 각각 1초씩 걸리는 API로 가져온다면:

이것이 "Waterfalls 제거"가 CRITICAL 영향도로 분류된 이유다

아래는 SKILL.md의 본문 번역입니다.

Vercel React Best Practices

Vercel이 관리하는 React 및 Next.js 애플리케이션을 위한 종합 성능 최적화 가이드. 8개 카테고리에 걸쳐 45개의 rules를 포함하며, 자동화된 리팩토링과 코드 생성을 안내하기 위해 영향도별로 우선순위가 매겨져 있습니다.

When to Apply (적용 시점)

다음 상황에서 이 가이드라인을 참고하세요:

• 새로운 React components나 Next.js pages 작성 시
• Data fetching 구현 시 (client 또는 server-side)
• 성능 이슈를 위한 코드 리뷰 시
• 기존 React/Next.js 코드 리팩토링 시
• Bundle size나 load times 최적화 시

Rule Categories by Priority (우선순위별 Rule 카테고리)

Quick Reference (빠른 참조)

1. Waterfalls 제거 (CRITICAL)

• async-defer-await - await를 실제로 사용되는 분기로 이동
• async-parallel - 독립적인 작업에 Promise.all() 사용
• async-dependencies - 부분적 의존성에 better-all 사용
• async-api-routes - API routes에서 promises를 일찍 시작하고 늦게 await
• async-suspense-boundaries - 콘텐츠 스트리밍을 위해 Suspense 사용

2. Bundle Size 최적화 (CRITICAL)

• bundle-barrel-imports - barrel files 피하고 직접 import
• bundle-dynamic-imports - 무거운 components에 next/dynamic 사용
• bundle-defer-third-party - analytics/logging은 hydration 이후 로드
• bundle-conditional - 기능이 활성화될 때만 modules 로드
• bundle-preload - 체감 속도를 위해 hover/focus 시 preload

3. Server-Side 성능 (HIGH)

• server-cache-react - 요청별 중복 제거를 위해 React.cache() 사용
• server-cache-lru - 요청 간 캐싱을 위해 LRU cache 사용
• server-serialization - client components로 전달되는 데이터 최소화
• server-parallel-fetching - fetches를 병렬화하도록 components 재구성
• server-after-nonblocking - non-blocking 작업에 after() 사용

4. Client-Side Data Fetching (MEDIUM-HIGH)

• client-swr-dedup - 자동 요청 중복 제거를 위해 SWR 사용
• client-event-listeners - 전역 event listeners 중복 제거

5. Re-render 최적화 (MEDIUM)

• rerender-defer-reads - callbacks에서만 사용되는 state를 subscribe하지 않기
• rerender-memo - 비용이 큰 작업을 memoized components로 추출
• rerender-dependencies - effects에서 primitive dependencies 사용
• rerender-derived-state - raw values 대신 derived booleans를 subscribe
• rerender-functional-setstate - stable callbacks를 위해 functional setState 사용
• rerender-lazy-state-init - 비용이 큰 값에는 useState에 function 전달
• rerender-transitions - 긴급하지 않은 updates에 startTransition 사용

6. Rendering 성능 (MEDIUM)

• rendering-animate-svg-wrapper - SVG element가 아닌 div wrapper를 animate
• rendering-content-visibility - 긴 lists에 content-visibility 사용
• rendering-hoist-jsx - static JSX를 components 외부로 추출
• rendering-svg-precision - SVG 좌표 정밀도 줄이기
• rendering-hydration-no-flicker - client-only 데이터에 inline script 사용
• rendering-activity - show/hide에 Activity component 사용
• rendering-conditional-render - 조건부 렌더링에 && 대신 ternary 사용

7. JavaScript 성능 (LOW-MEDIUM)

• js-batch-dom-css - classes나 cssText를 통해 CSS 변경 그룹화
• js-index-maps - 반복 조회를 위해 Map 구축
• js-cache-property-access - loops에서 object properties 캐시
• js-cache-function-results - module-level Map에 function 결과 캐시
• js-cache-storage - localStorage/sessionStorage 읽기 캐시
• js-combine-iterations - 여러 filter/map을 하나의 loop로 결합
• js-length-check-first - 비용 큰 비교 전에 array length 먼저 확인
• js-early-exit - functions에서 early return
• js-hoist-regexp - RegExp 생성을 loops 외부로 hoist
• js-min-max-loop - sort 대신 loop로 min/max 구하기
• js-set-map-lookups - O(1) 조회를 위해 Set/Map 사용
• js-tosorted-immutable - 불변성을 위해 toSorted() 사용

8. Advanced Patterns (LOW)

• advanced-event-handler-refs - event handlers를 refs에 저장
• advanced-use-latest - stable callback refs를 위해 useLatest 사용

How to Use (사용 방법)

상세한 설명과 코드 예시는 개별 rule 파일을 읽으세요:

rules/async-parallel.md
rules/bundle-barrel-imports.md
rules/_sections.md

각 rule 파일에 포함된 내용:

• 왜 중요한지에 대한 간략한 설명
• 설명이 포함된 잘못된 코드 예시
• 설명이 포함된 올바른 코드 예시
• 추가 컨텍스트 및 참조

Full Compiled Document (전체 컴파일 문서)

모든 rules가 확장된 전체 가이드: AGENTS.md